1libunbound(3) unbound 1.16.0 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_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.16.0 functions.
16
18 #include <unbound.h>
19 struct ub_ctx * ub_ctx_create(void);
21 void ub_ctx_delete(struct ub_ctx* ctx);
23 int ub_ctx_set_option(struct ub_ctx* ctx, char* opt, char* val);
25 int ub_ctx_get_option(struct ub_ctx* ctx, char* opt, char** val);
27 int ub_ctx_config(struct ub_ctx* ctx, char* fname);
29 int ub_ctx_set_fwd(struct ub_ctx* ctx, char* addr);
31 int ub_ctx_set_stub(struct ub_ctx* ctx, char* zone, char* addr,
33 int isprime);
34 int ub_ctx_set_tls(struct ub_ctx* ctx, int tls);
36 int ub_ctx_resolvconf(struct ub_ctx* ctx, char* fname);
38 int ub_ctx_hosts(struct ub_ctx* ctx, char* fname);
40 int ub_ctx_add_ta(struct ub_ctx* ctx, char* ta);
42 int ub_ctx_add_ta_autr(struct ub_ctx* ctx, char* fname);
44 int ub_ctx_add_ta_file(struct ub_ctx* ctx, char* fname);
46 int ub_ctx_trustedkeys(struct ub_ctx* ctx, char* fname);
48 int ub_ctx_debugout(struct ub_ctx* ctx, FILE* out);
50 int ub_ctx_debuglevel(struct ub_ctx* ctx, int d);
52 int ub_ctx_async(struct ub_ctx* ctx, int dothread);
54 int ub_poll(struct ub_ctx* ctx);
56 int ub_wait(struct ub_ctx* ctx);
58 int ub_fd(struct ub_ctx* ctx);
60 int ub_process(struct ub_ctx* ctx);
62 int ub_resolve(struct ub_ctx* ctx, char* name,
64 int rrtype, int rrclass, struct ub_result** result);
65 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 int ub_cancel(struct ub_ctx* ctx, int async_id);
71 void ub_resolve_free(struct ub_result* result);
73 const char * ub_strerror(int err);
75 int ub_ctx_print_local_zones(struct ub_ctx* ctx);
77 int ub_ctx_zone_add(struct ub_ctx* ctx, char* zone_name, char*
79 zone_type);
80 int ub_ctx_zone_remove(struct ub_ctx* ctx, char* zone_name);
82 int ub_ctx_data_add(struct ub_ctx* ctx, char* data);
84 int ub_ctx_data_remove(struct ub_ctx* ctx, char* data);
86
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 li‐
90 brary. 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 re‐
94 sults with DNSSEC.
95 The library uses a variable of type struct ub_ctx to keep context be‐
97 tween calls. The user must maintain it, creating it with ub_ctx_create
98 and deleting it with ub_ctx_delete. It can be created and deleted at
99 any time. Creating it anew removes any previous configuration (such as
100 trusted keys) and clears any cached results.
101 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 The functions are discussed in turn below.
109
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 de‐
114 fault. Use ub_ctx_resolvconf and ub_ctx_hosts to read them. Be‐
115 fore 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 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 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 op‐
129 tions are relevant. For some specific options, such as adding
130 trust anchors, special routines exist. Pass the option name with
131 the trailing ':'.
132 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 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 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 ma‐
152 chine, 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 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 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 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 "/etc/re‐
177 solv.conf". Uses those nameservers as caching proxies. If they
178 do not support DNSSEC, validation may fail. Only nameservers
179 are picked up, the searchdomain, ndots and other settings from
180 resolv.conf(5) are ignored. If fname NULL is passed, "/etc/re‐
181 solv.conf" is used (if on Windows, the system-wide configured
182 nameserver is picked instead). At this time it is only possible
183 to set configuration before the first resolve is done.
184 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 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 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 an‐
203 chor. 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 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 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 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 ub_ctx_debuglevel
229 Set debug verbosity for the context. Output is directed to
230 stderr. Higher debug level gives more output.
231 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 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 ub_wait
248 Wait for a context to finish with results. Calls ub_process af‐
249 ter the wait for you. After the wait, there are no more out‐
250 standing asynchronous queries.
251 ub_fd Get file descriptor. Wait for it to become readable, at this
253 point answers are returned from the asynchronous validating re‐
254 solver. Then call the ub_process to continue processing.
255 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 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 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 void my_callback_function(void* my_arg, int err,
276 struct ub_result* result);
277 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 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 ub_resolve_free
288 Free struct ub_result contents after use.
289 ub_strerror
291 Convert error value from one of the unbound library functions to
292 a human readable string.
293 ub_ctx_print_local_zones
295 Debug printout the local authority information to debug output.
296 ub_ctx_zone_add
298 Add new zone to local authority info, like local-zone un‐
299 bound.conf(5) statement.
300 ub_ctx_zone_remove
302 Delete zone from local authority info.
303 ub_ctx_data_add
305 Add resource record data to local authority info, like lo‐
306 cal-data unbound.conf(5) statement.
307 ub_ctx_data_remove
309 Delete local authority data from the name given.
310
312 The result of the DNS resolution and validation is returned as struct
313 ub_result. The result structure contains the following entries.
314 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 was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */
331 int ttl; /* number of seconds the result is valid */
332 };
333 If both secure and bogus are false, security was not enabled for the
335 domain of the query. Else, they are not both true, one of them is
336 true.
337
339 Many routines return an error code. The value 0 (zero) denotes no error
340 happened. Other values can be passed to ub_strerror to obtain a read‐
341 able error string. ub_strerror returns a zero terminated string.
342 ub_ctx_create returns NULL on an error (a malloc failure). ub_poll re‐
343 turns true if some information may be available, false otherwise.
344 ub_fd returns a file descriptor or -1 on error. ub_ctx_config and
345 ub_ctx_resolvconf attempt to leave errno informative on a function re‐
346 turn with file read failure.
347
349 unbound.conf(5), unbound(8).
350
352 Unbound developers are mentioned in the CREDITS file in the distribu‐
353 tion.
354NLnet Labs Jun 2, 2022 libunbound(3)