unbound: libunbound/unbound.h File Reference

unbound 0.1

Data Structures | Macros | Typedefs | Enumerations | Functions
unbound.h File Reference

This file contains functions to resolve DNS queries and validate the answers. More...

## Data Structures
struct | ub_result
| The validation and resolution results. More...
struct | ub_shm_stat_info
| Some global statistics that are not in struct stats_info, this struct is shared on a shm segment (shm-key in unbound.conf). More...
struct | ub_server_stats
| per worker statistics. More...
struct | ub_stats_info
| Statistics to send over the control pipe when asked This struct is made to be memcopied, sent in binary. More...

## Macros
#define | UNBOUND_VERSION_MAJOR @UNBOUND_VERSION_MAJOR@
| the version of this header file
#define | UNBOUND_VERSION_MINOR @UNBOUND_VERSION_MINOR@
#define | UNBOUND_VERSION_MICRO @UNBOUND_VERSION_MICRO@
#define | UB_STATS_QTYPE_NUM 256
| number of qtype that is stored for in array
#define | UB_STATS_QCLASS_NUM 256
| number of qclass that is stored for in array
#define | UB_STATS_RCODE_NUM 16
| number of rcodes in stats
#define | UB_STATS_OPCODE_NUM 16
| number of opcodes in stats
#define | UB_STATS_BUCKET_NUM 40
| number of histogram buckets
#define | UB_STATS_RPZ_ACTION_NUM 10
| number of RPZ actions

## Typedefs
typedef void(* | ub_callback_type) (void *, int, struct ub_result *)
| Callback for results of async queries.

## Enumerations
enum | ub_ctx_err { UB_NOERROR = 0 , UB_SOCKET = -1 , UB_NOMEM = -2 , UB_SYNTAX = -3 , UB_SERVFAIL = -4 , UB_FORKFAIL = -5 , UB_AFTERFINAL = -6 , UB_INITFAIL = -7 , UB_PIPE = -8 , UB_READFILE = -9 , UB_NOID = -10 }
| The error constants. More...

## Functions
struct ub_ctx * | ub_ctx_create (void)
| Create a resolving and validation context.
void | ub_ctx_delete (struct ub_ctx *ctx)
| Destroy a validation context and free all its resources.
int | ub_ctx_set_option (struct ub_ctx *ctx, const char *opt, const char *val)
| Set an option for the context.
int | ub_ctx_get_option (struct ub_ctx *ctx, const char *opt, char **str)
| Get an option from the context.
int | ub_ctx_config (struct ub_ctx *ctx, const char *fname)
| setup configuration for the given context.
int | ub_ctx_set_fwd (struct ub_ctx *ctx, const char *addr)
| Set machine to forward DNS queries to, the caching resolver to use.
int | ub_ctx_set_tls (struct ub_ctx *ctx, int tls)
| Use DNS over TLS to send queries to machines set with ub_ctx_set_fwd().
int | ub_ctx_set_stub (struct ub_ctx *ctx, const char *zone, const char *addr, int isprime)
| Add a stub zone, with given address to send to.
int | ub_ctx_resolvconf (struct ub_ctx *ctx, const char *fname)
| Read list of nameservers to use from the filename given.
int | ub_ctx_hosts (struct ub_ctx *ctx, const char *fname)
| Read list of hosts from the filename given.
int | ub_ctx_add_ta (struct ub_ctx *ctx, const char *ta)
| Add a trust anchor to the given context.
int | ub_ctx_add_ta_file (struct ub_ctx *ctx, const char *fname)
| Add trust anchors to the given context.
int | ub_ctx_add_ta_autr (struct ub_ctx *ctx, const char *fname)
| Add trust anchor to the given context that is tracked with RFC5011 automated trust anchor maintenance.
int | ub_ctx_trustedkeys (struct ub_ctx *ctx, const char *fname)
| Add trust anchors to the given context.
int | ub_ctx_debugout (struct ub_ctx *ctx, void *out)
| Set debug output (and error output) to the specified stream.
int | ub_ctx_debuglevel (struct ub_ctx *ctx, int d)
| Set debug verbosity for the context Output is directed to stderr.
int | ub_ctx_async (struct ub_ctx *ctx, int dothread)
| Set a context behaviour for asynchronous action.
int | ub_poll (struct ub_ctx *ctx)
| Poll a context to see if it has any new results Do not poll in a loop, instead extract the fd below to poll for readiness, and then check, or wait using the wait routine.
int | ub_wait (struct ub_ctx *ctx)
| Wait for a context to finish with results.
int | ub_fd (struct ub_ctx *ctx)
| Get file descriptor.
int | ub_process (struct ub_ctx *ctx)
| Call this routine to continue processing results from the validating resolver (when the fd becomes readable).
int | ub_resolve (struct ub_ctx *ctx, const char *name, int rrtype, int rrclass, struct ub_result **result)
| Perform resolution and validation of the target name.
int | ub_resolve_async (struct ub_ctx *ctx, const char *name, int rrtype, int rrclass, void *mydata, ub_callback_type callback, int *async_id)
| Perform resolution and validation of the target name.
int | ub_cancel (struct ub_ctx *ctx, int async_id)
| Cancel an async query in progress.
void | ub_resolve_free (struct ub_result *result)
| Free storage associated with a result structure.
const char * | ub_strerror (int err)
| Convert error value to a human readable string.
int | ub_ctx_print_local_zones (struct ub_ctx *ctx)
| Debug routine.
int | ub_ctx_zone_add (struct ub_ctx *ctx, const char *zone_name, const char *zone_type)
| Add a new zone with the zonetype to the local authority info of the library.
int | ub_ctx_zone_remove (struct ub_ctx *ctx, const char *zone_name)
| Remove zone from local authority info of the library.
int | ub_ctx_data_add (struct ub_ctx *ctx, const char *data)
| Add localdata to the library local authority info.
int | ub_ctx_data_remove (struct ub_ctx *ctx, const char *data)
| Remove localdata from the library local authority info.
const char * | ub_version (void)
| Get a version string from the libunbound implementation.

## Detailed Description

This file contains functions to resolve DNS queries and validate the answers.

Synchronously and asynchronously.

Several ways to use this interface from an application wishing to perform (validated) DNS lookups.

All start with ctx = ub_ctx_create(); err = ub_ctx_add_ta(ctx, "..."); err = ub_ctx_add_ta(ctx, "..."); ... some lookups ... call ub_ctx_delete(ctx); when you want to stop.

Application not threaded. Blocking. int err = ub_resolve(ctx, "www.example.com", ... if(err) fprintf(stderr, "lookup error: %s\n", ub_strerror(err)); ... use the answer

Application not threaded. Non-blocking ('asynchronous'). err = ub_resolve_async(ctx, "www.example.com", ... my_callback); ... application resumes processing ... ... and when either ub_poll(ctx) is true ... or when the file descriptor ub_fd(ctx) is readable, ... or whenever, the app calls ... ub_process(ctx); ... if no result is ready, the app resumes processing above, ... or process() calls my_callback() with results.

... if the application has nothing more to do, wait for answer ub_wait(ctx);

Application threaded. Blocking. Blocking, same as above. The current thread does the work. Multiple threads can use the same context, each does work and uses shared cache data from the context.

Application threaded. Non-blocking ('asynchronous'). ... setup threaded-asynchronous config option err = ub_ctx_async(ctx, 1); ... same as async for non-threaded ... the callbacks are called in the thread that calls process(ctx)

Openssl needs to have locking in place, and the application must set it up, because a mere library cannot do this, use the calls CRYPTO_set_id_callback and CRYPTO_set_locking_callback.

If no threading is compiled in, the above async example uses fork(2) to create a process to perform the work. The forked process exits when the calling process exits, or ctx_delete() is called. Otherwise, for asynchronous with threading, a worker thread is created.

The blocking calls use shared ctx-cache when threaded. Thus ub_resolve() and ub_resolve_async() && ub_wait() are not the same. The first makes the current thread do the work, setting up buffers, etc, to perform the work (but using shared cache data). The second calls another worker thread (or process) to perform the work. And no buffers need to be set up, but a context-switch happens.

## Typedef Documentation

## ◆ ub_callback_type

typedef void(* ub_callback_type) (void *, int, struct ub_result *)

Callback for results of async queries.

The readable function definition looks like: void my_callback(void* my_arg, int err, struct ub_result* result); It is called with void* my_arg: your pointer to a (struct of) data of your choice, or NULL. int err: if 0 all is OK, otherwise an error occurred and no results are forthcoming. struct result: pointer to more detailed result structure. This structure is allocated on the heap and needs to be freed with ub_resolve_free(result);

## Enumeration Type Documentation

## ◆ ub_ctx_err

enum ub_ctx_err

The error constants.

Enumerator
UB_NOERROR | no error
UB_SOCKET | socket operation. Set to -1, so that if an error from _fd() is passed (-1) it gives a socket error.
UB_NOMEM | alloc failure
UB_SYNTAX | syntax error
UB_SERVFAIL | DNS service failed.
UB_FORKFAIL | fork() failed
UB_AFTERFINAL | cfg change after finalize()
UB_INITFAIL | initialization failed (bad settings)
UB_PIPE | error in pipe communication with async bg worker
UB_READFILE | error reading from file (resolv.conf)
UB_NOID | error async_id does not exist or result already been delivered

## Function Documentation

## ◆ ub_ctx_create()

struct ub_ctx * ub_ctx_create | ( | void |  | ) |

Create a resolving and validation context.

The information from /etc/resolv.conf and /etc/hosts is not utilised by default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them.

Returns
  a new context. default initialisation. returns NULL on error.

## ◆ ub_ctx_delete()

void ub_ctx_delete | ( | struct ub_ctx * | ctx | ) |

Destroy a validation context and free all its resources.

Outstanding async queries are killed and callbacks are not called for them.

Parameters

  ctx | context to delete.

## ◆ ub_ctx_set_option()

int ub_ctx_set_option | ( | struct ub_ctx * | ctx,
|  | const char * | opt,
|  | const char * | val )

Set an option for the context.

Parameters

  ctx | context.
  opt | option name from the unbound.conf config file format. (not all settings applicable). The name includes the trailing ':' for example ub_ctx_set_option(ctx, "logfile:", "mylog.txt"); This is a power-users interface that lets you specify all sorts of options. For some specific options, such as adding trust anchors, special routines exist.
  val | value of the option.

Returns
  : 0 if OK, else error.

## ◆ ub_ctx_get_option()

int ub_ctx_get_option | ( | struct ub_ctx * | ctx,
|  | const char * | opt,
|  | char ** | str )

Get an option from the context.

Parameters

  ctx | context.
  opt | option name from the unbound.conf config file format. (not all settings applicable). The name excludes the trailing ':' for example ub_ctx_get_option(ctx, "logfile", &result); This is a power-users interface that lets you specify all sorts of options.
  str | the string is malloced and returned here. NULL on error. The caller must free() the string. In cases with multiple entries (auto-trust-anchor-file), a newline delimited list is returned in the string.

Returns
  0 if OK else an error code (malloc failure, syntax error).

## ◆ ub_ctx_config()

int ub_ctx_config | ( | struct ub_ctx * | ctx,
|  | const char * | fname )

setup configuration for the given context.

Parameters

  ctx | context.
  fname | unbound config file (not all settings applicable). This is a power-users interface that lets you specify all sorts of options. For some specific options, such as adding trust anchors, special routines exist.

Returns
  : 0 if OK, else error.

## ◆ ub_ctx_set_fwd()

int ub_ctx_set_fwd | ( | struct ub_ctx * | ctx,
|  | const char * | addr )

Set machine to forward DNS queries to, the caching resolver to use.

IP4 or IP6 address. Forwards all DNS requests to that machine, which is expected to run a recursive resolver. If the proxy is not DNSSEC-capable, validation may fail. Can be called several times, in that case the addresses are used as backup servers.

To read the list of nameservers from /etc/resolv.conf (from DHCP or so), use the call ub_ctx_resolvconf.

Parameters

  ctx | context. At this time it is only possible to set configuration before the first resolve is done.
  addr | address, IP4 or IP6 in string format. If the addr is NULL, forwarding is disabled.

Returns
  0 if OK, else error.

## ◆ ub_ctx_set_tls()

int ub_ctx_set_tls | ( | struct ub_ctx * | ctx,
|  | int | tls )

Use DNS over TLS to send queries to machines set with ub_ctx_set_fwd().

Parameters

  ctx | context. At this time it is only possible to set configuration before the first resolve is done.
  tls | enable or disable DNS over TLS

Returns
  0 if OK, else error.

## ◆ ub_ctx_set_stub()

int ub_ctx_set_stub | ( | struct ub_ctx * | ctx,
|  | const char * | zone,
|  | const char * | addr,
|  | int | isprime )

Add a stub zone, with given address to send to.

This is for custom root hints or pointing to a local authoritative dns server. For dns resolvers and the 'DHCP DNS' ip address, use ub_ctx_set_fwd. This is similar to a stub-zone entry in unbound.conf.

Parameters

  ctx | context. It is only possible to set configuration before the first resolve is done.
  zone | name of the zone, string.
  addr | address, IP4 or IP6 in string format. The addr is added to the list of stub-addresses if the entry exists. If the addr is NULL the stub entry is removed.
  isprime | set to true to set stub-prime to yes for the stub. For local authoritative servers, people usually set it to false, For root hints it should be set to true.

Returns
  0 if OK, else error.

## ◆ ub_ctx_resolvconf()

int ub_ctx_resolvconf | ( | struct ub_ctx * | ctx,
|  | const char * | fname )

Read list of nameservers to use from the filename given.

Usually "/etc/resolv.conf". Uses those nameservers as caching proxies. If they do not support DNSSEC, validation may fail.

Only nameservers are picked up, the searchdomain, ndots and other settings from resolv.conf(5) are ignored.

Parameters

  ctx | context. At this time it is only possible to set configuration before the first resolve is done.
  fname | file name string. If NULL "/etc/resolv.conf" is used.

Returns
  0 if OK, else error.

## ◆ ub_ctx_hosts()

int ub_ctx_hosts | ( | struct ub_ctx * | ctx,
|  | const char * | fname )

Read list of hosts from the filename given.

Usually "/etc/hosts". These addresses are not flagged as DNSSEC secure when queried for.

Parameters

  ctx | context. At this time it is only possible to set configuration before the first resolve is done.
  fname | file name string. If NULL "/etc/hosts" is used.

Returns
  0 if OK, else error.

## ◆ ub_ctx_add_ta()

int ub_ctx_add_ta | ( | struct ub_ctx * | ctx,
|  | const char * | ta )

Add a trust anchor to the given context.

The trust anchor is a string, on one line, that holds a valid DNSKEY or DS RR.

Parameters

  ctx | context. At this time it is only possible to add trusted keys before the first resolve is done.
  ta | string, with zone-format RR on one line. [domainname] [TTL optional] [type] [class optional] [rdata contents]

Returns
  0 if OK, else error.

## ◆ ub_ctx_add_ta_file()

int ub_ctx_add_ta_file | ( | struct ub_ctx * | ctx,
|  | const char * | fname )

Add trust anchors to the given context.

Pass name of a file with DS and DNSKEY records (like from dig or drill).

Parameters

  ctx | context. At this time it is only possible to add trusted keys before the first resolve is done.
  fname | filename of file with keyfile with trust anchors.

Returns
  0 if OK, else error.

## ◆ ub_ctx_add_ta_autr()

int ub_ctx_add_ta_autr | ( | struct ub_ctx * | ctx,
|  | const char * | fname )

Add trust anchor to the given context that is tracked with RFC5011 automated trust anchor maintenance.

The file is written to when the trust anchor is changed. Pass the name of a file that was output from eg. unbound-anchor, or you can start it by providing a trusted DNSKEY or DS record on one line in the file.

Parameters

  ctx | context. At this time it is only possible to add trusted keys before the first resolve is done.
  fname | filename of file with trust anchor.

Returns
  0 if OK, else error.

## ◆ ub_ctx_trustedkeys()

int ub_ctx_trustedkeys | ( | struct ub_ctx * | ctx,
|  | const char * | fname )

Add trust anchors to the given context.

Pass the name of a bind-style config file with trusted-keys{}.

Parameters

  ctx | context. At this time it is only possible to add trusted keys before the first resolve is done.
  fname | filename of file with bind-style config entries with trust anchors.

Returns
  0 if OK, else error.

## ◆ ub_ctx_debugout()

int ub_ctx_debugout | ( | struct ub_ctx * | ctx,
|  | void * | out )

Set debug output (and error output) to the specified stream.

Pass NULL to disable. Default is stderr.

Parameters

  ctx | context.
  out | FILE* out file stream to log to. Type void* to avoid stdio dependency of this header file.

Returns
  0 if OK, else error.

## ◆ ub_ctx_debuglevel()

int ub_ctx_debuglevel | ( | struct ub_ctx * | ctx,
|  | int | d )

Set debug verbosity for the context Output is directed to stderr.

Parameters

  ctx | context.
  d | debug level, 0 is off, 1 is very minimal, 2 is detailed, and 3 is lots.

Returns
  0 if OK, else error.

## ◆ ub_ctx_async()

int ub_ctx_async | ( | struct ub_ctx * | ctx,
|  | int | dothread )

Set a context behaviour for asynchronous action.

Parameters

  ctx | context.
  dothread | if true, enables threading and a call to resolve_async() creates a thread to handle work in the background. If false, a process is forked to handle work in the background. Changes to this setting after async() calls have been made have no effect (delete and re-create the context to change).

Returns
  0 if OK, else error.

## ◆ ub_poll()

int ub_poll | ( | struct ub_ctx * | ctx | ) |

Poll a context to see if it has any new results Do not poll in a loop, instead extract the fd below to poll for readiness, and then check, or wait using the wait routine.

Parameters

  ctx | context.

Returns
  : 0 if nothing to read, or nonzero if a result is available. If nonzero, call ctx_process() to do callbacks.

## ◆ ub_wait()

int ub_wait | ( | struct ub_ctx * | ctx | ) |

Wait for a context to finish with results.

Calls ub_process() after the wait for you. After the wait, there are no more outstanding asynchronous queries.

Parameters

  ctx | context.

Returns
  : 0 if OK, else error.

## ◆ ub_fd()

int ub_fd | ( | struct ub_ctx * | ctx | ) |

Get file descriptor.

Wait for it to become readable, at this point answers are returned from the asynchronous validating resolver. Then call the ub_process to continue processing. This routine works immediately after context creation, the fd does not change.

Parameters

  ctx | context.

Returns
  : -1 on error, or file descriptor to use select(2) with.

## ◆ ub_process()

int ub_process | ( | struct ub_ctx * | ctx | ) |

Call this routine to continue processing results from the validating resolver (when the fd becomes readable).

Will perform necessary callbacks.

Parameters

  ctx | context

Returns
  : 0 if OK, else error.

## ◆ ub_resolve()

int ub_resolve | ( | struct ub_ctx * | ctx,
|  | const char * | name,
|  | int | rrtype,
|  | int | rrclass,
|  | struct ub_result ** | result )

Perform resolution and validation of the target name.

Parameters

  ctx | context. The context is finalized, and can no longer accept config changes.
  name | domain name in text format (a zero terminated text string).
  rrtype | type of RR in host order, 1 is A (address).
  rrclass | class of RR in host order, 1 is IN (for internet).
  result | the result data is returned in a newly allocated result structure. May be NULL on return, return value is set to an error in that case (out of memory).

Returns
  0 if OK, else error.

## ◆ ub_resolve_async()

int ub_resolve_async | ( | struct ub_ctx * | ctx,
|  | const char * | name,
|  | int | rrtype,
|  | int | rrclass,
|  | void * | mydata,
|  | ub_callback_type | callback,
|  | int * | async_id )

Perform resolution and validation of the target name.

Asynchronous, after a while, the callback will be called with your data and the result.

Parameters

  ctx | context. If no thread or process has been created yet to perform the work in the background, it is created now. The context is finalized, and can no longer accept config changes.
  name | domain name in text format (a string).
  rrtype | type of RR in host order, 1 is A.
  rrclass | class of RR in host order, 1 is IN (for internet).
  mydata | this data is your own data (you can pass NULL), and is passed on to the callback function.
  callback | this is called on completion of the resolution. It is called as: void callback(void* mydata, int err, struct ub_result* result) with mydata: the same as passed here, you may pass NULL, with err: is 0 when a result has been found. with result: a newly allocated result structure. The result may be NULL, in that case err is set.

If an error happens during processing, your callback will be called with error set to a nonzero value (and result==NULL).

Parameters

  async_id | if you pass a non-NULL value, an identifier number is returned for the query as it is in progress. It can be used to cancel the query.

Returns
  0 if OK, else error.

## ◆ ub_cancel()

int ub_cancel | ( | struct ub_ctx * | ctx,
|  | int | async_id )

Cancel an async query in progress.

Its callback will not be called.

Parameters

  ctx | context.
  async_id | which query to cancel.

Returns
  0 if OK, else error. This routine can return an error if the async_id passed does not exist or has already been delivered. If another thread is processing results at the same time, the result may be delivered at the same time and the cancel fails with an error. Also the cancel can fail due to a system error, no memory or socket failures.

## ◆ ub_resolve_free()

void ub_resolve_free | ( | struct ub_result * | result | ) |

Free storage associated with a result structure.

Parameters

  result | to free

## ◆ ub_strerror()

const char * ub_strerror | ( | int | err | ) |

Convert error value to a human readable string.

Parameters

  err | error code from one of the libunbound functions. The error codes are from the type enum ub_ctx_err.

Returns
  pointer to constant text string, zero terminated.

## ◆ ub_ctx_print_local_zones()

int ub_ctx_print_local_zones | ( | struct ub_ctx * | ctx | ) |

Debug routine.

Print the local zone information to debug output.

Parameters

  ctx | context. Is finalized by the routine.

Returns
  0 if OK, else error.

## ◆ ub_ctx_zone_add()

int ub_ctx_zone_add | ( | struct ub_ctx * | ctx,
|  | const char * | zone_name,
|  | const char * | zone_type )

Add a new zone with the zonetype to the local authority info of the library.

Parameters

  ctx | context. Is finalized by the routine.
  zone_name | name of the zone in text, "example.com" If it already exists, the type is updated.
  zone_type | type of the zone (like for unbound.conf) in text.

Returns
  0 if OK, else error.

## ◆ ub_ctx_zone_remove()

int ub_ctx_zone_remove | ( | struct ub_ctx * | ctx,
|  | const char * | zone_name )

Remove zone from local authority info of the library.

Parameters

  ctx | context. Is finalized by the routine.
  zone_name | name of the zone in text, "example.com" If it does not exist, nothing happens.

Returns
  0 if OK, else error.

## ◆ ub_ctx_data_add()

int ub_ctx_data_add | ( | struct ub_ctx * | ctx,
|  | const char * | data )

Add localdata to the library local authority info.

Similar to local-data config statement.

Parameters

  ctx | context. Is finalized by the routine.
  data | the resource record in text format, for example "www.example.com IN A 127.0.0.1"

Returns
  0 if OK, else error.

## ◆ ub_ctx_data_remove()

int ub_ctx_data_remove | ( | struct ub_ctx * | ctx,
|  | const char * | data )

Remove localdata from the library local authority info.

Parameters

  ctx | context. Is finalized by the routine.
  data | the name to delete all data from, like "www.example.com".

Returns
  0 if OK, else error.

## ◆ ub_version()

const char * ub_version | ( | void |  | ) |

Get a version string from the libunbound implementation.

Returns
  a static constant string with the version number.