1libunbound(3)                    unbound 1.9.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_set_tls, ub_ctx_resolv‐
9       conf,      ub_ctx_hosts,       ub_ctx_add_ta,       ub_ctx_add_ta_autr,
10       ub_ctx_add_ta_file,  ub_ctx_trustedkeys,  ub_ctx_debugout, ub_ctx_debu‐
11       glevel, ub_ctx_async, ub_poll, ub_wait, ub_fd, ub_process,  ub_resolve,
12       ub_resolve_async,      ub_cancel,     ub_resolve_free,     ub_strerror,
13       ub_ctx_print_local_zones,     ub_ctx_zone_add,      ub_ctx_zone_remove,
14       ub_ctx_data_add,  ub_ctx_data_remove  - Unbound DNS validating resolver
15       1.9.6 functions.
16

SYNOPSIS

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

DESCRIPTION

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

FUNCTIONS

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

RESULT DATA STRUCTURE

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

RETURN VALUES

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

SEE ALSO

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

AUTHORS

351       Unbound developers are mentioned in the CREDITS file in  the  distribu‐
352       tion.
353
354
355
356NLnet Labs                       dec 12, 2019                    libunbound(3)
Impressum