1 .TH "libunbound" "3" "Jul 11, 2022" "NLnet Labs" "unbound 1.16.1"
3 .\" libunbound.3 -- unbound library functions manual
5 .\" Copyright (c) 2007, NLnet Labs. All rights reserved.
7 .\" See LICENSE for the license.
27 .B ub_ctx_add_ta_autr,
28 .B ub_ctx_add_ta_file,
29 .B ub_ctx_trustedkeys,
42 .B ub_ctx_print_local_zones,
44 .B ub_ctx_zone_remove,
47 \- Unbound DNS validating resolver 1.16.1 functions.
49 .B #include <unbound.h>
52 \fBub_ctx_create\fR(\fIvoid\fR);
55 \fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx);
58 \fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val);
61 \fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val);
64 \fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
67 \fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr);
70 \fBub_ctx_set_stub\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone,
76 \fBub_ctx_set_tls\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR tls);
79 \fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
82 \fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
85 \fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta);
88 \fBub_ctx_add_ta_autr\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
91 \fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
94 \fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
97 \fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out);
100 \fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d);
103 \fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread);
106 \fBub_poll\fR(\fIstruct ub_ctx*\fR ctx);
109 \fBub_wait\fR(\fIstruct ub_ctx*\fR ctx);
112 \fBub_fd\fR(\fIstruct ub_ctx*\fR ctx);
115 \fBub_process\fR(\fIstruct ub_ctx*\fR ctx);
118 \fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
120 \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result);
123 \fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
125 \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata,
127 \fIub_callback_type\fR callback, \fIint*\fR async_id);
130 \fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id);
133 \fBub_resolve_free\fR(\fIstruct ub_result*\fR result);
136 \fBub_strerror\fR(\fIint\fR err);
139 \fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx);
142 \fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type);
145 \fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name);
148 \fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
151 \fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
154 is an implementation of a DNS resolver, that does caching and
155 DNSSEC validation. This is the library API, for using the \-lunbound library.
156 The server daemon is described in \fIunbound\fR(8).
157 The library works independent from a running unbound server, and
158 can be used to convert hostnames to ip addresses, and back,
159 and obtain other information from the DNS. The library performs public\-key
160 validation of results with DNSSEC.
162 The library uses a variable of type \fIstruct ub_ctx\fR to keep context
163 between calls. The user must maintain it, creating it with
167 It can be created and deleted at any time. Creating it anew removes any
168 previous configuration (such as trusted keys) and clears any cached results.
170 The functions are thread\-safe, and a context can be used in a threaded (as
171 well as in a non\-threaded) environment. Also resolution (and validation)
172 can be performed blocking and non\-blocking (also called asynchronous).
173 The async method returns from the call immediately, so that processing
174 can go on, while the results become available later.
176 The functions are discussed in turn below.
180 Create a new context, initialised with defaults.
181 The information from /etc/resolv.conf and /etc/hosts is not utilised
187 Before you call this, use the openssl functions CRYPTO_set_id_callback and
188 CRYPTO_set_locking_callback to set up asynchronous operation if you use
189 lib openssl (the application calls these functions once for initialisation).
190 Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function.
193 Delete validation context and free associated resources.
194 Outstanding async queries are killed and callbacks are not called for them.
197 A power\-user interface that lets you specify one of the options from the
198 config file format, see \fIunbound.conf\fR(5). Not all options are
199 relevant. For some specific options, such as adding trust anchors, special
200 routines exist. Pass the option name with the trailing ':'.
203 A power\-user interface that gets an option value. Some options cannot be
204 gotten, and others return a newline separated list. Pass the option name
205 without trailing ':'. The returned value must be free(2)d by the caller.
208 A power\-user interface that lets you specify an unbound config file, see
209 \fIunbound.conf\fR(5), which is read for configuration. Not all options are
210 relevant. For some specific options, such as adding trust anchors, special
211 routines exist. This function is thread\-safe only if a single instance of
212 ub_ctx* exists in the application. If several instances exist the
213 application has to ensure that ub_ctx_config is not called in parallel by
214 the different instances.
217 Set machine to forward DNS queries to, the caching resolver to use.
218 IP4 or IP6 address. Forwards all DNS requests to that machine, which
219 is expected to run a recursive resolver. If the proxy is not
220 DNSSEC capable, validation may fail. Can be called several times, in
221 that case the addresses are used as backup servers.
222 At this time it is only possible to set configuration before the
223 first resolve is done.
226 Set a stub zone, authoritative dns servers to use for a particular zone.
227 IP4 or IP6 address. If the address is NULL the stub entry is removed.
228 Set isprime true if you configure root hints with it. Otherwise similar to
229 the stub zone item from unbound's config file. Can be called several times,
230 for different zones, or to add multiple addresses for a particular zone.
231 At this time it is only possible to set configuration before the
232 first resolve is done.
235 Enable DNS over TLS (DoT) for machines set with
237 At this time it is only possible to set configuration before the
238 first resolve is done.
241 By default the root servers are queried and full resolver mode is used, but
242 you can use this call to read the list of nameservers to use from the
244 Usually "/etc/resolv.conf". Uses those nameservers as caching proxies.
245 If they do not support DNSSEC, validation may fail.
246 Only nameservers are picked up, the searchdomain, ndots and other
247 settings from \fIresolv.conf\fR(5) are ignored.
248 If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows,
249 the system\-wide configured nameserver is picked instead).
250 At this time it is only possible to set configuration before the
251 first resolve is done.
254 Read list of hosts from the filename given.
255 Usually "/etc/hosts". When queried for, these addresses are not marked
256 DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used
257 (if on Windows, etc/hosts from WINDIR is picked instead).
258 At this time it is only possible to set configuration before the
259 first resolve is done.
263 Add a trust anchor to the given context.
264 At this time it is only possible to add trusted keys before the
265 first resolve is done.
266 The format is a string, similar to the zone\-file format,
267 [domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted.
269 .B ub_ctx_add_ta_autr
270 Add filename with automatically tracked trust anchor to the given context.
271 Pass name of a file with the managed trust anchor. You can create this
272 file with \fIunbound\-anchor\fR(8) for the root anchor. You can also
273 create it with an initial file with one line with a DNSKEY or DS record.
274 If the file is writable, it is updated when the trust anchor changes.
275 At this time it is only possible to add trusted keys before the
276 first resolve is done.
278 .B ub_ctx_add_ta_file
279 Add trust anchors to the given context.
280 Pass name of a file with DS and DNSKEY records in zone file format.
281 At this time it is only possible to add trusted keys before the
282 first resolve is done.
284 .B ub_ctx_trustedkeys
285 Add trust anchors to the given context.
286 Pass the name of a bind\-style config file with trusted\-keys{}.
287 At this time it is only possible to add trusted keys before the
288 first resolve is done.
291 Set debug and error log output to the given stream. Pass NULL to disable
292 output. Default is stderr. File\-names or using syslog can be enabled
293 using config options, this routine is for using your own stream.
296 Set debug verbosity for the context. Output is directed to stderr.
297 Higher debug level gives more output.
300 Set a context behaviour for asynchronous action.
301 if set to true, enables threading and a call to
303 creates a thread to handle work in the background.
304 If false, a process is forked to handle work in the background.
305 Changes to this setting after
307 calls have been made have no effect (delete and re\-create the context
311 Poll a context to see if it has any new results.
312 Do not poll in a loop, instead extract the fd below to poll for readiness,
313 and then check, or wait using the wait routine.
314 Returns 0 if nothing to read, or nonzero if a result is available.
320 Wait for a context to finish with results. Calls
322 after the wait for you. After the wait, there are no more outstanding
323 asynchronous queries.
326 Get file descriptor. Wait for it to become readable, at this point
327 answers are returned from the asynchronous validating resolver.
328 Then call the \fBub_process\fR to continue processing.
331 Call this routine to continue processing results from the validating
332 resolver (when the fd becomes readable).
333 Will perform necessary callbacks.
336 Perform resolution and validation of the target name.
337 The name is a domain name in a zero terminated text string.
338 The rrtype and rrclass are DNS type and class codes.
339 The result structure is newly allocated with the resulting data.
342 Perform asynchronous resolution and validation of the target name.
343 Arguments mean the same as for \fBub_resolve\fR except no
344 data is returned immediately, instead a callback is called later.
345 The callback receives a copy of the mydata pointer, that you can use to pass
346 information to the callback. The callback type is a function pointer to
347 a function declared as
349 void my_callback_function(void* my_arg, int err,
351 struct ub_result* result);
353 The async_id is returned so you can (at your option) decide to track it
354 and cancel the request if needed. If you pass a NULL pointer the async_id
358 Cancel an async query in progress. This may return an error if the query
359 does not exist, or the query is already being delivered, in that case you
360 may still get a callback for the query.
363 Free struct ub_result contents after use.
366 Convert error value from one of the unbound library functions
367 to a human readable string.
369 .B ub_ctx_print_local_zones
370 Debug printout the local authority information to debug output.
373 Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5)
376 .B ub_ctx_zone_remove
377 Delete zone from local authority info.
380 Add resource record data to local authority info, like local\-data
381 \fIunbound.conf\fR(5) statement.
383 .B ub_ctx_data_remove
384 Delete local authority data from the name given.
385 .SH "RESULT DATA STRUCTURE"
386 The result of the DNS resolution and validation is returned as
387 \fIstruct ub_result\fR. The result structure contains the following entries.
391 char* qname; /* text string, original question */
392 int qtype; /* type code asked for */
393 int qclass; /* class code asked for */
394 char** data; /* array of rdata items, NULL terminated*/
395 int* len; /* array with lengths of rdata items */
396 char* canonname; /* canonical name of result */
397 int rcode; /* additional error code in case of no data */
398 void* answer_packet; /* full network format answer packet */
399 int answer_len; /* length of packet in octets */
400 int havedata; /* true if there is data */
401 int nxdomain; /* true if nodata because name does not exist */
402 int secure; /* true if result is secure */
403 int bogus; /* true if a security failure happened */
404 char* why_bogus; /* string with error if bogus */
405 int was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */
406 int ttl; /* number of seconds the result is valid */
410 If both secure and bogus are false, security was not enabled for the
411 domain of the query. Else, they are not both true, one of them is true.
413 Many routines return an error code. The value 0 (zero) denotes no error
414 happened. Other values can be passed to
416 to obtain a readable error string.
418 returns a zero terminated string.
420 returns NULL on an error (a malloc failure).
422 returns true if some information may be available, false otherwise.
424 returns a file descriptor or \-1 on error.
428 attempt to leave errno informative on a function return with file read failure.
430 \fIunbound.conf\fR(5),
434 developers are mentioned in the CREDITS file in the distribution.