1 .TH "libunbound" "3" "Mar 12, 2014" "NLnet Labs" "unbound 1.4.22"
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_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.4.22 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_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
72 \fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
75 \fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta);
78 \fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
81 \fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
84 \fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out);
87 \fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d);
90 \fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread);
93 \fBub_poll\fR(\fIstruct ub_ctx*\fR ctx);
96 \fBub_wait\fR(\fIstruct ub_ctx*\fR ctx);
99 \fBub_fd\fR(\fIstruct ub_ctx*\fR ctx);
102 \fBub_process\fR(\fIstruct ub_ctx*\fR ctx);
105 \fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
107 \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result);
110 \fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
112 \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata,
114 \fIub_callback_t\fR callback, \fIint*\fR async_id);
117 \fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id);
120 \fBub_resolve_free\fR(\fIstruct ub_result*\fR result);
123 \fBub_strerror\fR(\fIint\fR err);
126 \fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx);
129 \fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type);
132 \fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name);
135 \fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
138 \fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
142 is an implementation of a DNS resolver, that does caching and
143 DNSSEC validation. This is the library API, for using the \-lunbound library.
144 The server daemon is described in \fIunbound\fR(8).
145 The library can be used to convert hostnames to ip addresses, and back,
146 and obtain other information from the DNS. The library performs public\-key
147 validation of results with DNSSEC.
149 The library uses a variable of type \fIstruct ub_ctx\fR to keep context
150 between calls. The user must maintain it, creating it with
154 It can be created and deleted at any time. Creating it anew removes any
155 previous configuration (such as trusted keys) and clears any cached results.
157 The functions are thread\-safe, and a context an be used in a threaded (as
158 well as in a non\-threaded) environment. Also resolution (and validation)
159 can be performed blocking and non\-blocking (also called asynchronous).
160 The async method returns from the call immediately, so that processing
161 can go on, while the results become available later.
163 The functions are discussed in turn below.
167 Create a new context, initialised with defaults.
168 The information from /etc/resolv.conf and /etc/hosts is not utilised
174 Before you call this, use the openssl functions CRYPTO_set_id_callback and
175 CRYPTO_set_locking_callback to set up asyncronous operation if you use
176 lib openssl (the application calls these functions once for initialisation).
179 Delete validation context and free associated resources.
180 Outstanding async queries are killed and callbacks are not called for them.
183 A power\-user interface that lets you specify one of the options from the
184 config file format, see \fIunbound.conf\fR(5). Not all options are
185 relevant. For some specific options, such as adding trust anchors, special
186 routines exist. Pass the option name with the trailing ':'.
189 A power\-user interface that gets an option value. Some options cannot be
190 gotten, and others return a newline separated list. Pass the option name
191 without trailing ':'. The returned value must be free(2)d by the caller.
194 A power\-user interface that lets you specify an unbound config file, see
195 \fIunbound.conf\fR(5), which is read for configuration. Not all options are
196 relevant. For some specific options, such as adding trust anchors, special
200 Set machine to forward DNS queries to, the caching resolver to use.
201 IP4 or IP6 address. Forwards all DNS requests to that machine, which
202 is expected to run a recursive resolver. If the proxy is not
203 DNSSEC capable, validation may fail. Can be called several times, in
204 that case the addresses are used as backup servers.
205 At this time it is only possible to set configuration before the
206 first resolve is done.
209 By default the root servers are queried and full resolver mode is used, but
210 you can use this call to read the list of nameservers to use from the
212 Usually "/etc/resolv.conf". Uses those nameservers as caching proxies.
213 If they do not support DNSSEC, validation may fail.
214 Only nameservers are picked up, the searchdomain, ndots and other
215 settings from \fIresolv.conf\fR(5) are ignored.
216 If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows,
217 the system\-wide configured nameserver is picked instead).
218 At this time it is only possible to set configuration before the
219 first resolve is done.
222 Read list of hosts from the filename given.
223 Usually "/etc/hosts". When queried for, these addresses are not marked
224 DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used
225 (if on Windows, etc/hosts from WINDIR is picked instead).
226 At this time it is only possible to set configuration before the
227 first resolve is done.
231 Add a trust anchor to the given context.
232 At this time it is only possible to add trusted keys before the
233 first resolve is done.
234 The format is a string, similar to the zone\-file format,
235 [domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted.
237 .B ub_ctx_add_ta_file
238 Add trust anchors to the given context.
239 Pass name of a file with DS and DNSKEY records in zone file format.
240 At this time it is only possible to add trusted keys before the
241 first resolve is done.
243 .B ub_ctx_trustedkeys
244 Add trust anchors to the given context.
245 Pass the name of a bind\-style config file with trusted\-keys{}.
246 At this time it is only possible to add trusted keys before the
247 first resolve is done.
250 Set debug and error log output to the given stream. Pass NULL to disable
251 output. Default is stderr. File\-names or using syslog can be enabled
252 using config options, this routine is for using your own stream.
255 Set debug verbosity for the context. Output is directed to stderr.
256 Higher debug level gives more output.
259 Set a context behaviour for asynchronous action.
260 if set to true, enables threading and a call to
262 creates a thread to handle work in the background.
263 If false, a process is forked to handle work in the background.
264 Changes to this setting after
266 calls have been made have no effect (delete and re\-create the context
270 Poll a context to see if it has any new results.
271 Do not poll in a loop, instead extract the fd below to poll for readiness,
272 and then check, or wait using the wait routine.
273 Returns 0 if nothing to read, or nonzero if a result is available.
279 Wait for a context to finish with results. Calls
281 after the wait for you. After the wait, there are no more outstanding
282 asynchronous queries.
285 Get file descriptor. Wait for it to become readable, at this point
286 answers are returned from the asynchronous validating resolver.
287 Then call the \fBub_process\fR to continue processing.
290 Call this routine to continue processing results from the validating
291 resolver (when the fd becomes readable).
292 Will perform necessary callbacks.
295 Perform resolution and validation of the target name.
296 The name is a domain name in a zero terminated text string.
297 The rrtype and rrclass are DNS type and class codes.
298 The result structure is newly allocated with the resulting data.
301 Perform asynchronous resolution and validation of the target name.
302 Arguments mean the same as for \fBub_resolve\fR except no
303 data is returned immediately, instead a callback is called later.
304 The callback receives a copy of the mydata pointer, that you can use to pass
305 information to the callback. The callback type is a function pointer to
306 a function declared as
308 void my_callback_function(void* my_arg, int err,
310 struct ub_result* result);
312 The async_id is returned so you can (at your option) decide to track it
313 and cancel the request if needed. If you pass a NULL pointer the async_id
317 Cancel an async query in progress. This may return an error if the query
318 does not exist, or the query is already being delivered, in that case you
319 may still get a callback for the query.
322 Free struct ub_result contents after use.
325 Convert error value from one of the unbound library functions
326 to a human readable string.
328 .B ub_ctx_print_local_zones
329 Debug printout the local authority information to debug output.
332 Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5)
335 .B ub_ctx_zone_remove
336 Delete zone from local authority info.
339 Add resource record data to local authority info, like local\-data
340 \fIunbound.conf\fR(5) statement.
342 .B ub_ctx_data_remove
343 Delete local authority data from the name given.
344 .SH "RESULT DATA STRUCTURE"
346 The result of the DNS resolution and validation is returned as
347 \fIstruct ub_result\fR. The result structure contains the following entries.
351 char* qname; /* text string, original question */
352 int qtype; /* type code asked for */
353 int qclass; /* class code asked for */
354 char** data; /* array of rdata items, NULL terminated*/
355 int* len; /* array with lengths of rdata items */
356 char* canonname; /* canonical name of result */
357 int rcode; /* additional error code in case of no data */
358 void* answer_packet; /* full network format answer packet */
359 int answer_len; /* length of packet in octets */
360 int havedata; /* true if there is data */
361 int nxdomain; /* true if nodata because name does not exist */
362 int secure; /* true if result is secure */
363 int bogus; /* true if a security failure happened */
364 char* why_bogus; /* string with error if bogus */
365 int ttl; /* number of seconds the result is valid */
369 If both secure and bogus are false, security was not enabled for the
370 domain of the query. Else, they are not both true, one of them is true.
372 Many routines return an error code. The value 0 (zero) denotes no error
373 happened. Other values can be passed to
375 to obtain a readable error string.
377 returns a zero terminated string.
379 returns NULL on an error (a malloc failure).
381 returns true if some information may be available, false otherwise.
383 returns a file descriptor or \-1 on error.
385 \fIunbound.conf\fR(5),
389 developers are mentioned in the CREDITS file in the distribution.