1libunbound(3) unbound 1.8.3 libunbound(3)
2
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.8.3 functions.
15
17 #include <unbound.h>
18 struct ub_ctx * ub_ctx_create(void);
20 void ub_ctx_delete(struct ub_ctx* ctx);
22 int ub_ctx_set_option(struct ub_ctx* ctx, char* opt, char* val);
24 int ub_ctx_get_option(struct ub_ctx* ctx, char* opt, char** val);
26 int ub_ctx_config(struct ub_ctx* ctx, char* fname);
28 int ub_ctx_set_fwd(struct ub_ctx* ctx, char* addr);
30 int ub_ctx_set_stub(struct ub_ctx* ctx, char* zone, char* addr,
32 int isprime);
33 int ub_ctx_resolvconf(struct ub_ctx* ctx, char* fname);
35 int ub_ctx_hosts(struct ub_ctx* ctx, char* fname);
37 int ub_ctx_add_ta(struct ub_ctx* ctx, char* ta);
39 int ub_ctx_add_ta_autr(struct ub_ctx* ctx, char* fname);
41 int ub_ctx_add_ta_file(struct ub_ctx* ctx, char* fname);
43 int ub_ctx_trustedkeys(struct ub_ctx* ctx, char* fname);
45 int ub_ctx_debugout(struct ub_ctx* ctx, FILE* out);
47 int ub_ctx_debuglevel(struct ub_ctx* ctx, int d);
49 int ub_ctx_async(struct ub_ctx* ctx, int dothread);
51 int ub_poll(struct ub_ctx* ctx);
53 int ub_wait(struct ub_ctx* ctx);
55 int ub_fd(struct ub_ctx* ctx);
57 int ub_process(struct ub_ctx* ctx);
59 int ub_resolve(struct ub_ctx* ctx, char* name,
61 int rrtype, int rrclass, struct ub_result** result);
62 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 int ub_cancel(struct ub_ctx* ctx, int async_id);
68 void ub_resolve_free(struct ub_result* result);
70 const char * ub_strerror(int err);
72 int ub_ctx_print_local_zones(struct ub_ctx* ctx);
74 int ub_ctx_zone_add(struct ub_ctx* ctx, char* zone_name, char*
76 zone_type);
77 int ub_ctx_zone_remove(struct ub_ctx* ctx, char* zone_name);
79 int ub_ctx_data_add(struct ub_ctx* ctx, char* data);
81 int ub_ctx_data_remove(struct ub_ctx* ctx, char* data);
83
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 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 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 The functions are discussed in turn below.
106
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 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 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 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 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 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 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 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 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 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 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 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 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 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 ub_ctx_debuglevel
221 Set debug verbosity for the context. Output is directed to
222 stderr. Higher debug level gives more output.
223 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 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 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 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 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 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 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 void my_callback_function(void* my_arg, int err,
268 struct ub_result* result);
269 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 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 ub_resolve_free
280 Free struct ub_result contents after use.
281 ub_strerror
283 Convert error value from one of the unbound library functions to
284 a human readable string.
285 ub_ctx_print_local_zones
287 Debug printout the local authority information to debug output.
288 ub_ctx_zone_add
290 Add new zone to local authority info, like local-zone
291 unbound.conf(5) statement.
292 ub_ctx_zone_remove
294 Delete zone from local authority info.
295 ub_ctx_data_add
297 Add resource record data to local authority info, like
298 local-data unbound.conf(5) statement.
299 ub_ctx_data_remove
301 Delete local authority data from the name given.
302
304 The result of the DNS resolution and validation is returned as struct
305 ub_result. The result structure contains the following entries.
306 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 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
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
340 unbound.conf(5), unbound(8).
341
343 Unbound developers are mentioned in the CREDITS file in the distribu‐
344 tion.
345NLnet Labs Dec 11, 2018 libunbound(3)