# Technical Documentation: NLnetLabs/unbound > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/NLnetLabs/unbound) ### Overview (`README.md`) # Unbound [](https://github.com/NLnetLabs/unbound/actions) [](https://repology.org/project/unbound/versions) [](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:unbound) [](https://unbound.readthedocs.io/en/latest/?badge=latest) [](https://social.nlnetlabs.nl/@nlnetlabs) Unbound is a validating, recursive, caching DNS resolver. It is designed to be fast and lean and incorporates modern features based on open standards. If you have any feedback, we would love to hear from you. Don’t hesitate to [create an issue on Github](https://github.com/NLnetLabs/unbound/issues/new) or post a message on our [community forum](https://community.nlnetlabs.nl/). You can learn more about Unbound by reading our [documentation](https://unbound.docs.nlnetlabs.nl/). ## Compiling Make sure you have the C toolchain, OpenSSL and its include files, and libexpat installed. If building from the repository source you also need flex and bison installed. Unbound can be compiled and installed using: ``` ./configure && make && make install ``` You can use libevent if you want. libevent is useful when using many (e.g., 10000) outgoing ports. Use the `--with-libevent` configure option to compile Unbound with libevent support. If not, the default builtin alternative opens max 256 ports at the same time and is equally capable and a little faster. ## Unbound configuration All of Unbound's configuration options are described in the `unbound.conf(5)` man page, which will be installed and is also available on the Unbound [documentation page](https://unbound.docs.nlnetlabs.nl/en/latest/manpages/unbound.conf.html) for the latest version. An example configuration file, with minimal documentation, is located in [doc/example.conf](https://github.com/NLnetLabs/unbound/blob/master/doc/example.conf.in). --- ### Doc README.Ipset (`doc/README.ipset.md`) ## Created a module to support the ipset that could add the domain's ip to a list easily. ### Purposes: * In my case, I can't access the facebook, twitter, youtube and thousands web site for some reason. VPN is a solution. But the internet too slow whether all traffics pass through the vpn. So, I set up a transparent proxy to proxy the traffic which has been blocked only. At the final step, I need to install a dns service which would work with ipset well to launch the system. I did some research for this. Unfortunately, Unbound, My favorite dns service doesn't support ipset yet. So, I decided to implement it by my self and contribute the patch. It's good for me and the community. ``` # unbound.conf server: ... local-zone: "facebook.com" ipset local-zone: "twitter.com" ipset local-zone: "instagram.com" ipset more social website ipset: name-v4: "gfwlist" ``` ``` # iptables iptables -A PREROUTING -p tcp -m set --match-set gfwlist dst -j REDIRECT --to-ports 10800 iptables -A OUTPUT -p tcp -m set --match-set gfwlist dst -j REDIRECT --to-ports 10800 ``` * This patch could work with iptables rules to batch block the IPs. ``` # unbound.conf server: ... local-zone: "facebook.com" ipset local-zone: "twitter.com" ipset local-zone: "instagram.com" ipset more social website ipset: name-v4: "blacklist" name-v6: "blacklist6" ``` ``` # iptables iptables -A INPUT -m set --set blacklist src -j DROP ip6tables -A INPUT -m set --set blacklist6 src -j DROP ``` ### Notes: * To enable this module the root privileges is required. * Please create a set with ipset command first. eg. **ipset -N blacklist iphash** ### How to use: ``` ./configure --enable-ipset make && make install ``` ### Configuration: ``` # unbound.conf server: ... local-zone: "example.com" ipset ipset: name-v4: "blacklist" ``` --- ### Doc Control Proto Spec (`doc/control_proto_spec.txt`) Specification for the unbound-control protocol. Server listens on 8953 TCP (localhost by default). Client connects, SSLv3 or TLSv1 connection setup (server selfsigned certificate, client has cert signed by server certificate). Port 8953 is registered with IANA as: ub-dns-control 8953/tcp unbound dns nameserver control # Wouter Wijngaards 10 May 2011 On may 11 2011, ticket [IANA #442315]. Query and Response ------------------ Client sends UBCT[version] [commandline] \n fixed string UBCT1 (for version 1), then an ascii text line, with a command, some whitespace allowed. Line ends with '\n'. Server executes command. And sends reply in ascii text over channel, closes the channel when done. in case of error the first line of the response is: error \n or the remainder is data of the response, for many commands the response is 'ok\n'. Queries and responses --------------------- stop stops the server. reload reloads the config file, and flushes the cache. verbosity Change logging verbosity to new value. stats output is a list of [name]=[value] lines. clears the counters. dump_cache output is a text representation of the cache contents. data ends with a line 'EOF' before connection close. load_cache client sends cache contents (like from dump_cache), which is stored in the cache. end of data indicated with a line with 'EOF' on it. The data is sent after the query line. flush flushes some information regarding the name from the cache. removes the A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV, NAPTR types. Does not remove other types. flush_type removes rrtype entry from the cache. flush_zone removes name and everything below that name from the cache. has to search through the cache item by item, so this is slow. lookup see what servers would be queried for a lookup of the given name. local_zone_remove the local-zone entry is removed. All data from the local zone is also deleted. If it did not exist, nothing happens. local_zone As the config file entry. Adds new local zone or updates existing zone type. local_data_remove Removes local-data (all types) name. local_data Add new local data record (on the rest of the line). local_data_add www.example.com. IN A 192.0.2.2 if no local_zone exists for it; a transparent zone with the same name as the data is created. Other commands in the unbound-control manual page. --- ### Doc Libunbound (`doc/libunbound.rst`) .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES libunbound(3) ============= Synopsis -------- .. only:: html .. code-block:: c #include struct ub_ctx * ub_ctx_create(void); void ub_ctx_delete(struct ub_ctx* ctx); int ub_ctx_set_option(struct ub_ctx* ctx, char* opt, char* val); int ub_ctx_get_option(struct ub_ctx* ctx, char* opt, char** val); int ub_ctx_config(struct ub_ctx* ctx, char* fname); int ub_ctx_set_fwd(struct ub_ctx* ctx, char* addr); int ub_ctx_set_stub(struct ub_ctx* ctx, char* zone, char* addr, int isprime); int ub_ctx_set_tls(struct ub_ctx* ctx, int tls); int ub_ctx_resolvconf(struct ub_ctx* ctx, char* fname); int ub_ctx_hosts(struct ub_ctx* ctx, char* fname); int ub_ctx_add_ta(struct ub_ctx* ctx, char* ta); int ub_ctx_add_ta_autr(struct ub_ctx* ctx, char* fname); int ub_ctx_add_ta_file(struct ub_ctx* ctx, char* fname); int ub_ctx_trustedkeys(struct ub_ctx* ctx, char* fname); int ub_ctx_debugout(struct ub_ctx* ctx, FILE* out); int ub_ctx_debuglevel(struct ub_ctx* ctx, int d); int ub_ctx_async(struct ub_ctx* ctx, int dothread); int ub_poll(struct ub_ctx* ctx); int ub_wait(struct ub_ctx* ctx); int ub_fd(struct ub_ctx* ctx); int ub_process(struct ub_ctx* ctx); int ub_resolve(struct ub_ctx* ctx, char* name, int rrtype, int rrclass, struct ub_result** result); int ub_resolve_async(struct ub_ctx* ctx, char* name, int rrtype, int rrclass, void* mydata, ub_callback_type callback, int* async_id); int ub_cancel(struct ub_ctx* ctx, int async_id); void ub_resolve_free(struct ub_result* result); const char * ub_strerror(int err); int ub_ctx_print_local_zones(struct ub_ctx* ctx); int ub_ctx_zone_add(struct ub_ctx* ctx, char* zone_name, char* zone_type); int ub_ctx_zone_remove(struct ub_ctx* ctx, char* zone_name); int ub_ctx_data_add(struct ub_ctx* ctx, char* data); int ub_ctx_data_remove(struct ub_ctx* ctx, char* data); .. only:: man **#include ** struct ub_ctx \* **ub_ctx_create**\ (void); void **ub_ctx_delete**\ (struct ub_ctx\* ctx); int **ub_ctx_set_option**\ (struct ub_ctx\* ctx, char\* opt, char\* val); int **ub_ctx_get_option**\ (struct ub_ctx\* ctx, char\* opt, char\*\* val); int **ub_ctx_config**\ (struct ub_ctx\* ctx, char* fname); int **ub_ctx_set_fwd**\ (struct ub_ctx\* ctx, char\* addr); int **ub_ctx_set_stub**\ (struct ub_ctx\* ctx, char\* zone, char\* addr, int isprime); int **ub_ctx_set_tls**\ (struct ub_ctx\* ctx, int tls); int **ub_ctx_resolvconf**\ (struct ub_ctx\* ctx, char\* fname); int **ub_ctx_hosts**\ (struct ub_ctx\* ctx, char\* fname); int **ub_ctx_add_ta**\ (struct ub_ctx\* ctx, char\* ta); int **ub_ctx_add_ta_autr**\ (struct ub_ctx\* ctx, char\* fname); int **ub_ctx_add_ta_file**\ (struct ub_ctx\* ctx, char\* fname); int **ub_ctx_trustedkeys**\ (struct ub_ctx\* ctx, char\* fname); int **ub_ctx_debugout**\ (struct ub_ctx\* ctx, FILE\* out); int **ub_ctx_debuglevel**\ (struct ub_ctx\* ctx, int d); int **ub_ctx_async**\ (struct ub_ctx\* ctx, int dothread); int **ub_poll**\ (struct ub_ctx\* ctx); int **ub_wait**\ (struct ub_ctx\* ctx); int **ub_fd**\ (struct ub_ctx\* ctx); int **ub_process**\ (struct ub_ctx\* ctx); int **ub_resolve**\ (struct ub_ctx\* ctx, char\* name, int rrtype, int rrclass, struct ub_result\*\* result); int **ub_resolve_async**\ (struct ub_ctx\* ctx, char\* name, int rrtype, int rrclass, void\* mydata, ub_callback_type\* callback, int\* async_id); int **ub_cancel**\ (struct ub_ctx\* ctx, int async_id); void **ub_resolve_free**\ (struct ub_result\* result); const char \* **ub_strerror**\ (int err); int **ub_ctx_print_local_zones**\ (struct ub_ctx\* ctx); int **ub_ctx_zone_add**\ (struct ub_ctx\* ctx, char\* zone_name, char\* zone_type); int **ub_ctx_zone_remove**\ (struct ub_ctx\* ctx, char\* zone_name); int **ub_ctx_data_add**\ (struct ub_ctx\* ctx, char\* data); int **ub_ctx_data_remove**\ (struct ub_ctx\* ctx, char\* data); Description ----------- Unbound is an implementation of a DNS resolver, that does caching and DNSSEC validation. This is the library API, for using the ``-lunbound`` library. The server daemon is described in :doc:`unbound(8)`. The library works independent from a running unbound server, and can be used to convert hostnames to ip addresses, and back, and obtain other information from the DNS. The library performs public-key validation of results with DNSSEC. The library uses a variable of type *struct ub_ctx* to keep context between calls. The user must maintain it, creating it with **ub_ctx_create** and deleting it with **ub_ctx_delete**. It can be created and deleted at any time. Creating it anew removes any previous configuration (such as trusted keys) and clears any cached results. The functions are thread-safe, and a context can be used in a threaded (as well as in a non-threaded) environment. Also resolution (and validation) can be performed blocking and non-blocking (also called asynchronous). The async method returns from the call immediately, so that processing can go on, while the results become available later. The functions are discussed in turn below. Functions --------- .. glossary:: ub_ctx_create Create a new context, initialised with defaults. The information from :file:`/etc/resolv.conf` and :file:`/etc/hosts` is not utilised by default. Use **ub_ctx_resolvconf** and **ub_ctx_hosts** to read them. Before you call this, use the openssl functions **CRYPTO_set_id_callback** and **CRYPTO_set_locking_callback** to set up asynchronous operation if you use lib openssl (the application calls these functions once for initialisation). Openssl 1.0.0 or later uses the **CRYPTO_THREADID_set_callback** function. ub_ctx_delete Delete validation context and free associated resources. Outstanding async queries are killed and callbacks are not called for them. ub_ctx_set_option A power-user interface that lets you specify one of the options from the config file format, see :doc:`unbound.conf(5)`. Not all options are relevant. For some specific options, such as adding trust anchors, special routines exist. Pass the option name with the trailing ``':'``. ub_ctx_get_option A power-user interface that gets an option value. Some options cannot be gotten, and others return a newline separated list. Pass the option name without trailing ``':'``. The returned value must be free(2)d by the caller. ub_ctx_config A power-user interface that lets you specify an unbound config file, see :doc:`unbound.conf(5)`, which is read for configuration. Not all options are relevant. For some specific options, such as adding trust anchors, special routines exist. This function is thread-safe only if a single instance of **ub_ctx**\* exists in the application. If several instances exist the application has to ensure that **ub_ctx_config** is not called in parallel by the different instances. ub_ctx_set_fwd Set machine to forward DNS queries to, the caching resolver to use. IP4 or IP6 address. Forwards all DNS requests to that machine, which is expected to run a recursive resolver. If the proxy is not DNSSEC capable, validation may fail. Can be called several times, in that case the addresses are used as backup servers. At this time it is only possible to set configuration before the first resolve is done. ub_ctx_set_stub Set a stub zone, authoritative dns servers to use for a particular zone. IP4 or IP6 address. If the address is NULL the stub entry is removed. Set isprime true if you configure root hints with it. Otherwise similar to the stub zone item from unbound's config file. Can be called several times, for different zones, or to add multiple addresses for a particular zone. At this time it is only possible to set configuration before the first resolve is done. ub_ctx_set_tls Enable DNS over TLS (DoT) for machines set with **ub_ctx_set_fwd**. At this time it is only possible to set configuration before the first resolve is done. ub_ctx_resolvconf By default the root servers are queried and full resolver mode is used, but you can use this call to read the list of nameservers to use from the filename given. Usually :file:`"/etc/resolv.conf"`. Uses those nameservers as caching proxies. If they do not support DNSSEC, validation may fail. Only nameservers are picked up, the searchdomain, ndots and other settings from *resolv.conf(5)* are ignored. If fname NULL is passed, :file:`"/etc/resolv.conf"` is used (if on Windows, the system-wide configured nameserver is picked instead). At this time it is only possible to set configuration before the first resolve is done. ub_ctx_hosts Read list of hosts from the filename given. Usually :file:`"/etc/hosts"`. When queried for, these addresses are not marked DNSSEC secure. If fname NULL is passed, :file:`"/etc/hosts"` is used (if on Windows, :file:`etc/hosts` from WINDIR is picked instead). At this time it is only possible to set configuration before the first resolve is done. ub_ctx_add_ta Add a trust anchor to the given context. At this time it is only possible to add trusted keys before the first resolve is done. The format is a string, similar to the zone-file format, **[domainname]** **[type]** **[rdata contents]**. Both DS and DNSKEY records are accepted. ub_ctx_add_ta_autr Add filename with automatically tracked trust anchor to the given context. Pass name of a file with the managed trust anchor. You can create this file with :doc:`unbound-anchor(8)` for the root anchor. You can also create it with an initial file with one line with a DNSKEY or DS record. If the file is writable, it is updated when the trust anchor changes. At this time it is only possible to add trusted keys before the first resolve is done. ub_ctx_add_ta_file Add trust anchors to the given context. Pass name of a file with DS and DNSKEY records in zone file format. At this time it is only possible to add trusted keys before the first resolve is done. ub_ctx_trustedkeys Add trust anchors to the given context. Pass the name of a bind-style config file with ``trusted-keys{}``. At this time it is only possible to add trusted keys before the first resolve is done. ub_ctx_debugout Set debug and error log output to the given stream. Pass NULL to disable output. Default is stderr. File-names or using syslog can be enabled using config options, this routine is for using your own stream. ub_ctx_debuglevel Set debug verbosity for the context. Output is directed to stderr. Higher debug level gives more output. ub_ctx_async Set a context behaviour for asynchronous action. if set to true, enables threading and a call to **ub_resolve_async** creates a thread to handle work in the background. If false, a process is forked to handle work in the background. Changes to this setting after **ub_resolve_async** calls have been made have no effect (delete and re-create the context to change). ub_poll Poll a context to see if it has any new results. Do not poll in a loop, instead extract the **fd** below to poll for readiness, and then check, or wait using the wait routine. Returns 0 if nothing to read, or nonzero if a result is available. If nonzero, call **ub_process** to do callbacks. ub_wait Wait for a context to finish with results. Calls **ub_process** after the wait for you. After the wait, there are no more outstanding asynchronous queries. ub_fd Get file descriptor. Wait for it to become readable, at this point answers are returned from the asynchronous validating resolver. Then call the **ub_process** to continue processing. ub_process Call this routine to continue processing results from the validating resolver (when the **fd** becomes readable). Will perform necessary callbacks. ub_resolve Perform resolution and validation of the target name. The name is a domain name in a zero terminated text string. The rrtype and rrclass are DNS type and class codes. The result structure is newly allocated with the resulting data. ub_resolve_async Perform asynchronous resolution and validation of the target name. Arguments mean the same as for **ub_resolve** except no data is returned immediately, instead a callback is called later. The callback receives a copy of the mydata pointer, that you can use to pass information to the callback. The callback type is a function pointer to a function declared as: .. code-block:: c void my_callback_function(void* my_arg, int err, struct ub_result* result); The **async_id** is returned so you can (at your option) decide to track it and cancel the request if needed. If you pass a NULL pointer the **async_id** is not returned. The context, created via **ub_ctx_create**, is in use during but also after the callback and it cannot be deleted during a callback. ub_cancel Cancel an async query in progress. This may return an error if the query does not exist, or the query is already being delivered, in that case you may still get a callback for the query. ub_resolve_free Free struct **ub_result** contents after use. ub_strerror Convert error value from one of the unbound library functions to a human readable string. ub_ctx_print_local_zones Debug printout the local authority information to debug output. ub_ctx_zone_add Add new zone to local authority info, like local-zone :doc:`unbound.conf(5)` statement. ub_ctx_zone_remove Delete zone from local authority info. ub_ctx_data_add Add resource record data to local authority info, like local-data :doc:`unbound.conf(5)` statement. ub_ctx_data_remove Delete local authority data from the name given. Result Data structure --------------------- The result of the DNS resolution and validation is returned as *struct ub_result*. The result structure contains the following entries: .. code-block:: c struct ub_result { char* qname; /* text string, original question */ int qtype; /* type code asked for */ int qclass; /* class code asked for */ char** data; /* array of rdata items, NULL terminated*/ int* len; /* array with lengths of rdata items */ char* canonname; /* canonical name of result */ int rcode; /* additional error code in case of no data */ void* answer_packet; /* full network format answer packet */ int answer_len; /* length of packet in octets */ int havedata; /* true if there is data */ int nxdomain; /* true if nodata because name does not exist */ int secure; /* true if result is secure */ int bogus; /* true if a security failure happened */ char* why_bogus; /* string with error if bogus */ int was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */ int ttl; /* number of seconds the result is valid */ }; If both secure and bogus are false, security was not enabled for the domain of the query. Else, they are not both true, one of them is true. Return Values ------------- Many routines return an error code. The value 0 (zero) denotes no error happened. Other values can be passed to **ub_strerror** to obtain a readable error string. **ub_strerror** returns a zero terminated string. **ub_ctx_create** returns NULL on an error (a malloc failure). **ub_poll** returns true if some information may be available, false otherwise. **ub_fd** returns a file descriptor or -1 on error. **ub_ctx_config** and **ub_ctx_resolvconf** attempt to leave errno informative on a function return with file read failure. See Also -------- :doc:`unbound.conf(5)`, :doc:`unbound(8)`. --- ### Doc Requirements (`doc/requirements.txt`) Requirements for Recursive Caching Resolver (a.k.a. Treeshrew, Unbound-C) By W.C.A. Wijngaards, NLnet Labs, October 2006. Contents 1. Introduction 2. History 3. Goals 4. Non-Goals 1. Introduction --------------- This is the requirements document for a DNS name server and aims to document the goals and non-goals of the project. The DNS (the Domain Name System) is a global, replicated database that uses a hierarchical structure for queries. Data in the DNS is stored in Resource Record sets (RR sets), and has a time to live (TTL). During this time the data can be cached. It is thus useful to cache data to speed up future lookups. A server that looks up data in the DNS for clients and caches previous answers to speed up processing is called a caching, recursive nameserver. This project aims to develop such a nameserver in modular components, so that also DNSSEC (secure DNS) validation and stub-resolvers (that do not run as a server, but a linked into an application) are easily possible. The main components are the Validator that validates the security fingerprints on data sets, the Iterator that sends queries to the hierarchical DNS servers that own the data and the Cache that stores data from previous queries. The networking and query management code then interface with the modules to perform the necessary processing. In Section 2 the origins of the Unbound project are documented. Section 3 lists the goals, while Section 4 lists the explicit non-goals of the project. Section 5 discusses choices made during development. 2. History ---------- The unbound resolver project started by Bill Manning, David Blacka, and Matt Larson (from the University of California and from Verisign), that created a Java based prototype resolver called Unbound. The basic design decisions of clean modules was executed. The Java prototype worked very well, with contributions from Geoff Sisson and Roy Arends from Nominet. Around 2006 the idea came to create a full-fledged C implementation ready for deployed use. NLnet Labs volunteered to write this implementation. 3. Goals -------- o A validating recursive DNS resolver. o Code diversity in the DNS resolver monoculture. o Drop-in replacement for BIND apart from config. o DNSSEC support. o Fully RFC compliant. o High performance * even with validation. o Used as * stub resolver. * full caching name server. * resolver library. o Elegant design of validator, resolver, cache modules. * provide the ability to pick and choose modules. o Robust. o In C, open source: The BSD license. o Highly portable, targets include modern Unix systems, such as *BSD, solaris, linux, and maybe also the windows platform. o Smallest as possible component that does the job. o Stub-zones can be configured (local data or AS112 zones). 4. Non-Goals ------------ o An authoritative name server. o Too many Features. 5. Choices ---------- o rfc2181 discourages duplicates RRs in RRsets. unbound does not create duplicates, but when presented with duplicates on the wire from the authoritative servers, does not perform duplicate removal. It does do some rrsig duplicate removal, in the msgparser, for dnssec qtype rrsig and any, because of special rrsig processing in the msgparser. o The harden-glue feature, when yes all out of zone glue is deleted, when no out of zone glue is used for further resolving, is more complicated than that, see below. Main points: * rfc2182 trust handling is used. * data is let through only in very specific cases * spoofability remains possible. Not all glue is let through (despite the name of the option). Only glue which is present in a delegation, of type A and AAAA, where the name is present in the NS record in the authority section is let through. The glue that is let through is stored in the cache (marked as 'from the additional section'). And will then be used for sending queries to. It will not be present in the reply to the client (if RD is off). A direct query for that name will attempt to get a msg into the message cache. Since A and AAAA queries are not synthesized by the unbound cache, this query will be (eventually) sent to the authoritative server and its answer will be put in the cache, marked as 'from the answer section' and thus remove the 'from the additional section' data, and this record is returned to the client. The message has a TTL smaller or equal to the TTL of the answer RR. If the cache memory is low; the answer RR may be dropped, and a glue RR may be inserted, within the message TTL time, and thus return the spoofed glue to a client. When the message expires, it is refetched and the cached RR is updated with the correct content. The server can be spoofed by getting it to visit a especially prepared domain. This domain then inserts an address for another authoritative server into the cache, when visiting that other domain, this address may then be used to send queries to. And fake answers may be returned. If the other domain is signed by DNSSEC, the fakes will be detected. In summary, the harden glue feature presents a security risk if disabled. Disabling the feature leads to possible better performance as more glue is present for the recursive service to use. The feature is implemented so as to minimise the security risk, while trying to keep this performance gain. o The method by which dnssec-lameness is detected is not secure. DNSSEC lame is when a server has the zone in question, but lacks dnssec data, such as signatures. The method to detect dnssec lameness looks at nonvalidated data from the parent of a zone. This can be used, by spoofing the parent, to create a false sense of dnssec-lameness in the child, or a false sense or dnssec-non-lameness in the child. The first results in the server marked lame, and not used for 900 seconds, and the second will result in a validator failure (SERVFAIL again), when the query is validated later on. Concluding, a spoof of the parent delegation can be used for many cases of denial of service. I.e. a completely different NS set could be returned, or the information withheld. All of these alterations can be caught by the validator if the parent is signed, and result in 900 seconds bogus. The dnssec-lameness detection is used to detect operator failures, before the validator will properly verify the messages. Also for zones for which no chain of trust exists, but a DS is given by the parent, dnssec-lameness detection enables. This delivers dnssec to our clients when possible (for client validators). The following issue needs to be resolved: a server that serves both a parent and child zone, where parent is signed, but child is not. The server must not be marked lame for the parent zone, because the child answer is not signed. Instead of a false positive, we want false negatives; failure to detect dnssec-lameness is less of a problem than marking honest servers lame. dnssec-lameness is a config error and deserves the trouble. So, only messages that identify the zone are used to mark the zone lame. The zone is identified by SOA or NS RRsets in the answer/auth. That includes almost all negative responses and also A, AAAA qtypes. That would be most responses from servers. For referrals, delegations that add a single label can be checked to be from their zone, this covers most delegation-centric zones. So possibly, for complicated setups, with multiple (parent-child) zones on a server, dnssec-lameness detection does not work - no dnssec-lameness is detected. Instead the zone that is dnssec-lame becomes bogus. o authority features. This is a recursive server, and authority features are out of scope. However, some authority features are expected in a recursor. Things like localhost, reverse lookup for 127.0.0.1, or blocking AS112 traffic. Also redirection of domain names with fixed data is needed by service providers. Limited support is added specifically to address this. Adding full authority support, requires much more code, and more complex maintenance. The limited support allows adding some static data (for localhost and so), and to respond with a fixed rcode (NXDOMAIN) for domains (such as AS112). You can put authority data on a separate server, and set the server in unbound.conf as stub for those zones, this allows clients to access data from the server without making unbound authoritative for the zones. o the access control denies queries before any other processing. This denies queries that are not authoritative, or version.bind, or any. And thus prevents cache-snooping (denied hosts cannot make non-recursive queries and get answers from the cache). o If a client makes a query without RD bit, in the case of a returned message from cache which is: answer section: empty auth section: NS record present, no SOA record, no DS record, maybe NSEC or NSEC3 records present. additional: A records or other relevant records. A SOA record would indicate that this was a NODATA answer. A DS records would indicate a referral. Absence of NS record would indicate a NODATA answer as well. Then the receiver does not know whether this was a referral with attempt at no-DS proof) or a nodata answer with attempt at no-data proof. It could be determined by attempting to prove either condition; and looking if only one is valid, but both proofs could be valid, or neither could be valid, which creates doubt. This case is validated by unbound as a 'referral' which ascertains that RRSIGs are OK (and not omitted), but does not check NSEC/NSEC3. o Case preservation Unbound preserves the casing received from authority servers as best as possible. It compresses without case, so case can get lost there. The casing from the query name is used in preference to the casing of the authority server. This is the same as BIND. RFC4343 allows either behaviour. o Denial of service protection If many queries are made, and they are made to names for which the authority servers do not respond, then the requestlist for unbound fills up fast. This results in denial of service for new queries. To combat this the first 50% of the requestlist can run to completion. The last 50% of the requestlist get (200 msec) at least and are replaced by newer queries when older (LIFO). When a new query comes in, and a place in the first 50% is available, this is preferred. Otherwise, it can replace older queries out of the last 50%. Thus, even long queries get a 50% chance to be resolved. And many 'short' one or two round-trip resolves can be done in the last 50% of the list. The timeout can be configured. o EDNS fallback. Is done according to the EDNS RFC (and update draft-00). Unbound assumes EDNS 0 support for the first query. Then it can detect support (if the servers replies) or non-support (on a NOTIMPL or FORMERR). Some middleboxes drop EDNS 0 queries, mainly when forwarding, not when routing packets. To detect this, when timeouts keep happening, as the timeout approached 5-10 seconds, and EDNS status has not been detected yet, a single probe query is sent. This probe has a sub-second timeout, and if the server responds (quickly) without EDNS, this is cached for 15 min. This works very well when detecting an address that you use much - like a forwarder address - which is where the middleboxes need to be detected. Otherwise, it results in a 5 second wait time before EDNS timeout is detected, which is slow but it works at least. It minimizes the chances of a dropped query making a (DNSSEC) EDNS server falsely EDNS-nonsupporting, and thus DNSSEC-bogus, works well with middleboxes, and can detect the occasional authority that drops EDNS. For some boxes it is necessary to probe for every failing query, a reassurance that the DNS server does EDNS does not mean that path can take large DNS answers. o 0x20 backoff. The draft describes to back off to the next server, and go through all servers several times. Unbound goes on get the full list of nameserver addresses, and then makes 3 * number of addresses queries. They are sent to a random server, but no one address more than 4 times. It succeeds if one has 0x20 intact, or else all are equal. Otherwise, servfail is returned to the client. o NXDOMAIN and SOA serial numbers. Unbound keeps TTL values for message formats, and thus rcodes, such as NXDOMAIN. Also it keeps the latest rrsets in the rrset cache. So it will faithfully negative cache for the exact TTL as originally specified for an NXDOMAIN message, but send a newer SOA record if this has been found in the mean time. In point, this could lead to a negative cached NXDOMAIN reply with a SOA RR where the serial number indicates a zone version where this domain is not any longer NXDOMAIN. These situations become consistent once the original TTL expires. If the domain is DNSSEC signed, by the way, then NSEC records are updated more carefully. If one of the NSEC records in an NXDOMAIN is updated from another query, the NXDOMAIN is dropped from the cache, and queried for again, so that its proof can be checked again. o SOA records in negative cached answers for DS queries. The current unbound code uses a negative cache for queries for type DS. This speeds up building chains of trust, and uses NSEC and NSEC3 (optout) information to speed up lookups. When used internally, the bare NSEC(3) information is sufficient, probably picked up from a referral. When answering to clients, a SOA record is needed for the correct message format, a SOA record is picked from the cache (and may not actually match the serial number of the SOA for which the NSEC and NSEC3 records were obtained) if available otherwise network queries are performed to get the data. o Parent and child with different nameserver information. A misconfiguration that sometimes happens is where the parent and child have different NS, glue information. The child is authoritative, and unbound will not trust information from the parent nameservers as the final answer. To help lookups, unbound will however use the parent-side version of the glue as a last resort lookup. This resolves lookups for those misconfigured domains where the servers reported by the parent are the only ones working, and servers reported by the child do not. o Failure of validation and probing. Retries on a validation failure are now 5x to a different nameserver IP (if possible), and then it gives up, for one name, type, class entry in the message cache. If a DNSKEY or DS fails in the chain of trust in the key cache additionally, after the probing, a bad key entry is created that makes the entire zone bogus for 900 seconds. This is a fixed value at this time and is conservative in sending probes. It makes the compound effect of many resolvers less and easier to handle, but penalizes individual resolvers by having less probes and a longer time before fixes are picked up. --- ### Doc Unbound Anchor (`doc/unbound-anchor.rst`) .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES .. program:: unbound-anchor unbound-anchor(8) ================= Synopsis -------- **unbound-anchor** [``opts``] Description ----------- ``unbound-anchor`` performs setup or update of the root trust anchor for DNSSEC validation. The program fetches the trust anchor with the method from :rfc:`7958` when regular :rfc:`5011` update fails to bring it up to date. It can be run from the commandline, or run as part of startup scripts before you start the :doc:`unbound(8)` DNS server. Note that if you want to use :rfc:`5011` with Unbound (i.e., the :ref:`auto-trust-anchor-file` option) so that trust anchor information is automatically tracked by Unbound during operation, the user that Unbound runs under (by default 'unbound') must have write permissions to the file and the directory the file lives in (for creating temporary files). In this case you would probably want to run this program as the designated Unbound user. Suggested usage: .. code-block:: text # in the init scripts. # provide or update the root anchor (if necessary) unbound-anchor -a "@UNBOUND_ROOTKEY_FILE@" # Please note usage of this root anchor is at your own risk # and under the terms of our LICENSE (see source). # # start validating resolver # the unbound.conf contains: # auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@" unbound -c unbound.conf This tool provides builtin default contents for the root anchor and root update certificate files. It tests if the root anchor file works, and if not, and an update is possible, attempts to update the root anchor using the root update certificate. It performs a https fetch of `root-anchors.xml `__ and checks the results (:rfc:`7958`); if all checks are successful, it updates the root anchor file. Otherwise the root anchor file is unchanged. It performs :rfc:`5011` tracking if the DNSSEC information available via the DNS makes that possible. It does not perform an update if the certificate is expired, if the network is down or other errors occur. The available options are: .. option:: -a The root anchor key file, that is read in and written out. Default is :file:`@UNBOUND_ROOTKEY_FILE@`. If the file does not exist, or is empty, a builtin root key is written to it. .. option:: -c The root update certificate file, that is read in. Default is :file:`@UNBOUND_ROOTCERT_FILE@`. If the file does not exist, or is empty, a builtin certificate is used. .. option:: -l List the builtin root key and builtin root update certificate on stdout. .. option:: -u The server name, it connects to ``https://name``. Specify without ``https://`` prefix. The default is ``"data.iana.org"``. It connects to the port specified with :option:`-P`. You can pass an IPv4 address or IPv6 address (no brackets) if you want. .. option:: -S Do not use SNI for the HTTPS connection. Default is to use SNI. .. option:: -b
The source address to bind to for domain resolution and contacting the server on https. May be either an IPv4 address or IPv6 address (no brackets). .. option:: -x The pathname to the root-anchors.xml file on the server. (forms URL with :option:`-u`). The default is :file:`/root-anchors/root-anchors.xml`. .. option:: -s The pathname to the root-anchors.p7s file on the server. (forms URL with :option:`-u`). The default is :file:`/root-anchors/root-anchors.p7s`. This file has to be a PKCS7 signature over the xml file, using the pem file (:option:`-c`) as trust anchor. .. option:: -n The emailAddress for the Subject of the signer's certificate from the p7s signature file. Only signatures from this name are allowed. The default is ``dnssec@iana.org``. If you pass ``""`` then the emailAddress is not checked. .. option:: -4 Use IPv4 for domain resolution and contacting the server on https. Default is to use IPv4 and IPv6 where appropriate. .. option:: -6 Use IPv6 for domain resolution and contacting the server on https. Default is to use IPv4 and IPv6 where appropriate. .. option:: -f Use the given resolv.conf file. Not enabled by default, but you could try to pass :file:`/etc/resolv.conf` on some systems. It contains the IP addresses of the recursive nameservers to use. However, since this tool could be used to bootstrap that very recursive nameserver, it would not be useful (since that server is not up yet, since we are bootstrapping it). It could be useful in a situation where you know an upstream cache is deployed (and running) and in captive portal situations. .. option:: -r Use the given root.hints file (same syntax as the BIND and Unbound root hints file) to bootstrap domain resolution. By default a list of builtin root hints is used. unbound-anchor goes to the network itself for these roots, to resolve the server (:option:`-u` option) and to check the root DNSKEY records. It does so, because the tool when used for bootstrapping the recursive resolver, cannot use that recursive resolver itself because it is bootstrapping that server. .. option:: -R Allow fallback from :option:`-f` ```` file to direct root servers query. It allows you to prefer local resolvers, but fallback automatically to direct root query if they do not respond or do not support DNSSEC. .. option:: -v More verbose. Once prints informational messages, multiple times may enable large debug amounts (such as full certificates or byte-dumps of downloaded files). By default it prints almost nothing. It also prints nothing on errors by default; in that case the original root anchor file is simply left undisturbed, so that a recursive server can start right after it. .. option:: -C Debug option to read :file:`` into the resolver process used. .. option:: -P Set the port number to use for the https connection. The default is 443. .. option:: -F Debug option to force update of the root anchor through downloading the xml file and verifying it with the certificate. By default it first tries to update by contacting the DNS, which uses much less bandwidth, is much faster (200 msec not 2 sec), and is nicer to the deployed infrastructure. With this option, it still attempts to do so (and may verbosely tell you), but then ignores the result and goes on to use the xml fallback method. .. option:: -h Show the version and commandline option help. Exit Code --------- This tool exits with value 1 if the root anchor was updated using the certificate or if the builtin root-anchor was used. It exits with code 0 if no update was necessary, if the update was possible with :rfc:`5011` tracking, or if an error occurred. You can check the exit value in this manner: .. code-block:: text unbound-anchor -a "root.key" || logger "Please check root.key" Or something more suitable for your operational environment. Trust ----- The root keys and update certificate included in this tool are provided for convenience and under the terms of our license (see the LICENSE file in the source distribution or https://github.com/NLnetLabs/unbound/blob/master/LICENSE and might be stale or not suitable to your purpose. By running :option:`unbound-anchor -l` the keys and certificate that are configured in the code are printed for your convenience. The built-in configuration can be overridden by providing a root-cert file and a rootkey file. Files ----- @UNBOUND_ROOTKEY_FILE@ The root anchor file, updated with 5011 tracking, and read and written to. The file is created if it does not exist. @UNBOUND_ROOTCERT_FILE@ The trusted self-signed certificate that is used to verify the downloaded DNSSEC root trust anchor. You can update it by fetching it from https://data.iana.org/root-anchors/icannbundle.pem (and validate it). If the file does not exist or is empty, a builtin version is used. https://data.iana.org/root-anchors/root-anchors.xml Source for the root key information. https://data.iana.org/root-anchors/root-anchors.p7s Signature on the root key information. See Also -------- :doc:`unbound.conf(5)`, :doc:`unbound(8)`. --- ### Doc Unbound Checkconf (`doc/unbound-checkconf.rst`) .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES .. WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE .. IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE .. IT HELPS PEOPLE DIFFING THE CHANGES .. program:: unbound-checkconf unbound-checkconf(8) ==================== Synopsis -------- **unbound-checkconf** [``-ahf``] [``-o option``] [cfgfile] Description ----------- ``unbound-checkconf`` checks the configuration file for the :doc:`unbound(8)` DNS resolver for syntax and other errors. The config file syntax is described in :doc:`unbound.conf(5)`. The available options are: .. option:: -a Also read the zonefiles for auth-zones and RPZ. It checks if the syntax is okay of the zonefiles. .. option:: -h Show the version and commandline option help. .. option:: -f Print full pathname, with chroot applied to it. Use with the :option:`-o` option. .. option:: -q Make the operation quiet, suppress output on success. .. option:: -o