1libunbound(3) unbound 1.6.6 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.6.6 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 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 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 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 The functions are discussed in turn below.
105
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 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 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 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 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 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 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 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 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 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 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 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 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 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 ub_ctx_debuglevel
216 Set debug verbosity for the context. Output is directed to
217 stderr. Higher debug level gives more output.
218 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 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 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 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 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 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 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 void my_callback_function(void* my_arg, int err,
263 struct ub_result* result);
264 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 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 ub_resolve_free
275 Free struct ub_result contents after use.
276 ub_strerror
278 Convert error value from one of the unbound library functions to
279 a human readable string.
280 ub_ctx_print_local_zones
282 Debug printout the local authority information to debug output.
283 ub_ctx_zone_add
285 Add new zone to local authority info, like local-zone
286 unbound.conf(5) statement.
287 ub_ctx_zone_remove
289 Delete zone from local authority info.
290 ub_ctx_data_add
292 Add resource record data to local authority info, like
293 local-data unbound.conf(5) statement.
294 ub_ctx_data_remove
296 Delete local authority data from the name given.
297
299 The result of the DNS resolution and validation is returned as struct
300 ub_result. The result structure contains the following entries.
301 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 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
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
333 unbound.conf(5), unbound(8).
334
336 Unbound developers are mentioned in the CREDITS file in the distribu‐
337 tion.
338NLnet Labs Sep 18, 2017 libunbound(3)