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

NAME

6       libunbound, unbound.h, ub_ctx, ub_result, ub_callback_t, ub_ctx_create,
7       ub_ctx_delete,  ub_ctx_set_option,  ub_ctx_get_option,   ub_ctx_config,
8       ub_ctx_set_fwd,    ub_ctx_resolvconf,    ub_ctx_hosts,   ub_ctx_add_ta,
9       ub_ctx_add_ta_file, ub_ctx_trustedkeys,  ub_ctx_debugout,  ub_ctx_debu‐
10       glevel,  ub_ctx_async, ub_poll, ub_wait, ub_fd, ub_process, ub_resolve,
11       ub_resolve_async,     ub_cancel,     ub_resolve_free,      ub_strerror,
12       ub_ctx_print_local_zones,      ub_ctx_zone_add,     ub_ctx_zone_remove,
13       ub_ctx_data_add, ub_ctx_data_remove - Unbound DNS  validating  resolver
14       1.4.20 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_resolvconf(struct ub_ctx* ctx, char* fname);
32
33       int ub_ctx_hosts(struct ub_ctx* ctx, char* fname);
34
35       int ub_ctx_add_ta(struct ub_ctx* ctx, char* ta);
36
37       int ub_ctx_add_ta_file(struct ub_ctx* ctx, char* fname);
38
39       int ub_ctx_trustedkeys(struct ub_ctx* ctx, char* fname);
40
41       int ub_ctx_debugout(struct ub_ctx* ctx, FILE* out);
42
43       int ub_ctx_debuglevel(struct ub_ctx* ctx, int d);
44
45       int ub_ctx_async(struct ub_ctx* ctx, int dothread);
46
47       int ub_poll(struct ub_ctx* ctx);
48
49       int ub_wait(struct ub_ctx* ctx);
50
51       int ub_fd(struct ub_ctx* ctx);
52
53       int ub_process(struct ub_ctx* ctx);
54
55       int ub_resolve(struct ub_ctx* ctx, char* name,
56                  int rrtype, int rrclass, struct ub_result** result);
57
58       int ub_resolve_async(struct ub_ctx* ctx, char* name,
59                        int rrtype, int rrclass, void* mydata,
60                        ub_callback_t callback, int* async_id);
61
62       int ub_cancel(struct ub_ctx* ctx, int async_id);
63
64       void ub_resolve_free(struct ub_result* result);
65
66       const char * ub_strerror(int err);
67
68       int ub_ctx_print_local_zones(struct ub_ctx* ctx);
69
70       int   ub_ctx_zone_add(struct   ub_ctx*   ctx,  char*  zone_name,  char*
71       zone_type);
72
73       int ub_ctx_zone_remove(struct ub_ctx* ctx, char* zone_name);
74
75       int ub_ctx_data_add(struct ub_ctx* ctx, char* data);
76
77       int ub_ctx_data_remove(struct ub_ctx* ctx, char* data);
78

DESCRIPTION

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

FUNCTIONS

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

RESULT DATA STRUCTURE

269       The  result  of the DNS resolution and validation is returned as struct
270       ub_result. The result structure contains the following entries.
271
272            struct ub_result {
273                 char* qname; /* text string, original question */
274                 int qtype;   /* type code asked for */
275                 int qclass;  /* class code asked for */
276                 char** data; /* array of rdata items, NULL terminated*/
277                 int* len;    /* array with lengths of rdata items */
278                 char* canonname; /* canonical name of result */
279                 int rcode;   /* additional error code in case of no data */
280                 void* answer_packet; /* full network format answer packet */
281                 int answer_len; /* length of packet in octets */
282                 int havedata; /* true if there is data */
283                 int nxdomain; /* true if nodata because name does not exist */
284                 int secure;  /* true if result is secure */
285                 int bogus;   /* true if a security failure happened */
286                 char* why_bogus; /* string with error if bogus */
287                 int ttl;     /* number of seconds the result is valid */
288            };
289
290       If both secure and bogus are false, security was not  enabled  for  the
291       domain of the query.
292

RETURN VALUES

294       Many routines return an error code. The value 0 (zero) denotes no error
295       happened. Other values can be passed to ub_strerror to obtain  a  read‐
296       able  error  string.   ub_strerror  returns  a  zero terminated string.
297       ub_ctx_create returns NULL on an error  (a  malloc  failure).   ub_poll
298       returns  true  if  some  information may be available, false otherwise.
299       ub_fd returns a file descriptor or -1 on error.
300

SEE ALSO

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

AUTHORS

305       Unbound developers are mentioned in the CREDITS file in  the  distribu‐
306       tion.
307
308
309
310NLnet Labs                       Mar 21, 2013                    libunbound(3)
Impressum