contrib/unbound/doc/libunbound.3.in

   1 .TH "libunbound" "3" "Dec 10, 2015" "NLnet Labs" "unbound 1.5.7"
   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_t,
  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_resolvconf,
  23 .B ub_ctx_hosts,
  24 .B ub_ctx_add_ta,
  25 .B ub_ctx_add_ta_autr,
  26 .B ub_ctx_add_ta_file,
  27 .B ub_ctx_trustedkeys,
  28 .B ub_ctx_debugout,
  29 .B ub_ctx_debuglevel,
  30 .B ub_ctx_async,
  31 .B ub_poll,
  32 .B ub_wait,
  33 .B ub_fd,
  34 .B ub_process,
  35 .B ub_resolve,
  36 .B ub_resolve_async,
  37 .B ub_cancel,
  38 .B ub_resolve_free,
  39 .B ub_strerror,
  40 .B ub_ctx_print_local_zones,
  41 .B ub_ctx_zone_add,
  42 .B ub_ctx_zone_remove,
  43 .B ub_ctx_data_add,
  44 .B ub_ctx_data_remove
  45 \- Unbound DNS validating resolver 1.5.7 functions.
  46 .SH "SYNOPSIS"
  47 .B #include <unbound.h>
  48 .LP
  49 \fIstruct ub_ctx *\fR
  50 \fBub_ctx_create\fR(\fIvoid\fR);
  51 .LP
  52 \fIvoid\fR
  53 \fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx);
  54 .LP
  55 \fIint\fR
  56 \fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val);
  57 .LP
  58 \fIint\fR
  59 \fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val);
  60 .LP
  61 \fIint\fR
  62 \fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  63 .LP
  64 \fIint\fR
  65 \fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr);
  66 .LP
  67 \fIint\fR
  68 \fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  69 .LP
  70 \fIint\fR
  71 \fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  72 .LP
  73 \fIint\fR
  74 \fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta);
  75 .LP
  76 \fIint\fR
  77 \fBub_ctx_add_ta_autr\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  78 .LP
  79 \fIint\fR
  80 \fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  81 .LP
  82 \fIint\fR
  83 \fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  84 .LP
  85 \fIint\fR
  86 \fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out);
  87 .LP
  88 \fIint\fR
  89 \fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d);
  90 .LP
  91 \fIint\fR
  92 \fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread);
  93 .LP
  94 \fIint\fR
  95 \fBub_poll\fR(\fIstruct ub_ctx*\fR ctx);
  96 .LP
  97 \fIint\fR
  98 \fBub_wait\fR(\fIstruct ub_ctx*\fR ctx);
  99 .LP
 100 \fIint\fR
 101 \fBub_fd\fR(\fIstruct ub_ctx*\fR ctx);
 102 .LP
 103 \fIint\fR
 104 \fBub_process\fR(\fIstruct ub_ctx*\fR ctx);
 105 .LP
 106 \fIint\fR
 107 \fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
 108 .br
 109            \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result);
 110 .LP
 111 \fIint\fR
 112 \fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
 113 .br
 114                  \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata,
 115 .br
 116                  \fIub_callback_t\fR callback, \fIint*\fR async_id);
 117 .LP
 118 \fIint\fR
 119 \fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id);
 120 .LP
 121 \fIvoid\fR
 122 \fBub_resolve_free\fR(\fIstruct ub_result*\fR result);
 123 .LP
 124 \fIconst char *\fR
 125 \fBub_strerror\fR(\fIint\fR err);
 126 .LP
 127 \fIint\fR
 128 \fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx);
 129 .LP
 130 \fIint\fR
 131 \fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type);
 132 .LP
 133 \fIint\fR
 134 \fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name);
 135 .LP
 136 \fIint\fR
 137 \fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
 138 .LP
 139 \fIint\fR
 140 \fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
 141 .SH "DESCRIPTION"
 142 .B Unbound
 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.
 149 .P
 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
 152 .B ub_ctx_create
 153 and deleting it with
 154 .B ub_ctx_delete\fR.
 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.
 157 .P
 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.
 163 .P
 164 The functions are discussed in turn below.
 165 .SH "FUNCTIONS"
 166 .TP
 167 .B ub_ctx_create
 168 Create a new context, initialised with defaults.
 169 The information from /etc/resolv.conf and /etc/hosts is not utilised
 170 by default. Use
 171 .B ub_ctx_resolvconf
 172 and
 173 .B ub_ctx_hosts
 174 to read them.
 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.
 179 .TP
 180 .B ub_ctx_delete
 181 Delete validation context and free associated resources.
 182 Outstanding async queries are killed and callbacks are not called for them.
 183 .TP
 184 .B ub_ctx_set_option
 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 ':'.
 189 .TP
 190 .B ub_ctx_get_option
 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.
 194 .TP
 195 .B ub_ctx_config
 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
 199 routines exist.
 200 .TP
 201 .B ub_ctx_set_fwd
 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.
 209 .TP
 210 .B ub_ctx_resolvconf
 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
 213 filename given.
 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.
 222 .TP
 223 .B ub_ctx_hosts
 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.
 230 .TP
 231 .B
 232 ub_ctx_add_ta
 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.
 238 .TP
 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.
 247 .TP
 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.
 253 .TP
 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.
 259 .TP
 260 .B ub_ctx_debugout
 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.
 264 .TP
 265 .B ub_ctx_debuglevel
 266 Set debug verbosity for the context. Output is directed to stderr.
 267 Higher debug level gives more output.
 268 .TP
 269 .B ub_ctx_async
 270 Set a context behaviour for asynchronous action.
 271 if set to true, enables threading and a call to
 272 .B ub_resolve_async
 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
 276 .B ub_resolve_async
 277 calls have been made have no effect (delete and re\-create the context
 278 to change).
 279 .TP
 280 .B ub_poll
 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.
 285 If nonzero, call
 286 .B ub_process
 287 to do callbacks.
 288 .TP
 289 .B ub_wait
 290 Wait for a context to finish with results. Calls
 291 .B ub_process
 292 after the wait for you. After the wait, there are no more outstanding
 293 asynchronous queries.
 294 .TP
 295 .B ub_fd
 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.
 299 .TP
 300 .B ub_process
 301 Call this routine to continue processing results from the validating
 302 resolver (when the fd becomes readable).
 303 Will perform necessary callbacks.
 304 .TP
 305 .B ub_resolve
 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.
 310 .TP
 311 .B ub_resolve_async
 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
 318 .IP
 319 void my_callback_function(void* my_arg, int err,
 320 .br
 321                   struct ub_result* result);
 322 .IP
 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
 325 is not returned.
 326 .TP
 327 .B ub_cancel
 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.
 331 .TP
 332 .B ub_resolve_free
 333 Free struct ub_result contents after use.
 334 .TP
 335 .B ub_strerror
 336 Convert error value from one of the unbound library functions
 337 to a human readable string.
 338 .TP
 339 .B ub_ctx_print_local_zones
 340 Debug printout the local authority information to debug output.
 341 .TP
 342 .B ub_ctx_zone_add
 343 Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5)
 344 statement.
 345 .TP
 346 .B ub_ctx_zone_remove
 347 Delete zone from local authority info.
 348 .TP
 349 .B ub_ctx_data_add
 350 Add resource record data to local authority info, like local\-data
 351 \fIunbound.conf\fR(5) statement.
 352 .TP
 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.
 358 .P
 359 .nf
 360         struct ub_result {
 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 */
 376         };
 377 .fi
 378 .P
 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.
 381 .SH "RETURN VALUES"
 382 Many routines return an error code. The value 0 (zero) denotes no error
 383 happened. Other values can be passed to
 384 .B ub_strerror
 385 to obtain a readable error string.
 386 .B ub_strerror
 387 returns a zero terminated string.
 388 .B ub_ctx_create
 389 returns NULL on an error (a malloc failure).
 390 .B ub_poll
 391 returns true if some information may be available, false otherwise.
 392 .B ub_fd
 393 returns a file descriptor or \-1 on error.
 394 .SH "SEE ALSO"
 395 \fIunbound.conf\fR(5),
 396 \fIunbound\fR(8).
 397 .SH "AUTHORS"
 398 .B Unbound
 399 developers are mentioned in the CREDITS file in the distribution.