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

FUNCTIONS

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

RESULT DATA STRUCTURE

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

RETURN VALUES

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

SEE ALSO

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

AUTHORS

343       Unbound  developers  are mentioned in the CREDITS file in the distribu‐
344       tion.
345
346
347
348NLnet Labs                       Jun 21, 2018                    libunbound(3)
Impressum