contrib/unbound/doc/libunbound.3

   1 .TH "libunbound" "3" "Mar 21, 2013" "NLnet Labs" "unbound 1.4.20"
   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 .LP
  12 .B libunbound,
  13 .B unbound.h,
  14 .B ub_ctx,
  15 .B ub_result,
  16 .B ub_callback_t,
  17 .B ub_ctx_create,
  18 .B ub_ctx_delete,
  19 .B ub_ctx_set_option,
  20 .B ub_ctx_get_option,
  21 .B ub_ctx_config,
  22 .B ub_ctx_set_fwd,
  23 .B ub_ctx_resolvconf,
  24 .B ub_ctx_hosts,
  25 .B ub_ctx_add_ta,
  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.4.20 functions.
  46 .SH "SYNOPSIS"
  47 .LP
  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_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  70 .LP
  71 \fIint\fR
  72 \fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  73 .LP
  74 \fIint\fR
  75 \fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta);
  76 .LP
  77 \fIint\fR
  78 \fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  79 .LP
  80 \fIint\fR
  81 \fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
  82 .LP
  83 \fIint\fR
  84 \fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out);
  85 .LP
  86 \fIint\fR
  87 \fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d);
  88 .LP
  89 \fIint\fR
  90 \fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread);
  91 .LP
  92 \fIint\fR
  93 \fBub_poll\fR(\fIstruct ub_ctx*\fR ctx);
  94 .LP
  95 \fIint\fR
  96 \fBub_wait\fR(\fIstruct ub_ctx*\fR ctx);
  97 .LP
  98 \fIint\fR
  99 \fBub_fd\fR(\fIstruct ub_ctx*\fR ctx);
 100 .LP
 101 \fIint\fR
 102 \fBub_process\fR(\fIstruct ub_ctx*\fR ctx);
 103 .LP
 104 \fIint\fR
 105 \fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
 106 .br
 107            \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result);
 108 .LP
 109 \fIint\fR
 110 \fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
 111 .br
 112                  \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata,
 113 .br
 114                  \fIub_callback_t\fR callback, \fIint*\fR async_id);
 115 .LP
 116 \fIint\fR
 117 \fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id);
 118 .LP
 119 \fIvoid\fR
 120 \fBub_resolve_free\fR(\fIstruct ub_result*\fR result);
 121 .LP
 122 \fIconst char *\fR
 123 \fBub_strerror\fR(\fIint\fR err);
 124 .LP
 125 \fIint\fR
 126 \fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx);
 127 .LP
 128 \fIint\fR
 129 \fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type);
 130 .LP
 131 \fIint\fR
 132 \fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name);
 133 .LP
 134 \fIint\fR
 135 \fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
 136 .LP
 137 \fIint\fR
 138 \fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
 139 .SH "DESCRIPTION"
 140 .LP
 141 .B Unbound
 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.
 148 .P
 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
 151 .B ub_ctx_create
 152 and deleting it with
 153 .B ub_ctx_delete\fR.
 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.
 156 .P
 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.
 162 .P
 163 The functions are discussed in turn below.
 164 .SH "FUNCTIONS"
 165 .TP
 166 .B ub_ctx_create
 167 Create a new context, initialised with defaults.
 168 The information from /etc/resolv.conf and /etc/hosts is not utilised
 169 by default. Use
 170 .B ub_ctx_resolvconf
 171 and
 172 .B ub_ctx_hosts
 173 to read them.
 174 .TP
 175 .B ub_ctx_delete
 176 Delete validation context and free associated resources.
 177 Outstanding async queries are killed and callbacks are not called for them.
 178 .TP
 179 .B ub_ctx_set_option
 180 A power\-user interface that lets you specify one of the options from the
 181 config file format, see \fIunbound.conf\fR(5). Not all options are
 182 relevant. For some specific options, such as adding trust anchors, special
 183 routines exist. Pass the option name with the trailing ':'.
 184 .TP
 185 .B ub_ctx_get_option
 186 A power\-user interface that gets an option value.  Some options cannot be
 187 gotten, and others return a newline separated list.  Pass the option name
 188 without trailing ':'.  The returned value must be free(2)d by the caller.
 189 .TP
 190 .B ub_ctx_config
 191 A power\-user interface that lets you specify an unbound config file, see
 192 \fIunbound.conf\fR(5), which is read for configuration. Not all options are
 193 relevant. For some specific options, such as adding trust anchors, special
 194 routines exist.
 195 .TP
 196 .B ub_ctx_set_fwd
 197 Set machine to forward DNS queries to, the caching resolver to use.
 198 IP4 or IP6 address. Forwards all DNS requests to that machine, which
 199 is expected to run a recursive resolver. If the proxy is not
 200 DNSSEC capable, validation may fail. Can be called several times, in
 201 that case the addresses are used as backup servers.
 202 At this time it is only possible to set configuration before the
 203 first resolve is done.
 204 .TP
 205 .B ub_ctx_resolvconf
 206 By default the root servers are queried and full resolver mode is used, but
 207 you can use this call to read the list of nameservers to use from the
 208 filename given.
 209 Usually "/etc/resolv.conf". Uses those nameservers as caching proxies.
 210 If they do not support DNSSEC, validation may fail.
 211 Only nameservers are picked up, the searchdomain, ndots and other
 212 settings from \fIresolv.conf\fR(5) are ignored.
 213 If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows,
 214 the system\-wide configured nameserver is picked instead).
 215 At this time it is only possible to set configuration before the
 216 first resolve is done.
 217 .TP
 218 .B ub_ctx_hosts
 219 Read list of hosts from the filename given.
 220 Usually "/etc/hosts". When queried for, these addresses are not marked
 221 DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used
 222 (if on Windows, etc/hosts from WINDIR is picked instead).
 223 At this time it is only possible to set configuration before the
 224 first resolve is done.
 225 .TP
 226 .B
 227 ub_ctx_add_ta
 228 Add a trust anchor to the given context.
 229 At this time it is only possible to add trusted keys before the
 230 first resolve is done.
 231 The format is a string, similar to the zone\-file format,
 232 [domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted.
 233 .TP
 234 .B ub_ctx_add_ta_file
 235 Add trust anchors to the given context.
 236 Pass name of a file with DS and DNSKEY records in zone file format.
 237 At this time it is only possible to add trusted keys before the
 238 first resolve is done.
 239 .TP
 240 .B ub_ctx_trustedkeys
 241 Add trust anchors to the given context.
 242 Pass the name of a bind\-style config file with trusted\-keys{}.
 243 At this time it is only possible to add trusted keys before the
 244 first resolve is done.
 245 .TP
 246 .B ub_ctx_debugout
 247 Set debug and error log output to the given stream. Pass NULL to disable
 248 output. Default is stderr. File\-names or using syslog can be enabled
 249 using config options, this routine is for using your own stream.
 250 .TP
 251 .B ub_ctx_debuglevel
 252 Set debug verbosity for the context. Output is directed to stderr.
 253 Higher debug level gives more output.
 254 .TP
 255 .B ub_ctx_async
 256 Set a context behaviour for asynchronous action.
 257 if set to true, enables threading and a call to
 258 .B ub_resolve_async
 259 creates a thread to handle work in the background.
 260 If false, a process is forked to handle work in the background.
 261 Changes to this setting after
 262 .B ub_resolve_async
 263 calls have been made have no effect (delete and re\-create the context
 264 to change).
 265 .TP
 266 .B ub_poll
 267 Poll a context to see if it has any new results.
 268 Do not poll in a loop, instead extract the fd below to poll for readiness,
 269 and then check, or wait using the wait routine.
 270 Returns 0 if nothing to read, or nonzero if a result is available.
 271 If nonzero, call
 272 .B ub_process
 273 to do callbacks.
 274 .TP
 275 .B ub_wait
 276 Wait for a context to finish with results. Calls
 277 .B ub_process
 278 after the wait for you. After the wait, there are no more outstanding
 279 asynchronous queries.
 280 .TP
 281 .B ub_fd
 282 Get file descriptor. Wait for it to become readable, at this point
 283 answers are returned from the asynchronous validating resolver.
 284 Then call the \fBub_process\fR to continue processing.
 285 .TP
 286 .B ub_process
 287 Call this routine to continue processing results from the validating
 288 resolver (when the fd becomes readable).
 289 Will perform necessary callbacks.
 290 .TP
 291 .B ub_resolve
 292 Perform resolution and validation of the target name.
 293 The name is a domain name in a zero terminated text string.
 294 The rrtype and rrclass are DNS type and class codes.
 295 The result structure is newly allocated with the resulting data.
 296 .TP
 297 .B ub_resolve_async
 298 Perform asynchronous resolution and validation of the target name.
 299 Arguments mean the same as for \fBub_resolve\fR except no
 300 data is returned immediately, instead a callback is called later.
 301 The callback receives a copy of the mydata pointer, that you can use to pass
 302 information to the callback. The callback type is a function pointer to
 303 a function declared as
 304 .IP
 305 void my_callback_function(void* my_arg, int err,
 306 .br
 307                   struct ub_result* result);
 308 .IP
 309 The async_id is returned so you can (at your option) decide to track it
 310 and cancel the request if needed.  If you pass a NULL pointer the async_id
 311 is not returned.
 312 .TP
 313 .B ub_cancel
 314 Cancel an async query in progress.  This may return an error if the query
 315 does not exist, or the query is already being delivered, in that case you
 316 may still get a callback for the query.
 317 .TP
 318 .B ub_resolve_free
 319 Free struct ub_result contents after use.
 320 .TP
 321 .B ub_strerror
 322 Convert error value from one of the unbound library functions
 323 to a human readable string.
 324 .TP
 325 .B ub_ctx_print_local_zones
 326 Debug printout the local authority information to debug output.
 327 .TP
 328 .B ub_ctx_zone_add
 329 Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5)
 330 statement.
 331 .TP
 332 .B ub_ctx_zone_remove
 333 Delete zone from local authority info.
 334 .TP
 335 .B ub_ctx_data_add
 336 Add resource record data to local authority info, like local\-data
 337 \fIunbound.conf\fR(5) statement.
 338 .TP
 339 .B ub_ctx_data_remove
 340 Delete local authority data from the name given.
 341 .SH "RESULT DATA STRUCTURE"
 342 .LP
 343 The result of the DNS resolution and validation is returned as
 344 \fIstruct ub_result\fR. The result structure contains the following entries.
 345 .P
 346 .nf
 347         struct ub_result {
 348                 char* qname; /* text string, original question */
 349                 int qtype;   /* type code asked for */
 350                 int qclass;  /* class code asked for */
 351                 char** data; /* array of rdata items, NULL terminated*/
 352                 int* len;    /* array with lengths of rdata items */
 353                 char* canonname; /* canonical name of result */
 354                 int rcode;   /* additional error code in case of no data */
 355                 void* answer_packet; /* full network format answer packet */
 356                 int answer_len; /* length of packet in octets */
 357                 int havedata; /* true if there is data */
 358                 int nxdomain; /* true if nodata because name does not exist */
 359                 int secure;  /* true if result is secure */
 360                 int bogus;   /* true if a security failure happened */
 361                 char* why_bogus; /* string with error if bogus */
 362                 int ttl;     /* number of seconds the result is valid */
 363         };
 364 .fi
 365 .P
 366 If both secure and bogus are false, security was not enabled for the
 367 domain of the query.
 368 .SH "RETURN VALUES"
 369 Many routines return an error code. The value 0 (zero) denotes no error
 370 happened. Other values can be passed to
 371 .B ub_strerror
 372 to obtain a readable error string.
 373 .B ub_strerror
 374 returns a zero terminated string.
 375 .B ub_ctx_create
 376 returns NULL on an error (a malloc failure).
 377 .B ub_poll
 378 returns true if some information may be available, false otherwise.
 379 .B ub_fd
 380 returns a file descriptor or \-1 on error.
 381 .SH "SEE ALSO"
 382 \fIunbound.conf\fR(5),
 383 \fIunbound\fR(8).
 384 .SH "AUTHORS"
 385 .B Unbound
 386 developers are mentioned in the CREDITS file in the distribution.