Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
libunbound(3)			unbound	1.13.2			 libunbound(3)

       libunbound, unbound.h, ub_ctx, ub_result, ub_callback_type, ub_ctx_cre-
       ate, ub_ctx_delete, ub_ctx_set_option,  ub_ctx_get_option,  ub_ctx_con-
       fig,  ub_ctx_set_fwd,  ub_ctx_set_stub,	ub_ctx_set_tls,	ub_ctx_resolv-
       conf,	  ub_ctx_hosts,	      ub_ctx_add_ta,	   ub_ctx_add_ta_autr,
       ub_ctx_add_ta_file,  ub_ctx_trustedkeys,	 ub_ctx_debugout, ub_ctx_debu-
       glevel, ub_ctx_async, ub_poll, ub_wait, ub_fd, ub_process,  ub_resolve,
       ub_resolve_async,      ub_cancel,     ub_resolve_free,	  ub_strerror,
       ub_ctx_print_local_zones,     ub_ctx_zone_add,	   ub_ctx_zone_remove,
       ub_ctx_data_add,	 ub_ctx_data_remove  - Unbound DNS validating resolver
       1.13.2 functions.

       #include	<unbound.h>

       struct ub_ctx * ub_ctx_create(void);

       void ub_ctx_delete(struct ub_ctx* ctx);

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

       int ub_ctx_get_option(struct ub_ctx* ctx, char* opt, char** val);

       int ub_ctx_config(struct	ub_ctx*	ctx, char* fname);

       int ub_ctx_set_fwd(struct ub_ctx* ctx, char* addr);

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

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

       int ub_ctx_resolvconf(struct ub_ctx* ctx, char* fname);

       int ub_ctx_hosts(struct ub_ctx* ctx, char* fname);

       int ub_ctx_add_ta(struct	ub_ctx*	ctx, char* ta);

       int ub_ctx_add_ta_autr(struct ub_ctx* ctx, char*	fname);

       int ub_ctx_add_ta_file(struct ub_ctx* ctx, char*	fname);

       int ub_ctx_trustedkeys(struct ub_ctx* ctx, char*	fname);

       int ub_ctx_debugout(struct ub_ctx* ctx, FILE* out);

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

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

       int ub_poll(struct ub_ctx* ctx);

       int ub_wait(struct ub_ctx* ctx);

       int ub_fd(struct	ub_ctx*	ctx);

       int ub_process(struct ub_ctx* ctx);

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

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

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

       void ub_resolve_free(struct ub_result* result);

       const char * ub_strerror(int err);

       int ub_ctx_print_local_zones(struct ub_ctx* ctx);

       int  ub_ctx_zone_add(struct  ub_ctx*  ctx,   char*   zone_name,	 char*

       int ub_ctx_zone_remove(struct ub_ctx* ctx, char*	zone_name);

       int ub_ctx_data_add(struct ub_ctx* ctx, char* data);

       int ub_ctx_data_remove(struct ub_ctx* ctx, char*	data);

       Unbound	is  an implementation of a DNS resolver, that does caching and
       DNSSEC validation. This is the library API, for using the -lunbound li-
       brary.	The  server  daemon  is	 described in unbound(8).  The library
       works independent from a	running	unbound	server,	and  can  be  used  to
       convert	hostnames to ip	addresses, and back, and obtain	other informa-
       tion from the DNS. The library performs public-key  validation  of  re-
       sults with DNSSEC.

       The  library  uses a variable of	type struct ub_ctx to keep context be-
       tween calls. The	user must maintain it, creating	it with	 ub_ctx_create
       and  deleting  it with ub_ctx_delete.  It can be	created	and deleted at
       any time. Creating it anew removes any previous configuration (such  as
       trusted keys) and clears	any cached results.

       The  functions are thread-safe, and a context can be used in a threaded
       (as well	as in a	non-threaded) environment. Also	resolution (and	 vali-
       dation)	can  be	performed blocking and non-blocking (also called asyn-
       chronous).  The async method returns from the call immediately, so that
       processing can go on, while the results become available	later.

       The functions are discussed in turn below.

	      Create  a	 new context, initialised with defaults.  The informa-
	      tion from	/etc/resolv.conf and /etc/hosts	is not utilised	by de-
	      fault. Use ub_ctx_resolvconf and ub_ctx_hosts to read them.  Be-
	      fore   you   call	   this,    use	   the	  openssl    functions
	      CRYPTO_set_id_callback and CRYPTO_set_locking_callback to	set up
	      asynchronous operation if	you use	lib openssl  (the  application
	      calls  these  functions once for initialisation).	 Openssl 1.0.0
	      or later uses the	CRYPTO_THREADID_set_callback function.

	      Delete validation	context	and free associated  resources.	  Out-
	      standing	async  queries are killed and callbacks	are not	called
	      for them.

	      A	power-user interface that lets you specify one of the  options
	      from  the	 config	 file format, see unbound.conf(5). Not all op-
	      tions are	relevant. For some specific options,  such  as	adding
	      trust anchors, special routines exist. Pass the option name with
	      the trailing ':'.

	      A	power-user interface that gets an option value.	 Some  options
	      cannot  be  gotten,  and others return a newline separated list.
	      Pass the option name without trailing ':'.  The  returned	 value
	      must be free(2)d by the caller.

	      A	 power-user  interface that lets you specify an	unbound	config
	      file, see	unbound.conf(5), which is read for configuration.  Not
	      all  options  are	 relevant.  For	some specific options, such as
	      adding trust anchors, special routines exist.  This function  is
	      thread-safe  only	 if a single instance of ub_ctx* exists	in the
	      application.  If several instances exist the application has  to
	      ensure  that ub_ctx_config is not	called in parallel by the dif-
	      ferent instances.

	      Set machine to forward DNS queries to, the caching  resolver  to
	      use.   IP4 or IP6	address. Forwards all DNS requests to that ma-
	      chine, 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.	 At this time it is only possible to set configuration
	      before the first resolve is done.

	      Set a stub zone, authoritative dns servers to use	for a particu-
	      lar  zone.  IP4 or IP6 address.  If the address is NULL the stub
	      entry is removed.	 Set isprime true if you configure root	 hints
	      with it.	Otherwise similar to the stub zone item	from unbound's
	      config file.  Can	be called several times, for different	zones,
	      or  to  add  multiple  addresses for a particular	zone.  At this
	      time it is only possible to set configuration before  the	 first
	      resolve is done.

	      Enable  DNS over TLS (DoT) for machines set with ub_ctx_set_fwd.
	      At this time it is only possible to set configuration before the
	      first resolve is done.

	      By  default  the root servers are	queried	and full resolver mode
	      is used, but you can use this call to read  the  list  of	 name-
	      servers  to  use	from  the  filename  given.  Usually "/etc/re-
	      solv.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.  If fname NULL is passed, "/etc/re-
	      solv.conf" is used (if on	Windows,  the  system-wide  configured
	      nameserver is picked instead).  At this time it is only possible
	      to set configuration before the first resolve is done.

	      Read  list  of  hosts  from   the	  filename   given.    Usually
	      "/etc/hosts".  When  queried for,	these addresses	are not	marked
	      DNSSEC secure. If	fname NULL is passed, "/etc/hosts" is used (if
	      on  Windows,  etc/hosts from WINDIR is picked instead).  At this
	      time it is only possible to set configuration before  the	 first
	      resolve is done.

	      Add  a  trust  anchor  to	the given context.  At this time it is
	      only possible to add trusted keys	before the  first  resolve  is
	      done.   The format is a string, similar to the zone-file format,
	      [domainname] [type] [rdata contents]. Both DS and	DNSKEY records
	      are accepted.

	      Add  filename  with  automatically  tracked  trust anchor	to the
	      given context.  Pass name	of a file with the managed  trust  an-
	      chor.   You  can create this file	with unbound-anchor(8) for the
	      root anchor.  You	can also create	it with	an initial  file  with
	      one  line	 with a	DNSKEY or DS record.  If the file is writable,
	      it is updated when the trust anchor changes.  At this time it is
	      only  possible  to  add trusted keys before the first resolve is

	      Add trust	anchors	to the given context.  Pass  name  of  a  file
	      with DS and DNSKEY records in zone file format.  At this time it
	      is only possible to add trusted keys before the first resolve is

	      Add  trust  anchors  to  the  given context.  Pass the name of a
	      bind-style config	file with trusted-keys{}.  At this time	it  is
	      only  possible  to  add trusted keys before the first resolve is

	      Set debug	and error log output to	the given stream. Pass NULL to
	      disable  output.	Default	 is stderr. File-names or using	syslog
	      can be enabled using config options, this	routine	is  for	 using
	      your own stream.

	      Set  debug  verbosity  for  the  context.	 Output	is directed to
	      stderr.  Higher debug level gives	more output.

	      Set a context behaviour for  asynchronous	 action.   if  set  to
	      true, enables threading and a call to ub_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 set-
	      ting after ub_resolve_async calls	have been made have no	effect
	      (delete and re-create the	context	to change).

	      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.  Returns 0 if noth-
	      ing to read, or nonzero if a result is available.	  If  nonzero,
	      call ub_process to do callbacks.

	      Wait  for	a context to finish with results. Calls	ub_process af-
	      ter the wait for you. After the wait, there  are	no  more  out-
	      standing asynchronous queries.

       ub_fd  Get  file	 descriptor.  Wait  for	it to become readable, at this
	      point answers are	returned from the asynchronous validating  re-
	      solver.  Then call the ub_process	to continue processing.

	      Call  this routine to continue processing	results	from the vali-
	      dating resolver (when the	fd becomes  readable).	 Will  perform
	      necessary	callbacks.

	      Perform  resolution and validation of the	target name.  The name
	      is a domain name in a zero terminated text string.   The	rrtype
	      and  rrclass are DNS type	and class codes.  The result structure
	      is newly allocated with the resulting data.

	      Perform asynchronous resolution and  validation  of  the	target
	      name.   Arguments	mean the same as for ub_resolve	except no data
	      is returned immediately, instead a  callback  is	called	later.
	      The callback receives a copy of the mydata pointer, that you can
	      use to pass information to the callback. The callback type is  a
	      function pointer to a function declared as

	      void my_callback_function(void* my_arg, int err,
				struct ub_result* result);

	      The  async_id  is	returned so you	can (at	your option) decide to
	      track it and cancel the request if needed.  If you pass  a  NULL
	      pointer the async_id is not returned.

	      Cancel  an async query in	progress.  This	may return an error if
	      the query	does not exist,	or the query is	already	 being	deliv-
	      ered, in that case you may still get a callback for the query.

	      Free struct ub_result contents after use.

	      Convert error value from one of the unbound library functions to
	      a	human readable string.

	      Debug printout the local authority information to	debug output.

	      Add new zone  to	local  authority  info,	 like  local-zone  un-
	      bound.conf(5) statement.

	      Delete zone from local authority info.

	      Add  resource  record  data  to  local  authority	info, like lo-
	      cal-data unbound.conf(5) statement.

	      Delete local authority data from the name	given.

       The result of the DNS resolution	and validation is returned  as	struct
       ub_result. The result structure contains	the following entries.

	    struct ub_result {
		 char* qname; /* text string, original question	*/
		 int qtype;   /* type code asked for */
		 int qclass;  /* class code asked for */
		 char**	data; /* array of rdata	items, NULL terminated*/
		 int* len;    /* array with lengths of rdata items */
		 char* canonname; /* canonical name of result */
		 int rcode;   /* additional error code in case of no data */
		 void* answer_packet; /* full network format answer packet */
		 int answer_len;  /* length of packet in octets	*/
		 int havedata; /* true if there	is data	*/
		 int nxdomain; /* true if nodata because name does not exist */
		 int secure;   /* true if result is secure */
		 int bogus;    /* true if a security failure happened */
		 char* why_bogus; /* string with error if bogus	*/
		 int was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */
		 int ttl;     /* number	of seconds the result is valid */

       If  both	 secure	 and bogus are false, security was not enabled for the
       domain of the query.  Else, they	are not	both  true,  one  of  them  is

       Many routines return an error code. The value 0 (zero) denotes no error
       happened. Other values can be passed to ub_strerror to obtain  a	 read-
       able  error  string.   ub_strerror  returns  a  zero terminated string.
       ub_ctx_create returns NULL on an	error (a malloc	failure).  ub_poll re-
       turns  true  if	some  information  may	be available, false otherwise.
       ub_fd returns a file descriptor or  -1  on  error.   ub_ctx_config  and
       ub_ctx_resolvconf  attempt to leave errno informative on	a function re-
       turn with file read failure.

       unbound.conf(5),	unbound(8).

       Unbound developers are mentioned	in the CREDITS file in	the  distribu-

NLnet Labs			 Aug 12, 2021			 libunbound(3)


Want to link to this manual page? Use this URL:

home | help