1.. 2 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 3 4.. 5 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 6 7.. 8 IT HELPS PEOPLE DIFFING THE CHANGES 9 10.. 11 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 12 13.. 14 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 15 16.. 17 IT HELPS PEOPLE DIFFING THE CHANGES 18 19.. 20 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 21 22.. 23 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 24 25.. 26 IT HELPS PEOPLE DIFFING THE CHANGES 27 28.. 29 WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE 30 31.. 32 IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE 33 34.. 35 IT HELPS PEOPLE DIFFING THE CHANGES 36 37libunbound(3) 38============= 39 40Synopsis 41-------- 42 43.. only:: html 44 45 .. code-block:: c 46 47 #include <unbound.h> 48 49 struct ub_ctx * ub_ctx_create(void); 50 51 void ub_ctx_delete(struct ub_ctx* ctx); 52 53 int ub_ctx_set_option(struct ub_ctx* ctx, char* opt, char* val); 54 55 int ub_ctx_get_option(struct ub_ctx* ctx, char* opt, char** val); 56 57 int ub_ctx_config(struct ub_ctx* ctx, char* fname); 58 59 int ub_ctx_set_fwd(struct ub_ctx* ctx, char* addr); 60 61 int ub_ctx_set_stub(struct ub_ctx* ctx, char* zone, char* addr, 62 int isprime); 63 64 int ub_ctx_set_tls(struct ub_ctx* ctx, int tls); 65 66 int ub_ctx_resolvconf(struct ub_ctx* ctx, char* fname); 67 68 int ub_ctx_hosts(struct ub_ctx* ctx, char* fname); 69 70 int ub_ctx_add_ta(struct ub_ctx* ctx, char* ta); 71 72 int ub_ctx_add_ta_autr(struct ub_ctx* ctx, char* fname); 73 74 int ub_ctx_add_ta_file(struct ub_ctx* ctx, char* fname); 75 76 int ub_ctx_trustedkeys(struct ub_ctx* ctx, char* fname); 77 78 int ub_ctx_debugout(struct ub_ctx* ctx, FILE* out); 79 80 int ub_ctx_debuglevel(struct ub_ctx* ctx, int d); 81 82 int ub_ctx_async(struct ub_ctx* ctx, int dothread); 83 84 int ub_poll(struct ub_ctx* ctx); 85 86 int ub_wait(struct ub_ctx* ctx); 87 88 int ub_fd(struct ub_ctx* ctx); 89 90 int ub_process(struct ub_ctx* ctx); 91 92 int ub_resolve(struct ub_ctx* ctx, char* name, int rrtype, 93 int rrclass, struct ub_result** result); 94 95 int ub_resolve_async(struct ub_ctx* ctx, char* name, int rrtype, 96 int rrclass, void* mydata, ub_callback_type callback, 97 int* async_id); 98 99 int ub_cancel(struct ub_ctx* ctx, int async_id); 100 101 void ub_resolve_free(struct ub_result* result); 102 103 const char * ub_strerror(int err); 104 105 int ub_ctx_print_local_zones(struct ub_ctx* ctx); 106 107 int ub_ctx_zone_add(struct ub_ctx* ctx, char* zone_name, char* zone_type); 108 109 int ub_ctx_zone_remove(struct ub_ctx* ctx, char* zone_name); 110 111 int ub_ctx_data_add(struct ub_ctx* ctx, char* data); 112 113 int ub_ctx_data_remove(struct ub_ctx* ctx, char* data); 114 115.. only:: man 116 117 **#include <unbound.h>** 118 119 struct ub_ctx \* **ub_ctx_create**\ (void); 120 121 void **ub_ctx_delete**\ (struct ub_ctx\* ctx); 122 123 int **ub_ctx_set_option**\ (struct ub_ctx\* ctx, char\* opt, char\* val); 124 125 int **ub_ctx_get_option**\ (struct ub_ctx\* ctx, char\* opt, char\*\* val); 126 127 int **ub_ctx_config**\ (struct ub_ctx\* ctx, char* fname); 128 129 int **ub_ctx_set_fwd**\ (struct ub_ctx\* ctx, char\* addr); 130 131 int **ub_ctx_set_stub**\ (struct ub_ctx\* ctx, char\* zone, char\* addr, 132 int isprime); 133 134 int **ub_ctx_set_tls**\ (struct ub_ctx\* ctx, int tls); 135 136 int **ub_ctx_resolvconf**\ (struct ub_ctx\* ctx, char\* fname); 137 138 int **ub_ctx_hosts**\ (struct ub_ctx\* ctx, char\* fname); 139 140 int **ub_ctx_add_ta**\ (struct ub_ctx\* ctx, char\* ta); 141 142 int **ub_ctx_add_ta_autr**\ (struct ub_ctx\* ctx, char\* fname); 143 144 int **ub_ctx_add_ta_file**\ (struct ub_ctx\* ctx, char\* fname); 145 146 int **ub_ctx_trustedkeys**\ (struct ub_ctx\* ctx, char\* fname); 147 148 int **ub_ctx_debugout**\ (struct ub_ctx\* ctx, FILE\* out); 149 150 int **ub_ctx_debuglevel**\ (struct ub_ctx\* ctx, int d); 151 152 int **ub_ctx_async**\ (struct ub_ctx\* ctx, int dothread); 153 154 int **ub_poll**\ (struct ub_ctx\* ctx); 155 156 int **ub_wait**\ (struct ub_ctx\* ctx); 157 158 int **ub_fd**\ (struct ub_ctx\* ctx); 159 160 int **ub_process**\ (struct ub_ctx\* ctx); 161 162 int **ub_resolve**\ (struct ub_ctx\* ctx, char\* name, 163 int rrtype, int rrclass, struct ub_result\*\* result); 164 165 int **ub_resolve_async**\ (struct ub_ctx\* ctx, char\* name, 166 int rrtype, int rrclass, void\* mydata, 167 ub_callback_type\* callback, int\* async_id); 168 169 int **ub_cancel**\ (struct ub_ctx\* ctx, int async_id); 170 171 void **ub_resolve_free**\ (struct ub_result\* result); 172 173 const char \* **ub_strerror**\ (int err); 174 175 int **ub_ctx_print_local_zones**\ (struct ub_ctx\* ctx); 176 177 int **ub_ctx_zone_add**\ (struct ub_ctx\* ctx, char\* zone_name, char\* zone_type); 178 179 int **ub_ctx_zone_remove**\ (struct ub_ctx\* ctx, char\* zone_name); 180 181 int **ub_ctx_data_add**\ (struct ub_ctx\* ctx, char\* data); 182 183 int **ub_ctx_data_remove**\ (struct ub_ctx\* ctx, char\* data); 184 185Description 186----------- 187 188Unbound is an implementation of a DNS resolver, that does caching and DNSSEC 189validation. 190This is the library API, for using the ``-lunbound`` library. 191The server daemon is described in :doc:`unbound(8)</manpages/unbound>`. 192The library works independent from a running unbound server, and can be used to 193convert hostnames to ip addresses, and back, and obtain other information from 194the DNS. 195The library performs public-key validation of results with DNSSEC. 196 197The library uses a variable of type *struct ub_ctx* to keep context between 198calls. 199The user must maintain it, creating it with **ub_ctx_create** and deleting it 200with **ub_ctx_delete**. 201It can be created and deleted at any time. 202Creating it anew removes any previous configuration (such as trusted keys) and 203clears any cached results. 204 205The functions are thread-safe, and a context can be used in a threaded (as well 206as in a non-threaded) environment. 207Also resolution (and validation) can be performed blocking and non-blocking 208(also called asynchronous). 209The async method returns from the call immediately, so that processing can go 210on, while the results become available later. 211 212The functions are discussed in turn below. 213 214Functions 215--------- 216 217.. glossary:: 218 219 ub_ctx_create 220 Create a new context, initialised with defaults. 221 The information from :file:`/etc/resolv.conf` and :file:`/etc/hosts` is 222 not utilised by default. 223 Use **ub_ctx_resolvconf** and **ub_ctx_hosts** to read them. 224 Before you call this, use the openssl functions 225 **CRYPTO_set_id_callback** and **CRYPTO_set_locking_callback** to set 226 up asynchronous operation if you use lib openssl (the application calls 227 these functions once for initialisation). 228 Openssl 1.0.0 or later uses the **CRYPTO_THREADID_set_callback** 229 function. 230 231 ub_ctx_delete 232 Delete validation context and free associated resources. 233 Outstanding async queries are killed and callbacks are not called for 234 them. 235 236 ub_ctx_set_option 237 A power-user interface that lets you specify one of the options from 238 the config file format, see :doc:`unbound.conf(5)</manpages/unbound.conf>`. 239 Not all options are relevant. 240 For some specific options, such as adding trust anchors, special 241 routines exist. 242 Pass the option name with the trailing ``':'``. 243 244 ub_ctx_get_option 245 A power-user interface that gets an option value. 246 Some options cannot be gotten, and others return a newline separated 247 list. 248 Pass the option name without trailing ``':'``. 249 The returned value must be free(2)d by the caller. 250 251 ub_ctx_config 252 A power-user interface that lets you specify an unbound config file, 253 see :doc:`unbound.conf(5)</manpages/unbound.conf>`, which is read for 254 configuration. 255 Not all options are relevant. 256 For some specific options, such as adding trust anchors, special 257 routines exist. 258 This function is thread-safe only if a single instance of **ub_ctx**\* 259 exists in the application. 260 If several instances exist the application has to ensure that 261 **ub_ctx_config** is not called in parallel by the different instances. 262 263 ub_ctx_set_fwd 264 Set machine to forward DNS queries to, the caching resolver to use. 265 IP4 or IP6 address. 266 Forwards all DNS requests to that machine, which is expected to run a 267 recursive resolver. 268 If the proxy is not DNSSEC capable, validation may fail. 269 Can be called several times, in that case the addresses are used as 270 backup servers. 271 At this time it is only possible to set configuration before the first 272 resolve is done. 273 274 ub_ctx_set_stub 275 Set a stub zone, authoritative dns servers to use for a particular 276 zone. 277 IP4 or IP6 address. 278 If the address is NULL the stub entry is removed. 279 Set isprime true if you configure root hints with it. 280 Otherwise similar to the stub zone item from unbound's config file. 281 Can be called several times, for different zones, or to add multiple 282 addresses for a particular zone. 283 At this time it is only possible to set configuration before the first 284 resolve is done. 285 286 ub_ctx_set_tls 287 Enable DNS over TLS (DoT) for machines set with **ub_ctx_set_fwd**. 288 At this time it is only possible to set configuration before the first 289 resolve is done. 290 291 ub_ctx_resolvconf 292 By default the root servers are queried and full resolver mode is used, 293 but you can use this call to read the list of nameservers to use from 294 the filename given. 295 Usually :file:`"/etc/resolv.conf"`. 296 Uses those nameservers as caching proxies. 297 If they do not support DNSSEC, validation may fail. 298 Only nameservers are picked up, the searchdomain, ndots and other 299 settings from *resolv.conf(5)* are ignored. 300 If fname NULL is passed, :file:`"/etc/resolv.conf"` is used (if on 301 Windows, the system-wide configured nameserver is picked instead). 302 At this time it is only possible to set configuration before the first 303 resolve is done. 304 305 ub_ctx_hosts 306 Read list of hosts from the filename given. 307 Usually :file:`"/etc/hosts"`. 308 When queried for, these addresses are not marked DNSSEC secure. 309 If fname NULL is passed, :file:`"/etc/hosts"` is used (if on Windows, 310 :file:`etc/hosts` from WINDIR is picked instead). 311 At this time it is only possible to set configuration before the first 312 resolve is done. 313 314 ub_ctx_add_ta 315 Add a trust anchor to the given context. 316 At this time it is only possible to add trusted keys before the first 317 resolve is done. 318 The format is a string, similar to the zone-file format, 319 **[domainname]** **[type]** **[rdata contents]**. 320 Both DS and DNSKEY records are accepted. 321 322 ub_ctx_add_ta_autr 323 Add filename with automatically tracked trust anchor to the given 324 context. 325 Pass name of a file with the managed trust anchor. 326 You can create this file with 327 :doc:`unbound-anchor(8)</manpages/unbound-anchor>` for the root anchor. 328 You can also create it with an initial file with one line with a DNSKEY 329 or DS record. 330 If the file is writable, it is updated when the trust anchor changes. 331 At this time it is only possible to add trusted keys before the first 332 resolve is done. 333 334 ub_ctx_add_ta_file 335 Add trust anchors to the given context. 336 Pass name of a file with DS and DNSKEY records in zone file format. 337 At this time it is only possible to add trusted keys before the first 338 resolve is done. 339 340 ub_ctx_trustedkeys 341 Add trust anchors to the given context. 342 Pass the name of a bind-style config file with ``trusted-keys{}``. 343 At this time it is only possible to add trusted keys before the first 344 resolve is done. 345 346 ub_ctx_debugout 347 Set debug and error log output to the given stream. 348 Pass NULL to disable output. 349 Default is stderr. 350 File-names or using syslog can be enabled using config options, this 351 routine is for using your own stream. 352 353 ub_ctx_debuglevel 354 Set debug verbosity for the context. 355 Output is directed to stderr. 356 Higher debug level gives more output. 357 358 ub_ctx_async 359 Set a context behaviour for asynchronous action. 360 if set to true, enables threading and a call to **ub_resolve_async** 361 creates a thread to handle work in the background. 362 If false, a process is forked to handle work in the background. 363 Changes to this setting after **ub_resolve_async** calls have been made 364 have no effect (delete and re-create the context to change). 365 366 ub_poll 367 Poll a context to see if it has any new results. 368 Do not poll in a loop, instead extract the **fd** below to poll for 369 readiness, and then check, or wait using the wait routine. 370 Returns 0 if nothing to read, or nonzero if a result is available. 371 If nonzero, call **ub_process** to do callbacks. 372 373 ub_wait 374 Wait for a context to finish with results. 375 Calls **ub_process** after the wait for you. 376 After the wait, there are no more outstanding asynchronous queries. 377 378 ub_fd 379 Get file descriptor. 380 Wait for it to become readable, at this point answers are returned from 381 the asynchronous validating resolver. 382 Then call the **ub_process** to continue processing. 383 384 ub_process 385 Call this routine to continue processing results from the validating 386 resolver (when the **fd** becomes readable). 387 Will perform necessary callbacks. 388 389 ub_resolve 390 Perform resolution and validation of the target name. 391 The name is a domain name in a zero terminated text string. 392 The rrtype and rrclass are DNS type and class codes. 393 The result structure is newly allocated with the resulting data. 394 395 ub_resolve_async 396 Perform asynchronous resolution and validation of the target name. 397 Arguments mean the same as for **ub_resolve** except no data is 398 returned immediately, instead a callback is called later. 399 The callback receives a copy of the mydata pointer, that you can use to 400 pass information to the callback. 401 The callback type is a function pointer to a function declared as: 402 403 .. code-block:: c 404 405 void my_callback_function(void* my_arg, int err, 406 struct ub_result* result); 407 408 The **async_id** is returned so you can (at your option) decide to 409 track it and cancel the request if needed. 410 If you pass a NULL pointer the **async_id** is not returned. 411 412 ub_cancel 413 Cancel an async query in progress. 414 This may return an error if the query does not exist, or the query is 415 already being delivered, in that case you may still get a callback for 416 the query. 417 418 ub_resolve_free 419 Free struct **ub_result** contents after use. 420 421 ub_strerror 422 Convert error value from one of the unbound library functions to a 423 human readable string. 424 425 ub_ctx_print_local_zones 426 Debug printout the local authority information to debug output. 427 428 ub_ctx_zone_add 429 Add new zone to local authority info, like local-zone 430 :doc:`unbound.conf(5)</manpages/unbound.conf>` statement. 431 432 ub_ctx_zone_remove 433 Delete zone from local authority info. 434 435 ub_ctx_data_add 436 Add resource record data to local authority info, like local-data 437 :doc:`unbound.conf(5)</manpages/unbound.conf>` statement. 438 439 ub_ctx_data_remove 440 Delete local authority data from the name given. 441 442Result Data structure 443--------------------- 444 445The result of the DNS resolution and validation is returned as *struct 446ub_result*. 447The result structure contains the following entries: 448 449.. code-block:: c 450 451 struct ub_result { 452 char* qname; /* text string, original question */ 453 int qtype; /* type code asked for */ 454 int qclass; /* class code asked for */ 455 char** data; /* array of rdata items, NULL terminated*/ 456 int* len; /* array with lengths of rdata items */ 457 char* canonname; /* canonical name of result */ 458 int rcode; /* additional error code in case of no data */ 459 void* answer_packet; /* full network format answer packet */ 460 int answer_len; /* length of packet in octets */ 461 int havedata; /* true if there is data */ 462 int nxdomain; /* true if nodata because name does not exist */ 463 int secure; /* true if result is secure */ 464 int bogus; /* true if a security failure happened */ 465 char* why_bogus; /* string with error if bogus */ 466 int was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */ 467 int ttl; /* number of seconds the result is valid */ 468 }; 469 470If both secure and bogus are false, security was not enabled for the domain of 471the query. 472Else, they are not both true, one of them is true. 473 474Return Values 475------------- 476 477Many routines return an error code. 478The value 0 (zero) denotes no error happened. 479Other values can be passed to **ub_strerror** to obtain a readable error 480string. 481**ub_strerror** returns a zero terminated string. 482**ub_ctx_create** returns NULL on an error (a malloc failure). 483**ub_poll** returns true if some information may be available, false otherwise. 484**ub_fd** returns a file descriptor or -1 on error. 485**ub_ctx_config** and **ub_ctx_resolvconf** attempt to leave errno informative 486on a function return with file read failure. 487 488See Also 489-------- 490 491:doc:`unbound.conf(5)</manpages/unbound.conf>`, :doc:`unbound(8)</manpages/unbound>`. 492