1 /* 2 * unbound.h - unbound validating resolver public API 3 * 4 * Copyright (c) 2007, NLnet Labs. All rights reserved. 5 * 6 * This software is open source. 7 * 8 * Redistribution and use in source and binary forms, with or without 9 * modification, are permitted provided that the following conditions 10 * are met: 11 * 12 * Redistributions of source code must retain the above copyright notice, 13 * this list of conditions and the following disclaimer. 14 * 15 * Redistributions in binary form must reproduce the above copyright notice, 16 * this list of conditions and the following disclaimer in the documentation 17 * and/or other materials provided with the distribution. 18 * 19 * Neither the name of the NLNET LABS nor the names of its contributors may 20 * be used to endorse or promote products derived from this software without 21 * specific prior written permission. 22 * 23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 25 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 26 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 27 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 28 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 29 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 30 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 31 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 32 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34 */ 35 36 /** 37 * \file 38 * 39 * This file contains functions to resolve DNS queries and 40 * validate the answers. Synchronously and asynchronously. 41 * 42 * Several ways to use this interface from an application wishing 43 * to perform (validated) DNS lookups. 44 * 45 * All start with 46 * ctx = ub_ctx_create(); 47 * err = ub_ctx_add_ta(ctx, "..."); 48 * err = ub_ctx_add_ta(ctx, "..."); 49 * ... some lookups 50 * ... call ub_ctx_delete(ctx); when you want to stop. 51 * 52 * Application not threaded. Blocking. 53 * int err = ub_resolve(ctx, "www.example.com", ... 54 * if(err) fprintf(stderr, "lookup error: %s\n", ub_strerror(err)); 55 * ... use the answer 56 * 57 * Application not threaded. Non-blocking ('asynchronous'). 58 * err = ub_resolve_async(ctx, "www.example.com", ... my_callback); 59 * ... application resumes processing ... 60 * ... and when either ub_poll(ctx) is true 61 * ... or when the file descriptor ub_fd(ctx) is readable, 62 * ... or whenever, the app calls ... 63 * ub_process(ctx); 64 * ... if no result is ready, the app resumes processing above, 65 * ... or process() calls my_callback() with results. 66 * 67 * ... if the application has nothing more to do, wait for answer 68 * ub_wait(ctx); 69 * 70 * Application threaded. Blocking. 71 * Blocking, same as above. The current thread does the work. 72 * Multiple threads can use the *same context*, each does work and uses 73 * shared cache data from the context. 74 * 75 * Application threaded. Non-blocking ('asynchronous'). 76 * ... setup threaded-asynchronous config option 77 * err = ub_ctx_async(ctx, 1); 78 * ... same as async for non-threaded 79 * ... the callbacks are called in the thread that calls process(ctx) 80 * 81 * Openssl needs to have locking in place, and the application must set 82 * it up, because a mere library cannot do this, use the calls 83 * CRYPTO_set_id_callback and CRYPTO_set_locking_callback. 84 * 85 * If no threading is compiled in, the above async example uses fork(2) to 86 * create a process to perform the work. The forked process exits when the 87 * calling process exits, or ctx_delete() is called. 88 * Otherwise, for asynchronous with threading, a worker thread is created. 89 * 90 * The blocking calls use shared ctx-cache when threaded. Thus 91 * ub_resolve() and ub_resolve_async() && ub_wait() are 92 * not the same. The first makes the current thread do the work, setting 93 * up buffers, etc, to perform the work (but using shared cache data). 94 * The second calls another worker thread (or process) to perform the work. 95 * And no buffers need to be set up, but a context-switch happens. 96 */ 97 #ifndef _UB_UNBOUND_H 98 #define _UB_UNBOUND_H 99 100 #ifdef __cplusplus 101 extern "C" { 102 #endif 103 104 /** the version of this header file */ 105 #define UNBOUND_VERSION_MAJOR @UNBOUND_VERSION_MAJOR@ 106 #define UNBOUND_VERSION_MINOR @UNBOUND_VERSION_MINOR@ 107 #define UNBOUND_VERSION_MICRO @UNBOUND_VERSION_MICRO@ 108 109 /** 110 * The validation context is created to hold the resolver status, 111 * validation keys and a small cache (containing messages, rrsets, 112 * roundtrip times, trusted keys, lameness information). 113 * 114 * Its contents are internally defined. 115 */ 116 struct ub_ctx; 117 118 /** 119 * The validation and resolution results. 120 * Allocated by the resolver, and need to be freed by the application 121 * with ub_resolve_free(). 122 */ 123 struct ub_result { 124 /** The original question, name text string. */ 125 char* qname; 126 /** the type asked for */ 127 int qtype; 128 /** the class asked for */ 129 int qclass; 130 131 /** 132 * a list of network order DNS rdata items, terminated with a 133 * NULL pointer, so that data[0] is the first result entry, 134 * data[1] the second, and the last entry is NULL. 135 * If there was no data, data[0] is NULL. 136 */ 137 char** data; 138 139 /** the length in bytes of the data items, len[i] for data[i] */ 140 int* len; 141 142 /** 143 * canonical name for the result (the final cname). 144 * zero terminated string. 145 * May be NULL if no canonical name exists. 146 */ 147 char* canonname; 148 149 /** 150 * DNS RCODE for the result. May contain additional error code if 151 * there was no data due to an error. 0 (NOERROR) if okay. 152 */ 153 int rcode; 154 155 /** 156 * The DNS answer packet. Network formatted. Can contain DNSSEC types. 157 */ 158 void* answer_packet; 159 /** length of the answer packet in octets. */ 160 int answer_len; 161 162 /** 163 * If there is any data, this is true. 164 * If false, there was no data (nxdomain may be true, rcode can be set). 165 */ 166 int havedata; 167 168 /** 169 * If there was no data, and the domain did not exist, this is true. 170 * If it is false, and there was no data, then the domain name 171 * is purported to exist, but the requested data type is not available. 172 */ 173 int nxdomain; 174 175 /** 176 * True, if the result is validated securely. 177 * False, if validation failed or domain queried has no security info. 178 * 179 * It is possible to get a result with no data (havedata is false), 180 * and secure is true. This means that the non-existence of the data 181 * was cryptographically proven (with signatures). 182 */ 183 int secure; 184 185 /** 186 * If the result was not secure (secure==0), and this result is due 187 * to a security failure, bogus is true. 188 * This means the data has been actively tampered with, signatures 189 * failed, expected signatures were not present, timestamps on 190 * signatures were out of date and so on. 191 * 192 * If !secure and !bogus, this can happen if the data is not secure 193 * because security is disabled for that domain name. 194 * This means the data is from a domain where data is not signed. 195 */ 196 int bogus; 197 198 /** 199 * If the result is bogus this contains a string (zero terminated) 200 * that describes the failure. There may be other errors as well 201 * as the one described, the description may not be perfectly accurate. 202 * Is NULL if the result is not bogus. 203 */ 204 char* why_bogus; 205 206 /** 207 * If the query or one of its subqueries was ratelimited. Useful if 208 * ratelimiting is enabled and answer to the client is SERVFAIL as a 209 * result. 210 */ 211 int was_ratelimited; 212 213 /** 214 * TTL for the result, in seconds. If the security is bogus, then 215 * you also cannot trust this value. 216 */ 217 int ttl; 218 }; 219 220 /** 221 * Callback for results of async queries. 222 * The readable function definition looks like: 223 * void my_callback(void* my_arg, int err, struct ub_result* result); 224 * It is called with 225 * void* my_arg: your pointer to a (struct of) data of your choice, 226 * or NULL. 227 * int err: if 0 all is OK, otherwise an error occurred and no results 228 * are forthcoming. 229 * struct result: pointer to more detailed result structure. 230 * This structure is allocated on the heap and needs to be 231 * freed with ub_resolve_free(result); 232 */ 233 typedef void (*ub_callback_type)(void*, int, struct ub_result*); 234 235 /** 236 * The error constants 237 */ 238 enum ub_ctx_err { 239 /** no error */ 240 UB_NOERROR = 0, 241 /** socket operation. Set to -1, so that if an error from _fd() is 242 * passed (-1) it gives a socket error. */ 243 UB_SOCKET = -1, 244 /** alloc failure */ 245 UB_NOMEM = -2, 246 /** syntax error */ 247 UB_SYNTAX = -3, 248 /** DNS service failed */ 249 UB_SERVFAIL = -4, 250 /** fork() failed */ 251 UB_FORKFAIL = -5, 252 /** cfg change after finalize() */ 253 UB_AFTERFINAL = -6, 254 /** initialization failed (bad settings) */ 255 UB_INITFAIL = -7, 256 /** error in pipe communication with async bg worker */ 257 UB_PIPE = -8, 258 /** error reading from file (resolv.conf) */ 259 UB_READFILE = -9, 260 /** error async_id does not exist or result already been delivered */ 261 UB_NOID = -10 262 }; 263 264 /** 265 * Create a resolving and validation context. 266 * The information from /etc/resolv.conf and /etc/hosts is not utilised by 267 * default. Use ub_ctx_resolvconf and ub_ctx_hosts to read them. 268 * @return a new context. default initialisation. 269 * returns NULL on error. 270 */ 271 struct ub_ctx* ub_ctx_create(void); 272 273 /** 274 * Destroy a validation context and free all its resources. 275 * Outstanding async queries are killed and callbacks are not called for them. 276 * @param ctx: context to delete. 277 */ 278 void ub_ctx_delete(struct ub_ctx* ctx); 279 280 /** 281 * Set an option for the context. 282 * @param ctx: context. 283 * @param opt: option name from the unbound.conf config file format. 284 * (not all settings applicable). The name includes the trailing ':' 285 * for example ub_ctx_set_option(ctx, "logfile:", "mylog.txt"); 286 * This is a power-users interface that lets you specify all sorts 287 * of options. 288 * For some specific options, such as adding trust anchors, special 289 * routines exist. 290 * @param val: value of the option. 291 * @return: 0 if OK, else error. 292 */ 293 int ub_ctx_set_option(struct ub_ctx* ctx, const char* opt, const char* val); 294 295 /** 296 * Get an option from the context. 297 * @param ctx: context. 298 * @param opt: option name from the unbound.conf config file format. 299 * (not all settings applicable). The name excludes the trailing ':' 300 * for example ub_ctx_get_option(ctx, "logfile", &result); 301 * This is a power-users interface that lets you specify all sorts 302 * of options. 303 * @param str: the string is malloced and returned here. NULL on error. 304 * The caller must free() the string. In cases with multiple 305 * entries (auto-trust-anchor-file), a newline delimited list is 306 * returned in the string. 307 * @return 0 if OK else an error code (malloc failure, syntax error). 308 */ 309 int ub_ctx_get_option(struct ub_ctx* ctx, const char* opt, char** str); 310 311 /** 312 * setup configuration for the given context. 313 * @param ctx: context. 314 * @param fname: unbound config file (not all settings applicable). 315 * This is a power-users interface that lets you specify all sorts 316 * of options. 317 * For some specific options, such as adding trust anchors, special 318 * routines exist. 319 * @return: 0 if OK, else error. 320 */ 321 int ub_ctx_config(struct ub_ctx* ctx, const char* fname); 322 323 /** 324 * Set machine to forward DNS queries to, the caching resolver to use. 325 * IP4 or IP6 address. Forwards all DNS requests to that machine, which 326 * is expected to run a recursive resolver. If the proxy is not 327 * DNSSEC-capable, validation may fail. Can be called several times, in 328 * that case the addresses are used as backup servers. 329 * 330 * To read the list of nameservers from /etc/resolv.conf (from DHCP or so), 331 * use the call ub_ctx_resolvconf. 332 * 333 * @param ctx: context. 334 * At this time it is only possible to set configuration before the 335 * first resolve is done. 336 * @param addr: address, IP4 or IP6 in string format. 337 * If the addr is NULL, forwarding is disabled. 338 * @return 0 if OK, else error. 339 */ 340 int ub_ctx_set_fwd(struct ub_ctx* ctx, const char* addr); 341 342 /** 343 * Use DNS over TLS to send queries to machines set with ub_ctx_set_fwd(). 344 * 345 * @param ctx: context. 346 * At this time it is only possible to set configuration before the 347 * first resolve is done. 348 * @param tls: enable or disable DNS over TLS 349 * @return 0 if OK, else error. 350 */ 351 int ub_ctx_set_tls(struct ub_ctx* ctx, int tls); 352 353 /** 354 * Add a stub zone, with given address to send to. This is for custom 355 * root hints or pointing to a local authoritative dns server. 356 * For dns resolvers and the 'DHCP DNS' ip address, use ub_ctx_set_fwd. 357 * This is similar to a stub-zone entry in unbound.conf. 358 * 359 * @param ctx: context. 360 * It is only possible to set configuration before the 361 * first resolve is done. 362 * @param zone: name of the zone, string. 363 * @param addr: address, IP4 or IP6 in string format. 364 * The addr is added to the list of stub-addresses if the entry exists. 365 * If the addr is NULL the stub entry is removed. 366 * @param isprime: set to true to set stub-prime to yes for the stub. 367 * For local authoritative servers, people usually set it to false, 368 * For root hints it should be set to true. 369 * @return 0 if OK, else error. 370 */ 371 int ub_ctx_set_stub(struct ub_ctx* ctx, const char* zone, const char* addr, 372 int isprime); 373 374 /** 375 * Read list of nameservers to use from the filename given. 376 * Usually "/etc/resolv.conf". Uses those nameservers as caching proxies. 377 * If they do not support DNSSEC, validation may fail. 378 * 379 * Only nameservers are picked up, the searchdomain, ndots and other 380 * settings from resolv.conf(5) are ignored. 381 * 382 * @param ctx: context. 383 * At this time it is only possible to set configuration before the 384 * first resolve is done. 385 * @param fname: file name string. If NULL "/etc/resolv.conf" is used. 386 * @return 0 if OK, else error. 387 */ 388 int ub_ctx_resolvconf(struct ub_ctx* ctx, const char* fname); 389 390 /** 391 * Read list of hosts from the filename given. 392 * Usually "/etc/hosts". 393 * These addresses are not flagged as DNSSEC secure when queried for. 394 * 395 * @param ctx: context. 396 * At this time it is only possible to set configuration before the 397 * first resolve is done. 398 * @param fname: file name string. If NULL "/etc/hosts" is used. 399 * @return 0 if OK, else error. 400 */ 401 int ub_ctx_hosts(struct ub_ctx* ctx, const char* fname); 402 403 /** 404 * Add a trust anchor to the given context. 405 * The trust anchor is a string, on one line, that holds a valid DNSKEY or 406 * DS RR. 407 * @param ctx: context. 408 * At this time it is only possible to add trusted keys before the 409 * first resolve is done. 410 * @param ta: string, with zone-format RR on one line. 411 * [domainname] [TTL optional] [type] [class optional] [rdata contents] 412 * @return 0 if OK, else error. 413 */ 414 int ub_ctx_add_ta(struct ub_ctx* ctx, const char* ta); 415 416 /** 417 * Add trust anchors to the given context. 418 * Pass name of a file with DS and DNSKEY records (like from dig or drill). 419 * @param ctx: context. 420 * At this time it is only possible to add trusted keys before the 421 * first resolve is done. 422 * @param fname: filename of file with keyfile with trust anchors. 423 * @return 0 if OK, else error. 424 */ 425 int ub_ctx_add_ta_file(struct ub_ctx* ctx, const char* fname); 426 427 /** 428 * Add trust anchor to the given context that is tracked with RFC5011 429 * automated trust anchor maintenance. The file is written to when the 430 * trust anchor is changed. 431 * Pass the name of a file that was output from eg. unbound-anchor, 432 * or you can start it by providing a trusted DNSKEY or DS record on one 433 * line in the file. 434 * @param ctx: context. 435 * At this time it is only possible to add trusted keys before the 436 * first resolve is done. 437 * @param fname: filename of file with trust anchor. 438 * @return 0 if OK, else error. 439 */ 440 int ub_ctx_add_ta_autr(struct ub_ctx* ctx, const char* fname); 441 442 /** 443 * Add trust anchors to the given context. 444 * Pass the name of a bind-style config file with trusted-keys{}. 445 * @param ctx: context. 446 * At this time it is only possible to add trusted keys before the 447 * first resolve is done. 448 * @param fname: filename of file with bind-style config entries with trust 449 * anchors. 450 * @return 0 if OK, else error. 451 */ 452 int ub_ctx_trustedkeys(struct ub_ctx* ctx, const char* fname); 453 454 /** 455 * Set debug output (and error output) to the specified stream. 456 * Pass NULL to disable. Default is stderr. 457 * @param ctx: context. 458 * @param out: FILE* out file stream to log to. 459 * Type void* to avoid stdio dependency of this header file. 460 * @return 0 if OK, else error. 461 */ 462 int ub_ctx_debugout(struct ub_ctx* ctx, void* out); 463 464 /** 465 * Set debug verbosity for the context 466 * Output is directed to stderr. 467 * @param ctx: context. 468 * @param d: debug level, 0 is off, 1 is very minimal, 2 is detailed, 469 * and 3 is lots. 470 * @return 0 if OK, else error. 471 */ 472 int ub_ctx_debuglevel(struct ub_ctx* ctx, int d); 473 474 /** 475 * Set a context behaviour for asynchronous action. 476 * @param ctx: context. 477 * @param dothread: if true, enables threading and a call to resolve_async() 478 * creates a thread to handle work in the background. 479 * If false, a process is forked to handle work in the background. 480 * Changes to this setting after async() calls have been made have 481 * no effect (delete and re-create the context to change). 482 * @return 0 if OK, else error. 483 */ 484 int ub_ctx_async(struct ub_ctx* ctx, int dothread); 485 486 /** 487 * Poll a context to see if it has any new results 488 * Do not poll in a loop, instead extract the fd below to poll for readiness, 489 * and then check, or wait using the wait routine. 490 * @param ctx: context. 491 * @return: 0 if nothing to read, or nonzero if a result is available. 492 * If nonzero, call ctx_process() to do callbacks. 493 */ 494 int ub_poll(struct ub_ctx* ctx); 495 496 /** 497 * Wait for a context to finish with results. Calls ub_process() after 498 * the wait for you. After the wait, there are no more outstanding 499 * asynchronous queries. 500 * @param ctx: context. 501 * @return: 0 if OK, else error. 502 */ 503 int ub_wait(struct ub_ctx* ctx); 504 505 /** 506 * Get file descriptor. Wait for it to become readable, at this point 507 * answers are returned from the asynchronous validating resolver. 508 * Then call the ub_process to continue processing. 509 * This routine works immediately after context creation, the fd 510 * does not change. 511 * @param ctx: context. 512 * @return: -1 on error, or file descriptor to use select(2) with. 513 */ 514 int ub_fd(struct ub_ctx* ctx); 515 516 /** 517 * Call this routine to continue processing results from the validating 518 * resolver (when the fd becomes readable). 519 * Will perform necessary callbacks. 520 * @param ctx: context 521 * @return: 0 if OK, else error. 522 */ 523 int ub_process(struct ub_ctx* ctx); 524 525 /** 526 * Perform resolution and validation of the target name. 527 * @param ctx: context. 528 * The context is finalized, and can no longer accept config changes. 529 * @param name: domain name in text format (a zero terminated text string). 530 * @param rrtype: type of RR in host order, 1 is A (address). 531 * @param rrclass: class of RR in host order, 1 is IN (for internet). 532 * @param result: the result data is returned in a newly allocated result 533 * structure. May be NULL on return, return value is set to an error 534 * in that case (out of memory). 535 * @return 0 if OK, else error. 536 */ 537 int ub_resolve(struct ub_ctx* ctx, const char* name, int rrtype, 538 int rrclass, struct ub_result** result); 539 540 /** 541 * Perform resolution and validation of the target name. 542 * Asynchronous, after a while, the callback will be called with your 543 * data and the result. 544 * @param ctx: context. 545 * If no thread or process has been created yet to perform the 546 * work in the background, it is created now. 547 * The context is finalized, and can no longer accept config changes. 548 * @param name: domain name in text format (a string). 549 * @param rrtype: type of RR in host order, 1 is A. 550 * @param rrclass: class of RR in host order, 1 is IN (for internet). 551 * @param mydata: this data is your own data (you can pass NULL), 552 * and is passed on to the callback function. 553 * @param callback: this is called on completion of the resolution. 554 * It is called as: 555 * void callback(void* mydata, int err, struct ub_result* result) 556 * with mydata: the same as passed here, you may pass NULL, 557 * with err: is 0 when a result has been found. 558 * with result: a newly allocated result structure. 559 * The result may be NULL, in that case err is set. 560 * 561 * If an error happens during processing, your callback will be called 562 * with error set to a nonzero value (and result==NULL). 563 * @param async_id: if you pass a non-NULL value, an identifier number is 564 * returned for the query as it is in progress. It can be used to 565 * cancel the query. 566 * @return 0 if OK, else error. 567 */ 568 int ub_resolve_async(struct ub_ctx* ctx, const char* name, int rrtype, 569 int rrclass, void* mydata, ub_callback_type callback, int* async_id); 570 571 /** 572 * Cancel an async query in progress. 573 * Its callback will not be called. 574 * 575 * @param ctx: context. 576 * @param async_id: which query to cancel. 577 * @return 0 if OK, else error. 578 * This routine can return an error if the async_id passed does not exist 579 * or has already been delivered. If another thread is processing results 580 * at the same time, the result may be delivered at the same time and the 581 * cancel fails with an error. Also the cancel can fail due to a system 582 * error, no memory or socket failures. 583 */ 584 int ub_cancel(struct ub_ctx* ctx, int async_id); 585 586 /** 587 * Free storage associated with a result structure. 588 * @param result: to free 589 */ 590 void ub_resolve_free(struct ub_result* result); 591 592 /** 593 * Convert error value to a human readable string. 594 * @param err: error code from one of the libunbound functions. 595 * The error codes are from the type enum ub_ctx_err. 596 * @return pointer to constant text string, zero terminated. 597 */ 598 const char* ub_strerror(int err); 599 600 /** 601 * Debug routine. Print the local zone information to debug output. 602 * @param ctx: context. Is finalized by the routine. 603 * @return 0 if OK, else error. 604 */ 605 int ub_ctx_print_local_zones(struct ub_ctx* ctx); 606 607 /** 608 * Add a new zone with the zonetype to the local authority info of the 609 * library. 610 * @param ctx: context. Is finalized by the routine. 611 * @param zone_name: name of the zone in text, "example.com" 612 * If it already exists, the type is updated. 613 * @param zone_type: type of the zone (like for unbound.conf) in text. 614 * @return 0 if OK, else error. 615 */ 616 int ub_ctx_zone_add(struct ub_ctx* ctx, const char *zone_name, 617 const char *zone_type); 618 619 /** 620 * Remove zone from local authority info of the library. 621 * @param ctx: context. Is finalized by the routine. 622 * @param zone_name: name of the zone in text, "example.com" 623 * If it does not exist, nothing happens. 624 * @return 0 if OK, else error. 625 */ 626 int ub_ctx_zone_remove(struct ub_ctx* ctx, const char *zone_name); 627 628 /** 629 * Add localdata to the library local authority info. 630 * Similar to local-data config statement. 631 * @param ctx: context. Is finalized by the routine. 632 * @param data: the resource record in text format, for example 633 * "www.example.com IN A 127.0.0.1" 634 * @return 0 if OK, else error. 635 */ 636 int ub_ctx_data_add(struct ub_ctx* ctx, const char *data); 637 638 /** 639 * Remove localdata from the library local authority info. 640 * @param ctx: context. Is finalized by the routine. 641 * @param data: the name to delete all data from, like "www.example.com". 642 * @return 0 if OK, else error. 643 */ 644 int ub_ctx_data_remove(struct ub_ctx* ctx, const char *data); 645 646 /** 647 * Get a version string from the libunbound implementation. 648 * @return a static constant string with the version number. 649 */ 650 const char* ub_version(void); 651 652 /** 653 * Some global statistics that are not in struct stats_info, 654 * this struct is shared on a shm segment (shm-key in unbound.conf) 655 */ 656 struct ub_shm_stat_info { 657 int num_threads; 658 659 struct { 660 long long now_sec, now_usec; 661 long long up_sec, up_usec; 662 long long elapsed_sec, elapsed_usec; 663 } time; 664 665 struct { 666 long long msg; 667 long long rrset; 668 long long val; 669 long long iter; 670 long long subnet; 671 long long ipsecmod; 672 long long respip; 673 long long dnscrypt_shared_secret; 674 long long dnscrypt_nonce; 675 long long dynlib; 676 } mem; 677 }; 678 679 /** number of qtype that is stored for in array */ 680 #define UB_STATS_QTYPE_NUM 256 681 /** number of qclass that is stored for in array */ 682 #define UB_STATS_QCLASS_NUM 256 683 /** number of rcodes in stats */ 684 #define UB_STATS_RCODE_NUM 16 685 /** number of opcodes in stats */ 686 #define UB_STATS_OPCODE_NUM 16 687 /** number of histogram buckets */ 688 #define UB_STATS_BUCKET_NUM 40 689 /** number of RPZ actions */ 690 #define UB_STATS_RPZ_ACTION_NUM 10 691 692 /** per worker statistics. */ 693 struct ub_server_stats { 694 /** number of queries from clients received. */ 695 long long num_queries; 696 /** number of queries that have been dropped/ratelimited by ip. */ 697 long long num_queries_ip_ratelimited; 698 /** number of queries that had a cache-miss. */ 699 long long num_queries_missed_cache; 700 /** number of prefetch queries - cachehits with prefetch */ 701 long long num_queries_prefetch; 702 703 /** 704 * Sum of the querylistsize of the worker for 705 * every query that missed cache. To calculate average. 706 */ 707 long long sum_query_list_size; 708 /** max value of query list size reached. */ 709 long long max_query_list_size; 710 711 /** Extended stats below (bool) */ 712 int extended; 713 714 /** qtype stats */ 715 long long qtype[UB_STATS_QTYPE_NUM]; 716 /** bigger qtype values not in array */ 717 long long qtype_big; 718 /** qclass stats */ 719 long long qclass[UB_STATS_QCLASS_NUM]; 720 /** bigger qclass values not in array */ 721 long long qclass_big; 722 /** query opcodes */ 723 long long qopcode[UB_STATS_OPCODE_NUM]; 724 /** number of queries over TCP */ 725 long long qtcp; 726 /** number of outgoing queries over TCP */ 727 long long qtcp_outgoing; 728 /** number of outgoing queries over UDP */ 729 long long qudp_outgoing; 730 /** number of queries over (DNS over) TLS */ 731 long long qtls; 732 /** number of queries over (DNS over) HTTPS */ 733 long long qhttps; 734 /** number of queries over IPv6 */ 735 long long qipv6; 736 /** number of queries with QR bit */ 737 long long qbit_QR; 738 /** number of queries with AA bit */ 739 long long qbit_AA; 740 /** number of queries with TC bit */ 741 long long qbit_TC; 742 /** number of queries with RD bit */ 743 long long qbit_RD; 744 /** number of queries with RA bit */ 745 long long qbit_RA; 746 /** number of queries with Z bit */ 747 long long qbit_Z; 748 /** number of queries with AD bit */ 749 long long qbit_AD; 750 /** number of queries with CD bit */ 751 long long qbit_CD; 752 /** number of queries with EDNS OPT record */ 753 long long qEDNS; 754 /** number of queries with EDNS with DO flag */ 755 long long qEDNS_DO; 756 /** answer rcodes */ 757 long long ans_rcode[UB_STATS_RCODE_NUM]; 758 /** answers with pseudo rcode 'nodata' */ 759 long long ans_rcode_nodata; 760 /** answers that were secure (AD) */ 761 long long ans_secure; 762 /** answers that were bogus (withheld as SERVFAIL) */ 763 long long ans_bogus; 764 /** rrsets marked bogus by validator */ 765 long long rrset_bogus; 766 /** number of queries that have been ratelimited by domain recursion. */ 767 long long queries_ratelimited; 768 /** unwanted traffic received on server-facing ports */ 769 long long unwanted_replies; 770 /** unwanted traffic received on client-facing ports */ 771 long long unwanted_queries; 772 /** usage of tcp accept list */ 773 long long tcp_accept_usage; 774 /** expired answers served from cache */ 775 long long ans_expired; 776 /** histogram data exported to array 777 * if the array is the same size, no data is lost, and 778 * if all histograms are same size (is so by default) then 779 * adding up works well. */ 780 long long hist[UB_STATS_BUCKET_NUM]; 781 782 /** number of message cache entries */ 783 long long msg_cache_count; 784 /** number of rrset cache entries */ 785 long long rrset_cache_count; 786 /** number of infra cache entries */ 787 long long infra_cache_count; 788 /** number of key cache entries */ 789 long long key_cache_count; 790 791 /** number of queries that used dnscrypt */ 792 long long num_query_dnscrypt_crypted; 793 /** number of queries that queried dnscrypt certificates */ 794 long long num_query_dnscrypt_cert; 795 /** number of queries in clear text and not asking for the certificates */ 796 long long num_query_dnscrypt_cleartext; 797 /** number of malformed encrypted queries */ 798 long long num_query_dnscrypt_crypted_malformed; 799 /** number of queries which did not have a shared secret in cache */ 800 long long num_query_dnscrypt_secret_missed_cache; 801 /** number of dnscrypt shared secret cache entries */ 802 long long shared_secret_cache_count; 803 /** number of queries which are replays */ 804 long long num_query_dnscrypt_replay; 805 /** number of dnscrypt nonces cache entries */ 806 long long nonce_cache_count; 807 /** number of queries for unbound's auth_zones, upstream query */ 808 long long num_query_authzone_up; 809 /** number of queries for unbound's auth_zones, downstream answers */ 810 long long num_query_authzone_down; 811 /** number of times neg cache records were used to generate NOERROR 812 * responses. */ 813 long long num_neg_cache_noerror; 814 /** number of times neg cache records were used to generate NXDOMAIN 815 * responses. */ 816 long long num_neg_cache_nxdomain; 817 /** number of queries answered from edns-subnet specific data */ 818 long long num_query_subnet; 819 /** number of queries answered from edns-subnet specific data, and 820 * the answer was from the edns-subnet cache. */ 821 long long num_query_subnet_cache; 822 /** number of bytes in the stream wait buffers */ 823 long long mem_stream_wait; 824 /** number of bytes in the HTTP2 query buffers */ 825 long long mem_http2_query_buffer; 826 /** number of bytes in the HTTP2 response buffers */ 827 long long mem_http2_response_buffer; 828 /** number of TLS connection resume */ 829 long long qtls_resume; 830 /** RPZ action stats */ 831 long long rpz_action[UB_STATS_RPZ_ACTION_NUM]; 832 }; 833 834 /** 835 * Statistics to send over the control pipe when asked 836 * This struct is made to be memcopied, sent in binary. 837 * shm mapped with (number+1) at num_threads+1, with first as total 838 */ 839 struct ub_stats_info { 840 /** the thread stats */ 841 struct ub_server_stats svr; 842 843 /** mesh stats: current number of states */ 844 long long mesh_num_states; 845 /** mesh stats: current number of reply (user) states */ 846 long long mesh_num_reply_states; 847 /** mesh stats: number of reply states overwritten with a new one */ 848 long long mesh_jostled; 849 /** mesh stats: number of incoming queries dropped */ 850 long long mesh_dropped; 851 /** mesh stats: replies sent */ 852 long long mesh_replies_sent; 853 /** mesh stats: sum of waiting times for the replies */ 854 long long mesh_replies_sum_wait_sec, mesh_replies_sum_wait_usec; 855 /** mesh stats: median of waiting times for replies (in sec) */ 856 double mesh_time_median; 857 }; 858 859 #ifdef __cplusplus 860 } 861 #endif 862 863 #endif /* _UB_UNBOUND_H */ 864