1libunbound(3) unbound 1.4.20 libunbound(3)
2
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
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_resolvconf(struct ub_ctx* ctx, char* fname);
32 int ub_ctx_hosts(struct ub_ctx* ctx, char* fname);
34 int ub_ctx_add_ta(struct ub_ctx* ctx, char* ta);
36 int ub_ctx_add_ta_file(struct ub_ctx* ctx, char* fname);
38 int ub_ctx_trustedkeys(struct ub_ctx* ctx, char* fname);
40 int ub_ctx_debugout(struct ub_ctx* ctx, FILE* out);
42 int ub_ctx_debuglevel(struct ub_ctx* ctx, int d);
44 int ub_ctx_async(struct ub_ctx* ctx, int dothread);
46 int ub_poll(struct ub_ctx* ctx);
48 int ub_wait(struct ub_ctx* ctx);
50 int ub_fd(struct ub_ctx* ctx);
52 int ub_process(struct ub_ctx* ctx);
54 int ub_resolve(struct ub_ctx* ctx, char* name,
56 int rrtype, int rrclass, struct ub_result** result);
57 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 int ub_cancel(struct ub_ctx* ctx, int async_id);
63 void ub_resolve_free(struct ub_result* result);
65 const char * ub_strerror(int err);
67 int ub_ctx_print_local_zones(struct ub_ctx* ctx);
69 int ub_ctx_zone_add(struct ub_ctx* ctx, char* zone_name, char*
71 zone_type);
72 int ub_ctx_zone_remove(struct ub_ctx* ctx, char* zone_name);
74 int ub_ctx_data_add(struct ub_ctx* ctx, char* data);
76 int ub_ctx_data_remove(struct ub_ctx* ctx, char* data);
78
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 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 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 The functions are discussed in turn below.
100
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 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 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 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 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 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 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 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 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 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 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 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 ub_ctx_debuglevel
186 Set debug verbosity for the context. Output is directed to
187 stderr. Higher debug level gives more output.
188 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 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 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 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 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 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 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 void my_callback_function(void* my_arg, int err,
233 struct ub_result* result);
234 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 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 ub_resolve_free
245 Free struct ub_result contents after use.
246 ub_strerror
248 Convert error value from one of the unbound library functions to
249 a human readable string.
250 ub_ctx_print_local_zones
252 Debug printout the local authority information to debug output.
253 ub_ctx_zone_add
255 Add new zone to local authority info, like local-zone
256 unbound.conf(5) statement.
257 ub_ctx_zone_remove
259 Delete zone from local authority info.
260 ub_ctx_data_add
262 Add resource record data to local authority info, like
263 local-data unbound.conf(5) statement.
264 ub_ctx_data_remove
266 Delete local authority data from the name given.
267
269 The result of the DNS resolution and validation is returned as struct
270 ub_result. The result structure contains the following entries.
271 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 If both secure and bogus are false, security was not enabled for the
291 domain of the query.
292
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
302 unbound.conf(5), unbound(8).
303
305 Unbound developers are mentioned in the CREDITS file in the distribu‐
306 tion.
307NLnet Labs Mar 21, 2013 libunbound(3)