contrib/unbound/doc/libunbound.3.in

   1 .TH "libunbound" "3" "May  3, 2018" "NLnet Labs" "unbound 1.7.1"
   2 .\"
   3 .\" libunbound.3 -- unbound library functions manual
   4 .\"
   5 .\" Copyright (c) 2007, NLnet Labs. All rights reserved.
   6 .\"
   7 .\" See LICENSE for the license.
   8 .\"
   9 .\"
  10 .SH "NAME"
  11 .B libunbound,
  12 .B unbound.h,
  13 .B ub_ctx,
  14 .B ub_result,
  15 .B ub_callback_type,
  16 .B ub_ctx_create,
  17 .B ub_ctx_delete,
  18 .B ub_ctx_set_option,
  19 .B ub_ctx_get_option,
  20 .B ub_ctx_config,
  21 .B ub_ctx_set_fwd,
  22 .B ub_ctx_set_stub,
  23 .B ub_ctx_resolvconf,
  24 .B ub_ctx_hosts,
  25 .B ub_ctx_add_ta,
  26 .B ub_ctx_add_ta_autr,
  27 .B ub_ctx_add_ta_file,
  28 .B ub_ctx_trustedkeys,
  29 .B ub_ctx_debugout,
  30 .B ub_ctx_debuglevel,
  31 .B ub_ctx_async,
  32 .B ub_poll,
  33 .B ub_wait,
  34 .B ub_fd,
  35 .B ub_process,
  36 .B ub_resolve,
  37 .B ub_resolve_async,
  38 .B ub_cancel,
  39 .B ub_resolve_free,
  40 .B ub_strerror,
  41 .B ub_ctx_print_local_zones,
  42 .B ub_ctx_zone_add,
  43 .B ub_ctx_zone_remove,
  44 .B ub_ctx_data_add,
  45 .B ub_ctx_data_remove
  46 \- Unbound DNS validating resolver 1.7.1 functions.
  47 .SH "SYNOPSIS"
  48 .B #include <unbound.h>
  49 .LP
  50 \fIstruct ub_ctx *\fR
  51 \fBub_ctx_create\fR(\fIvoid\fR);
  52 .LP
  53 \fIvoid\fR
  54 \fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx);
  55 .LP
  56 \fIint\fR
  57 \fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val);
  58 .LP
  59 \fIint\fR
  60 \fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val);
  61 .LP
  62 \fIint\fR
  63 \fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  64 .LP
  65 \fIint\fR
  66 \fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr);
  67 .LP
  68 \fIint\fR
  69 \fBub_ctx_set_stub\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone,
  70 \fIchar*\fR addr,
  71 .br
  72                 \fIint\fR isprime);
  73 .LP
  74 \fIint\fR
  75 \fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  76 .LP
  77 \fIint\fR
  78 \fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  79 .LP
  80 \fIint\fR
  81 \fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta);
  82 .LP
  83 \fIint\fR
  84 \fBub_ctx_add_ta_autr\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  85 .LP
  86 \fIint\fR
  87 \fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  88 .LP
  89 \fIint\fR
  90 \fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  91 .LP
  92 \fIint\fR
  93 \fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out);
  94 .LP
  95 \fIint\fR
  96 \fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d);
  97 .LP
  98 \fIint\fR
  99 \fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread);
 100 .LP
 101 \fIint\fR
 102 \fBub_poll\fR(\fIstruct ub_ctx*\fR ctx);
 103 .LP
 104 \fIint\fR
 105 \fBub_wait\fR(\fIstruct ub_ctx*\fR ctx);
 106 .LP
 107 \fIint\fR
 108 \fBub_fd\fR(\fIstruct ub_ctx*\fR ctx);
 109 .LP
 110 \fIint\fR
 111 \fBub_process\fR(\fIstruct ub_ctx*\fR ctx);
 112 .LP
 113 \fIint\fR
 114 \fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
 115 .br
 116            \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result);
 117 .LP
 118 \fIint\fR
 119 \fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
 120 .br
 121                  \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata,
 122 .br
 123                  \fIub_callback_type\fR callback, \fIint*\fR async_id);
 124 .LP
 125 \fIint\fR
 126 \fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id);
 127 .LP
 128 \fIvoid\fR
 129 \fBub_resolve_free\fR(\fIstruct ub_result*\fR result);
 130 .LP
 131 \fIconst char *\fR
 132 \fBub_strerror\fR(\fIint\fR err);
 133 .LP
 134 \fIint\fR
 135 \fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx);
 136 .LP
 137 \fIint\fR
 138 \fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type);
 139 .LP
 140 \fIint\fR
 141 \fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name);
 142 .LP
 143 \fIint\fR
 144 \fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
 145 .LP
 146 \fIint\fR
 147 \fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
 148 .SH "DESCRIPTION"
 149 .B Unbound
 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 works independent from a running unbound server, and
 154 can be used to convert hostnames to ip addresses, and back,
 155 and obtain other information from the DNS. The library performs public\-key
 156 validation of results with DNSSEC.
 157 .P
 158 The library uses a variable of type \fIstruct ub_ctx\fR to keep context
 159 between calls. The user must maintain it, creating it with
 160 .B ub_ctx_create
 161 and deleting it with
 162 .B ub_ctx_delete\fR.
 163 It can be created and deleted at any time. Creating it anew removes any
 164 previous configuration (such as trusted keys) and clears any cached results.
 165 .P
 166 The functions are thread\-safe, and a context can be used in a threaded (as
 167 well as in a non\-threaded) environment. Also resolution (and validation)
 168 can be performed blocking and non\-blocking (also called asynchronous).
 169 The async method returns from the call immediately, so that processing
 170 can go on, while the results become available later.
 171 .P
 172 The functions are discussed in turn below.
 173 .SH "FUNCTIONS"
 174 .TP
 175 .B ub_ctx_create
 176 Create a new context, initialised with defaults.
 177 The information from /etc/resolv.conf and /etc/hosts is not utilised
 178 by default. Use
 179 .B ub_ctx_resolvconf
 180 and
 181 .B ub_ctx_hosts
 182 to read them.
 183 Before you call this, use the openssl functions CRYPTO_set_id_callback and
 184 CRYPTO_set_locking_callback to set up asynchronous operation if you use
 185 lib openssl (the application calls these functions once for initialisation).
 186 Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function.
 187 .TP
 188 .B ub_ctx_delete
 189 Delete validation context and free associated resources.
 190 Outstanding async queries are killed and callbacks are not called for them.
 191 .TP
 192 .B ub_ctx_set_option
 193 A power\-user interface that lets you specify one of the options from the
 194 config file format, see \fIunbound.conf\fR(5). Not all options are
 195 relevant. For some specific options, such as adding trust anchors, special
 196 routines exist. Pass the option name with the trailing ':'.
 197 .TP
 198 .B ub_ctx_get_option
 199 A power\-user interface that gets an option value.  Some options cannot be
 200 gotten, and others return a newline separated list.  Pass the option name
 201 without trailing ':'.  The returned value must be free(2)d by the caller.
 202 .TP
 203 .B ub_ctx_config
 204 A power\-user interface that lets you specify an unbound config file, see
 205 \fIunbound.conf\fR(5), which is read for configuration. Not all options are
 206 relevant. For some specific options, such as adding trust anchors, special
 207 routines exist.  This function is thread\-safe only if a single instance of
 208 ub_ctx* exists in the application.  If several instances exist the
 209 application has to ensure that ub_ctx_config is not called in parallel by
 210 the different instances.
 211 .TP
 212 .B ub_ctx_set_fwd
 213 Set machine to forward DNS queries to, the caching resolver to use.
 214 IP4 or IP6 address. Forwards all DNS requests to that machine, which
 215 is expected to run a recursive resolver. If the proxy is not
 216 DNSSEC capable, validation may fail. Can be called several times, in
 217 that case the addresses are used as backup servers.
 218 At this time it is only possible to set configuration before the
 219 first resolve is done.
 220 .TP
 221 .B ub_ctx_set_stub
 222 Set a stub zone, authoritative dns servers to use for a particular zone.
 223 IP4 or IP6 address.  If the address is NULL the stub entry is removed.
 224 Set isprime true if you configure root hints with it.  Otherwise similar to
 225 the stub zone item from unbound's config file.  Can be called several times,
 226 for different zones, or to add multiple addresses for a particular zone.
 227 At this time it is only possible to set configuration before the
 228 first resolve is done.
 229 .TP
 230 .B ub_ctx_resolvconf
 231 By default the root servers are queried and full resolver mode is used, but
 232 you can use this call to read the list of nameservers to use from the
 233 filename given.
 234 Usually "/etc/resolv.conf". Uses those nameservers as caching proxies.
 235 If they do not support DNSSEC, validation may fail.
 236 Only nameservers are picked up, the searchdomain, ndots and other
 237 settings from \fIresolv.conf\fR(5) are ignored.
 238 If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows,
 239 the system\-wide configured nameserver is picked instead).
 240 At this time it is only possible to set configuration before the
 241 first resolve is done.
 242 .TP
 243 .B ub_ctx_hosts
 244 Read list of hosts from the filename given.
 245 Usually "/etc/hosts". When queried for, these addresses are not marked
 246 DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used
 247 (if on Windows, etc/hosts from WINDIR is picked instead).
 248 At this time it is only possible to set configuration before the
 249 first resolve is done.
 250 .TP
 251 .B
 252 ub_ctx_add_ta
 253 Add a trust anchor to the given context.
 254 At this time it is only possible to add trusted keys before the
 255 first resolve is done.
 256 The format is a string, similar to the zone\-file format,
 257 [domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted.
 258 .TP
 259 .B ub_ctx_add_ta_autr
 260 Add filename with automatically tracked trust anchor to the given context.
 261 Pass name of a file with the managed trust anchor.  You can create this
 262 file with \fIunbound\-anchor\fR(8) for the root anchor.  You can also
 263 create it with an initial file with one line with a DNSKEY or DS record.
 264 If the file is writable, it is updated when the trust anchor changes.
 265 At this time it is only possible to add trusted keys before the
 266 first resolve is done.
 267 .TP
 268 .B ub_ctx_add_ta_file
 269 Add trust anchors to the given context.
 270 Pass name of a file with DS and DNSKEY records in zone file format.
 271 At this time it is only possible to add trusted keys before the
 272 first resolve is done.
 273 .TP
 274 .B ub_ctx_trustedkeys
 275 Add trust anchors to the given context.
 276 Pass the name of a bind\-style config file with trusted\-keys{}.
 277 At this time it is only possible to add trusted keys before the
 278 first resolve is done.
 279 .TP
 280 .B ub_ctx_debugout
 281 Set debug and error log output to the given stream. Pass NULL to disable
 282 output. Default is stderr. File\-names or using syslog can be enabled
 283 using config options, this routine is for using your own stream.
 284 .TP
 285 .B ub_ctx_debuglevel
 286 Set debug verbosity for the context. Output is directed to stderr.
 287 Higher debug level gives more output.
 288 .TP
 289 .B ub_ctx_async
 290 Set a context behaviour for asynchronous action.
 291 if set to true, enables threading and a call to
 292 .B ub_resolve_async
 293 creates a thread to handle work in the background.
 294 If false, a process is forked to handle work in the background.
 295 Changes to this setting after
 296 .B ub_resolve_async
 297 calls have been made have no effect (delete and re\-create the context
 298 to change).
 299 .TP
 300 .B ub_poll
 301 Poll a context to see if it has any new results.
 302 Do not poll in a loop, instead extract the fd below to poll for readiness,
 303 and then check, or wait using the wait routine.
 304 Returns 0 if nothing to read, or nonzero if a result is available.
 305 If nonzero, call
 306 .B ub_process
 307 to do callbacks.
 308 .TP
 309 .B ub_wait
 310 Wait for a context to finish with results. Calls
 311 .B ub_process
 312 after the wait for you. After the wait, there are no more outstanding
 313 asynchronous queries.
 314 .TP
 315 .B ub_fd
 316 Get file descriptor. Wait for it to become readable, at this point
 317 answers are returned from the asynchronous validating resolver.
 318 Then call the \fBub_process\fR to continue processing.
 319 .TP
 320 .B ub_process
 321 Call this routine to continue processing results from the validating
 322 resolver (when the fd becomes readable).
 323 Will perform necessary callbacks.
 324 .TP
 325 .B ub_resolve
 326 Perform resolution and validation of the target name.
 327 The name is a domain name in a zero terminated text string.
 328 The rrtype and rrclass are DNS type and class codes.
 329 The result structure is newly allocated with the resulting data.
 330 .TP
 331 .B ub_resolve_async
 332 Perform asynchronous resolution and validation of the target name.
 333 Arguments mean the same as for \fBub_resolve\fR except no
 334 data is returned immediately, instead a callback is called later.
 335 The callback receives a copy of the mydata pointer, that you can use to pass
 336 information to the callback. The callback type is a function pointer to
 337 a function declared as
 338 .IP
 339 void my_callback_function(void* my_arg, int err,
 340 .br
 341                   struct ub_result* result);
 342 .IP
 343 The async_id is returned so you can (at your option) decide to track it
 344 and cancel the request if needed.  If you pass a NULL pointer the async_id
 345 is not returned.
 346 .TP
 347 .B ub_cancel
 348 Cancel an async query in progress.  This may return an error if the query
 349 does not exist, or the query is already being delivered, in that case you
 350 may still get a callback for the query.
 351 .TP
 352 .B ub_resolve_free
 353 Free struct ub_result contents after use.
 354 .TP
 355 .B ub_strerror
 356 Convert error value from one of the unbound library functions
 357 to a human readable string.
 358 .TP
 359 .B ub_ctx_print_local_zones
 360 Debug printout the local authority information to debug output.
 361 .TP
 362 .B ub_ctx_zone_add
 363 Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5)
 364 statement.
 365 .TP
 366 .B ub_ctx_zone_remove
 367 Delete zone from local authority info.
 368 .TP
 369 .B ub_ctx_data_add
 370 Add resource record data to local authority info, like local\-data
 371 \fIunbound.conf\fR(5) statement.
 372 .TP
 373 .B ub_ctx_data_remove
 374 Delete local authority data from the name given.
 375 .SH "RESULT DATA STRUCTURE"
 376 The result of the DNS resolution and validation is returned as
 377 \fIstruct ub_result\fR. The result structure contains the following entries.
 378 .P
 379 .nf
 380         struct ub_result {
 381                 char* qname; /* text string, original question */
 382                 int qtype;   /* type code asked for */
 383                 int qclass;  /* class code asked for */
 384                 char** data; /* array of rdata items, NULL terminated*/
 385                 int* len;    /* array with lengths of rdata items */
 386                 char* canonname; /* canonical name of result */
 387                 int rcode;   /* additional error code in case of no data */
 388                 void* answer_packet; /* full network format answer packet */
 389                 int answer_len; /* length of packet in octets */
 390                 int havedata; /* true if there is data */
 391                 int nxdomain; /* true if nodata because name does not exist */
 392                 int secure;  /* true if result is secure */
 393                 int bogus;   /* true if a security failure happened */
 394                 char* why_bogus; /* string with error if bogus */
 395                 int ttl;     /* number of seconds the result is valid */
 396         };
 397 .fi
 398 .P
 399 If both secure and bogus are false, security was not enabled for the
 400 domain of the query.  Else, they are not both true, one of them is true.
 401 .SH "RETURN VALUES"
 402 Many routines return an error code. The value 0 (zero) denotes no error
 403 happened. Other values can be passed to
 404 .B ub_strerror
 405 to obtain a readable error string.
 406 .B ub_strerror
 407 returns a zero terminated string.
 408 .B ub_ctx_create
 409 returns NULL on an error (a malloc failure).
 410 .B ub_poll
 411 returns true if some information may be available, false otherwise.
 412 .B ub_fd
 413 returns a file descriptor or \-1 on error.
 414 .B ub_ctx_config
 415 and
 416 .B ub_ctx_resolvconf
 417 attempt to leave errno informative on a function return with file read failure.
 418 .SH "SEE ALSO"
 419 \fIunbound.conf\fR(5),
 420 \fIunbound\fR(8).
 421 .SH "AUTHORS"
 422 .B Unbound
 423 developers are mentioned in the CREDITS file in the distribution.