1libunbound(3)                    unbound 1.6.6                   libunbound(3)
2
3
4

NAME

6       libunbound, unbound.h, ub_ctx, ub_result, ub_callback_type, ub_ctx_cre‐
7       ate, ub_ctx_delete, ub_ctx_set_option,  ub_ctx_get_option,  ub_ctx_con‐
8       fig,  ub_ctx_set_fwd, ub_ctx_set_stub, ub_ctx_resolvconf, ub_ctx_hosts,
9       ub_ctx_add_ta, ub_ctx_add_ta_autr, ub_ctx_add_ta_file,  ub_ctx_trusted‐
10       keys,   ub_ctx_debugout,   ub_ctx_debuglevel,   ub_ctx_async,  ub_poll,
11       ub_wait, ub_fd, ub_process,  ub_resolve,  ub_resolve_async,  ub_cancel,
12       ub_resolve_free,         ub_strerror,         ub_ctx_print_local_zones,
13       ub_ctx_zone_add,          ub_ctx_zone_remove,          ub_ctx_data_add,
14       ub_ctx_data_remove - Unbound DNS validating resolver 1.6.6 functions.
15

SYNOPSIS

17       #include <unbound.h>
18
19       struct ub_ctx * ub_ctx_create(void);
20
21       void ub_ctx_delete(struct ub_ctx* ctx);
22
23       int ub_ctx_set_option(struct ub_ctx* ctx, char* opt, char* val);
24
25       int ub_ctx_get_option(struct ub_ctx* ctx, char* opt, char** val);
26
27       int ub_ctx_config(struct ub_ctx* ctx, char* fname);
28
29       int ub_ctx_set_fwd(struct ub_ctx* ctx, char* addr);
30
31       int ub_ctx_set_stub(struct ub_ctx* ctx, char* zone, char* addr,
32                 int isprime);
33
34       int ub_ctx_resolvconf(struct ub_ctx* ctx, char* fname);
35
36       int ub_ctx_hosts(struct ub_ctx* ctx, char* fname);
37
38       int ub_ctx_add_ta(struct ub_ctx* ctx, char* ta);
39
40       int ub_ctx_add_ta_autr(struct ub_ctx* ctx, char* fname);
41
42       int ub_ctx_add_ta_file(struct ub_ctx* ctx, char* fname);
43
44       int ub_ctx_trustedkeys(struct ub_ctx* ctx, char* fname);
45
46       int ub_ctx_debugout(struct ub_ctx* ctx, FILE* out);
47
48       int ub_ctx_debuglevel(struct ub_ctx* ctx, int d);
49
50       int ub_ctx_async(struct ub_ctx* ctx, int dothread);
51
52       int ub_poll(struct ub_ctx* ctx);
53
54       int ub_wait(struct ub_ctx* ctx);
55
56       int ub_fd(struct ub_ctx* ctx);
57
58       int ub_process(struct ub_ctx* ctx);
59
60       int ub_resolve(struct ub_ctx* ctx, char* name,
61                  int rrtype, int rrclass, struct ub_result** result);
62
63       int ub_resolve_async(struct ub_ctx* ctx, char* name,
64                        int rrtype, int rrclass, void* mydata,
65                        ub_callback_type callback, int* async_id);
66
67       int ub_cancel(struct ub_ctx* ctx, int async_id);
68
69       void ub_resolve_free(struct ub_result* result);
70
71       const char * ub_strerror(int err);
72
73       int ub_ctx_print_local_zones(struct ub_ctx* ctx);
74
75       int   ub_ctx_zone_add(struct   ub_ctx*   ctx,  char*  zone_name,  char*
76       zone_type);
77
78       int ub_ctx_zone_remove(struct ub_ctx* ctx, char* zone_name);
79
80       int ub_ctx_data_add(struct ub_ctx* ctx, char* data);
81
82       int ub_ctx_data_remove(struct ub_ctx* ctx, char* data);
83

DESCRIPTION

85       Unbound is an implementation of a DNS resolver, that does  caching  and
86       DNSSEC  validation.  This  is  the library API, for using the -lunbound
87       library.  The server daemon is described in  unbound(8).   The  library
88       can  be used to convert hostnames to ip addresses, and back, and obtain
89       other information from the DNS. The library performs public-key valida‐
90       tion of results with DNSSEC.
91
92       The  library  uses  a  variable  of  type struct ub_ctx to keep context
93       between calls. The user must maintain it, creating it with  ub_ctx_cre‐
94       ate  and deleting it with ub_ctx_delete.  It can be created and deleted
95       at any time. Creating it anew removes any previous configuration  (such
96       as trusted keys) and clears any cached results.
97
98       The  functions  are thread-safe, and a context an be used in a threaded
99       (as well as in a non-threaded) environment. Also resolution (and  vali‐
100       dation)  can  be performed blocking and non-blocking (also called asyn‐
101       chronous).  The async method returns from the call immediately, so that
102       processing can go on, while the results become available later.
103
104       The functions are discussed in turn below.
105

FUNCTIONS

107       ub_ctx_create
108              Create  a  new context, initialised with defaults.  The informa‐
109              tion from /etc/resolv.conf and /etc/hosts  is  not  utilised  by
110              default.  Use  ub_ctx_resolvconf  and ub_ctx_hosts to read them.
111              Before   you   call   this,   use    the    openssl    functions
112              CRYPTO_set_id_callback and CRYPTO_set_locking_callback to set up
113              asynchronous operation if you use lib openssl  (the  application
114              calls  these  functions once for initialisation).  Openssl 1.0.0
115              or later uses the CRYPTO_THREADID_set_callback function.
116
117       ub_ctx_delete
118              Delete validation context and free associated  resources.   Out‐
119              standing  async  queries are killed and callbacks are not called
120              for them.
121
122       ub_ctx_set_option
123              A power-user interface that lets you specify one of the  options
124              from  the  config  file  format,  see  unbound.conf(5).  Not all
125              options are relevant. For some specific options, such as  adding
126              trust anchors, special routines exist. Pass the option name with
127              the trailing ':'.
128
129       ub_ctx_get_option
130              A power-user interface that gets an option value.  Some  options
131              cannot  be  gotten,  and others return a newline separated list.
132              Pass the option name without trailing ':'.  The  returned  value
133              must be free(2)d by the caller.
134
135       ub_ctx_config
136              A  power-user  interface that lets you specify an unbound config
137              file, see unbound.conf(5), which is read for configuration.  Not
138              all  options  are  relevant.  For some specific options, such as
139              adding trust anchors, special routines exist.
140
141       ub_ctx_set_fwd
142              Set machine to forward DNS queries to, the caching  resolver  to
143              use.   IP4  or  IP6  address.  Forwards all DNS requests to that
144              machine, which is expected to run a recursive resolver.  If  the
145              proxy  is not DNSSEC capable, validation may fail. Can be called
146              several times, in that case the addresses  are  used  as  backup
147              servers.   At this time it is only possible to set configuration
148              before the first resolve is done.
149
150       ub_ctx_set_stub
151              Set a stub zone, authoritative dns servers to use for a particu‐
152              lar  zone.  IP4 or IP6 address.  If the address is NULL the stub
153              entry is removed.  Set isprime true if you configure root  hints
154              with it.  Otherwise similar to the stub zone item from unbound's
155              config file.  Can be called several times, for different  zones,
156              or  to  add  multiple  addresses for a particular zone.  At this
157              time it is only possible to set configuration before  the  first
158              resolve is done.
159
160       ub_ctx_resolvconf
161              By  default  the root servers are queried and full resolver mode
162              is used, but you can use this call to read  the  list  of  name‐
163              servers    to    use   from   the   filename   given.    Usually
164              "/etc/resolv.conf". Uses those nameservers as  caching  proxies.
165              If  they do not support DNSSEC, validation may fail.  Only name‐
166              servers are picked up, the searchdomain, ndots  and  other  set‐
167              tings from resolv.conf(5) are ignored.  If fname NULL is passed,
168              "/etc/resolv.conf" is used (if on Windows, the system-wide  con‐
169              figured  nameserver is picked instead).  At this time it is only
170              possible to set configuration before the first resolve is done.
171
172       ub_ctx_hosts
173              Read  list  of  hosts  from   the   filename   given.    Usually
174              "/etc/hosts".  When  queried for, these addresses are not marked
175              DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used (if
176              on  Windows,  etc/hosts from WINDIR is picked instead).  At this
177              time it is only possible to set configuration before  the  first
178              resolve is done.
179
180       ub_ctx_add_ta
181              Add  a  trust  anchor  to the given context.  At this time it is
182              only possible to add trusted keys before the  first  resolve  is
183              done.   The format is a string, similar to the zone-file format,
184              [domainname] [type] [rdata contents]. Both DS and DNSKEY records
185              are accepted.
186
187       ub_ctx_add_ta_autr
188              Add  filename  with  automatically  tracked  trust anchor to the
189              given context.  Pass name of  a  file  with  the  managed  trust
190              anchor.  You can create this file with unbound-anchor(8) for the
191              root anchor.  You can also create it with an initial  file  with
192              one  line  with a DNSKEY or DS record.  If the file is writable,
193              it is updated when the trust anchor changes.  At this time it is
194              only  possible  to  add trusted keys before the first resolve is
195              done.
196
197       ub_ctx_add_ta_file
198              Add trust anchors to the given context.  Pass  name  of  a  file
199              with DS and DNSKEY records in zone file format.  At this time it
200              is only possible to add trusted keys before the first resolve is
201              done.
202
203       ub_ctx_trustedkeys
204              Add  trust  anchors  to  the  given context.  Pass the name of a
205              bind-style config file with trusted-keys{}.  At this time it  is
206              only  possible  to  add trusted keys before the first resolve is
207              done.
208
209       ub_ctx_debugout
210              Set debug and error log output to the given stream. Pass NULL to
211              disable  output.  Default  is stderr. File-names or using syslog
212              can be enabled using config options, this routine is  for  using
213              your own stream.
214
215       ub_ctx_debuglevel
216              Set  debug  verbosity  for  the  context.  Output is directed to
217              stderr.  Higher debug level gives more output.
218
219       ub_ctx_async
220              Set a context behaviour for  asynchronous  action.   if  set  to
221              true, enables threading and a call to ub_resolve_async creates a
222              thread to handle work in the background.  If false, a process is
223              forked  to  handle work in the background.  Changes to this set‐
224              ting after ub_resolve_async calls have been made have no  effect
225              (delete and re-create the context to change).
226
227       ub_poll
228              Poll a context to see if it has any new results.  Do not poll in
229              a loop, instead extract the fd below to poll for readiness,  and
230              then  check, or wait using the wait routine.  Returns 0 if noth‐
231              ing to read, or nonzero if a result is available.   If  nonzero,
232              call ub_process to do callbacks.
233
234       ub_wait
235              Wait  for  a  context  to  finish with results. Calls ub_process
236              after the wait for you. After the wait, there are no  more  out‐
237              standing asynchronous queries.
238
239       ub_fd  Get  file  descriptor.  Wait  for it to become readable, at this
240              point answers are  returned  from  the  asynchronous  validating
241              resolver.  Then call the ub_process to continue processing.
242
243       ub_process
244              Call  this routine to continue processing results from the vali‐
245              dating resolver (when the fd becomes  readable).   Will  perform
246              necessary callbacks.
247
248       ub_resolve
249              Perform  resolution and validation of the target name.  The name
250              is a domain name in a zero terminated text string.   The  rrtype
251              and  rrclass are DNS type and class codes.  The result structure
252              is newly allocated with the resulting data.
253
254       ub_resolve_async
255              Perform asynchronous resolution and  validation  of  the  target
256              name.   Arguments mean the same as for ub_resolve except no data
257              is returned immediately, instead a  callback  is  called  later.
258              The callback receives a copy of the mydata pointer, that you can
259              use to pass information to the callback. The callback type is  a
260              function pointer to a function declared as
261
262              void my_callback_function(void* my_arg, int err,
263                                struct ub_result* result);
264
265              The  async_id  is returned so you can (at your option) decide to
266              track it and cancel the request if needed.  If you pass  a  NULL
267              pointer the async_id is not returned.
268
269       ub_cancel
270              Cancel  an async query in progress.  This may return an error if
271              the query does not exist, or the query is already  being  deliv‐
272              ered, in that case you may still get a callback for the query.
273
274       ub_resolve_free
275              Free struct ub_result contents after use.
276
277       ub_strerror
278              Convert error value from one of the unbound library functions to
279              a human readable string.
280
281       ub_ctx_print_local_zones
282              Debug printout the local authority information to debug output.
283
284       ub_ctx_zone_add
285              Add  new  zone  to  local  authority   info,   like   local-zone
286              unbound.conf(5) statement.
287
288       ub_ctx_zone_remove
289              Delete zone from local authority info.
290
291       ub_ctx_data_add
292              Add   resource   record  data  to  local  authority  info,  like
293              local-data unbound.conf(5) statement.
294
295       ub_ctx_data_remove
296              Delete local authority data from the name given.
297

RESULT DATA STRUCTURE

299       The result of the DNS resolution and validation is returned  as  struct
300       ub_result. The result structure contains the following entries.
301
302            struct ub_result {
303                 char* qname; /* text string, original question */
304                 int qtype;   /* type code asked for */
305                 int qclass;  /* class code asked for */
306                 char** data; /* array of rdata items, NULL terminated*/
307                 int* len;    /* array with lengths of rdata items */
308                 char* canonname; /* canonical name of result */
309                 int rcode;   /* additional error code in case of no data */
310                 void* answer_packet; /* full network format answer packet */
311                 int answer_len; /* length of packet in octets */
312                 int havedata; /* true if there is data */
313                 int nxdomain; /* true if nodata because name does not exist */
314                 int secure;  /* true if result is secure */
315                 int bogus;   /* true if a security failure happened */
316                 char* why_bogus; /* string with error if bogus */
317                 int ttl;     /* number of seconds the result is valid */
318            };
319
320       If  both  secure  and bogus are false, security was not enabled for the
321       domain of the query.  Else, they are not both  true,  one  of  them  is
322       true.
323

RETURN VALUES

325       Many routines return an error code. The value 0 (zero) denotes no error
326       happened. Other values can be passed to ub_strerror to obtain  a  read‐
327       able  error  string.   ub_strerror  returns  a  zero terminated string.
328       ub_ctx_create returns NULL on an error  (a  malloc  failure).   ub_poll
329       returns  true  if  some  information may be available, false otherwise.
330       ub_fd returns a file descriptor or -1 on error.
331

SEE ALSO

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

AUTHORS

336       Unbound developers are mentioned in the CREDITS file in  the  distribu‐
337       tion.
338
339
340
341NLnet Labs                       Sep 18, 2017                    libunbound(3)
Impressum