diff --git a/contrib/unbound/doc/example.conf b/contrib/unbound/doc/example.conf index 3dc6d3f358d2..d9f4995e41ef 100644 --- a/contrib/unbound/doc/example.conf +++ b/contrib/unbound/doc/example.conf @@ -1,994 +1,1175 @@ # # Example configuration file. # -# See unbound.conf(5) man page, version 1.9.2. +# See unbound.conf(5) man page, version 1.14.0. # # this is a comment. -#Use this to include other text into the file. +# Use this anywhere in the file to include other text into this file. #include: "otherfile.conf" +# Use this anywhere in the file to include other text, that explicitly starts a +# clause, into this file. Text after this directive needs to start a clause. +#include-toplevel: "otherfile.conf" + # The server clause sets the main parameters. server: # whitespace is not necessary, but looks cleaner. # verbosity number, 0 is least verbose. 1 is default. verbosity: 1 # print statistics to the log (for every thread) every N seconds. # Set to "" or 0 to disable. Default is disabled. # statistics-interval: 0 # enable shm for stats, default no. if you enable also enable # statistics-interval, every time it also writes stats to the # shared memory segment keyed with shm-key. # shm-enable: no # shm for stats uses this key, and key+1 for the shared mem segment. # shm-key: 11777 # enable cumulative statistics, without clearing them after printing. # statistics-cumulative: no # enable extended statistics (query types, answer codes, status) # printed from unbound-control. default off, because of speed. # extended-statistics: no # number of threads to create. 1 disables threading. # num-threads: 1 # specify the interfaces to answer queries from by ip-address. # The default is to listen to localhost (127.0.0.1 and ::1). # specify 0.0.0.0 and ::0 to bind to all available interfaces. # specify every interface[@port] on a new 'interface:' labelled line. # The listen interfaces are not changed on reload, only on restart. # interface: 192.0.2.153 # interface: 192.0.2.154 # interface: 192.0.2.154@5003 # interface: 2001:DB8::5 # enable this feature to copy the source address of queries to reply. # Socket options are not supported on all platforms. experimental. # interface-automatic: no # port to answer queries from # port: 53 # specify the interfaces to send outgoing queries to authoritative # server from by ip-address. If none, the default (all) interface # is used. Specify every interface on a 'outgoing-interface:' line. # outgoing-interface: 192.0.2.153 # outgoing-interface: 2001:DB8::5 # outgoing-interface: 2001:DB8::6 # Specify a netblock to use remainder 64 bits as random bits for # upstream queries. Uses freebind option (Linux). # outgoing-interface: 2001:DB8::/64 # Also (Linux:) ip -6 addr add 2001:db8::/64 dev lo # And: ip -6 route add local 2001:db8::/64 dev lo # And set prefer-ip6: yes to use the ip6 randomness from a netblock. # Set this to yes to prefer ipv6 upstream servers over ipv4. # prefer-ip6: no + # Prefer ipv4 upstream servers, even if ipv6 is available. + # prefer-ip4: no + # number of ports to allocate per thread, determines the size of the # port range that can be open simultaneously. About double the # num-queries-per-thread, or, use as many as the OS will allow you. # outgoing-range: 4096 # permit unbound to use this port number or port range for # making outgoing queries, using an outgoing interface. # outgoing-port-permit: 32768 # deny unbound the use this of port number or port range for # making outgoing queries, using an outgoing interface. # Use this to make sure unbound does not grab a UDP port that some # other server on this computer needs. The default is to avoid # IANA-assigned port numbers. # If multiple outgoing-port-permit and outgoing-port-avoid options # are present, they are processed in order. # outgoing-port-avoid: "3200-3208" # number of outgoing simultaneous tcp buffers to hold per thread. # outgoing-num-tcp: 10 # number of incoming simultaneous tcp buffers to hold per thread. # incoming-num-tcp: 10 # buffer size for UDP port 53 incoming (SO_RCVBUF socket option). # 0 is system default. Use 4m to catch query spikes for busy servers. # so-rcvbuf: 0 # buffer size for UDP port 53 outgoing (SO_SNDBUF socket option). # 0 is system default. Use 4m to handle spikes on very busy servers. # so-sndbuf: 0 # use SO_REUSEPORT to distribute queries over threads. # at extreme load it could be better to turn it off to distribute even. # so-reuseport: yes # use IP_TRANSPARENT so the interface: addresses can be non-local # and you can config non-existing IPs that are going to work later on # (uses IP_BINDANY on FreeBSD). # ip-transparent: no # use IP_FREEBIND so the interface: addresses can be non-local # and you can bind to nonexisting IPs and interfaces that are down. # Linux only. On Linux you also have ip-transparent that is similar. # ip-freebind: no + # the value of the Differentiated Services Codepoint (DSCP) + # in the differentiated services field (DS) of the outgoing + # IP packets + # ip-dscp: 0 + # EDNS reassembly buffer to advertise to UDP peers (the actual buffer - # is set with msg-buffer-size). 1472 can solve fragmentation (timeouts) - # edns-buffer-size: 4096 + # is set with msg-buffer-size). + # edns-buffer-size: 1232 # Maximum UDP response size (not applied to TCP response). # Suggested values are 512 to 4096. Default is 4096. 65536 disables it. # max-udp-size: 4096 # max memory to use for stream(tcp and tls) waiting result buffers. # stream-wait-size: 4m # buffer size for handling DNS data. No messages larger than this # size can be sent or received, by UDP or TCP. In bytes. # msg-buffer-size: 65552 # the amount of memory to use for the message cache. # plain value in bytes or you can append k, m or G. default is "4Mb". # msg-cache-size: 4m # the number of slabs to use for the message cache. # the number of slabs must be a power of 2. # more slabs reduce lock contention, but fragment memory usage. # msg-cache-slabs: 4 # the number of queries that a thread gets to service. # num-queries-per-thread: 1024 # if very busy, 50% queries run to completion, 50% get timeout in msec # jostle-timeout: 200 # msec to wait before close of port on timeout UDP. 0 disables. # delay-close: 0 + # perform connect for UDP sockets to mitigate ICMP side channel. + # udp-connect: yes + + # The number of retries when a non-positive response is received. + # outbound-msg-retry: 5 + # msec for waiting for an unknown server to reply. Increase if you # are behind a slow satellite link, to eg. 1128. # unknown-server-time-limit: 376 # the amount of memory to use for the RRset cache. # plain value in bytes or you can append k, m or G. default is "4Mb". # rrset-cache-size: 4m # the number of slabs to use for the RRset cache. # the number of slabs must be a power of 2. # more slabs reduce lock contention, but fragment memory usage. # rrset-cache-slabs: 4 # the time to live (TTL) value lower bound, in seconds. Default 0. # If more than an hour could easily give trouble due to stale data. # cache-min-ttl: 0 # the time to live (TTL) value cap for RRsets and messages in the # cache. Items are not cached for longer. In seconds. # cache-max-ttl: 86400 # the time to live (TTL) value cap for negative responses in the cache # cache-max-negative-ttl: 3600 # the time to live (TTL) value for cached roundtrip times, lameness and # EDNS version information for hosts. In seconds. # infra-host-ttl: 900 # minimum wait time for responses, increase if uplink is long. In msec. # infra-cache-min-rtt: 50 + # enable to make server probe down hosts more frequently. + # infra-keep-probing: no + # the number of slabs to use for the Infrastructure cache. # the number of slabs must be a power of 2. # more slabs reduce lock contention, but fragment memory usage. # infra-cache-slabs: 4 # the maximum number of hosts that are cached (roundtrip, EDNS, lame). # infra-cache-numhosts: 10000 # define a number of tags here, use with local-zone, access-control. # repeat the define-tag statement to add additional tags. # define-tag: "tag1 tag2 tag3" # Enable IPv4, "yes" or "no". # do-ip4: yes # Enable IPv6, "yes" or "no". # do-ip6: yes # Enable UDP, "yes" or "no". # do-udp: yes # Enable TCP, "yes" or "no". # do-tcp: yes # upstream connections use TCP only (and no UDP), "yes" or "no" # useful for tunneling scenarios, default no. # tcp-upstream: no # upstream connections also use UDP (even if do-udp is no). # useful if if you want UDP upstream, but don't provide UDP downstream. # udp-upstream-without-downstream: no # Maximum segment size (MSS) of TCP socket on which the server # responds to queries. Default is 0, system default MSS. # tcp-mss: 0 # Maximum segment size (MSS) of TCP socket for outgoing queries. # Default is 0, system default MSS. # outgoing-tcp-mss: 0 # Idle TCP timeout, connection closed in milliseconds # tcp-idle-timeout: 30000 # Enable EDNS TCP keepalive option. # edns-tcp-keepalive: no # Timeout for EDNS TCP keepalive, in msec. # edns-tcp-keepalive-timeout: 120000 # Use systemd socket activation for UDP, TCP, and control sockets. # use-systemd: no # Detach from the terminal, run in background, "yes" or "no". # Set the value to "no" when unbound runs as systemd service. # do-daemonize: yes # control which clients are allowed to make (recursive) queries # to this server. Specify classless netblocks with /size and action. # By default everything is refused, except for localhost. # Choose deny (drop message), refuse (polite error reply), # allow (recursive ok), allow_setrd (recursive ok, rd bit is forced on), # allow_snoop (recursive and nonrecursive ok) # deny_non_local (drop queries unless can be answered from local-data) # refuse_non_local (like deny_non_local but polite error reply). # access-control: 0.0.0.0/0 refuse # access-control: 127.0.0.0/8 allow # access-control: ::0/0 refuse # access-control: ::1 allow # access-control: ::ffff:127.0.0.1 allow # tag access-control with list of tags (in "" with spaces between) # Clients using this access control element use localzones that # are tagged with one of these tags. # access-control-tag: 192.0.2.0/24 "tag2 tag3" # set action for particular tag for given access control element # if you have multiple tag values, the tag used to lookup the action # is the first tag match between access-control-tag and local-zone-tag # where "first" comes from the order of the define-tag values. # access-control-tag-action: 192.0.2.0/24 tag3 refuse # set redirect data for particular tag for access control element # access-control-tag-data: 192.0.2.0/24 tag2 "A 127.0.0.1" # Set view for access control element # access-control-view: 192.0.2.0/24 viewname # if given, a chroot(2) is done to the given directory. # i.e. you can chroot to the working directory, for example, # for extra security, but make sure all files are in that directory. # # If chroot is enabled, you should pass the configfile (from the # commandline) as a full path from the original root. After the # chroot has been performed the now defunct portion of the config # file path is removed to be able to reread the config after a reload. # # All other file paths (working dir, logfile, roothints, and # key files) can be specified in several ways: # o as an absolute path relative to the new root. # o as a relative path to the working directory. # o as an absolute path relative to the original root. # In the last case the path is adjusted to remove the unused portion. # # The pid file can be absolute and outside of the chroot, it is # written just prior to performing the chroot and dropping permissions. # - # Additionally, unbound may need to access /dev/random (for entropy). + # Additionally, unbound may need to access /dev/urandom (for entropy). # How to do this is specific to your OS. # # If you give "" no chroot is performed. The path must not end in a /. - # chroot: "/var/unbound" + # chroot: "@UNBOUND_CHROOT_DIR@" # if given, user privileges are dropped (after binding port), # and the given username is assumed. Default is user "unbound". # If you give "" no privileges are dropped. - # username: "unbound" + # username: "@UNBOUND_USERNAME@" # the working directory. The relative files in this config are # relative to this directory. If you give "" the working directory # is not changed. # If you give a server: directory: dir before include: file statements # then those includes can be relative to the working directory. - # directory: "/var/unbound" + # directory: "@UNBOUND_RUN_DIR@" # the log file, "" means log to stderr. # Use of this option sets use-syslog to "no". # logfile: "" # Log to syslog(3) if yes. The log facility LOG_DAEMON is used to # log to. If yes, it overrides the logfile. # use-syslog: yes # Log identity to report. if empty, defaults to the name of argv[0] # (usually "unbound"). # log-identity: "" # print UTC timestamp in ascii to logfile, default is epoch in seconds. # log-time-ascii: no # print one line with time, IP, name, type, class for every query. # log-queries: no # print one line per reply, with time, IP, name, type, class, rcode, # timetoresolve, fromcache and responsesize. # log-replies: no # log with tag 'query' and 'reply' instead of 'info' for # filtering log-queries and log-replies from the log. # log-tag-queryreply: no # log the local-zone actions, like local-zone type inform is enabled # also for the other local zone types. # log-local-actions: no # print log lines that say why queries return SERVFAIL to clients. # log-servfail: no # the pid file. Can be an absolute path outside of chroot/work dir. - # pidfile: "/var/unbound/unbound.pid" + # pidfile: "@UNBOUND_PIDFILE@" # file to read root hints from. # get one from https://www.internic.net/domain/named.cache # root-hints: "" # enable to not answer id.server and hostname.bind queries. # hide-identity: no # enable to not answer version.server and version.bind queries. # hide-version: no # enable to not answer trustanchor.unbound queries. # hide-trustanchor: no + # enable to not set the User-Agent HTTP header. + # hide-http-user-agent: no + # the identity to report. Leave "" or default to return hostname. # identity: "" # the version to report. Leave "" or default to return package version. # version: "" + # NSID identity (hex string, or "ascii_somestring"). default disabled. + # nsid: "aabbccdd" + + # User-Agent HTTP header to use. Leave "" or default to use package name + # and version. + # http-user-agent: "" + # the target fetch policy. # series of integers describing the policy per dependency depth. # The number of values in the list determines the maximum dependency # depth the recursor will pursue before giving up. Each integer means: # -1 : fetch all targets opportunistically, # 0: fetch on demand, # positive value: fetch that many targets opportunistically. # Enclose the list of numbers between quotes (""). # target-fetch-policy: "3 2 1 0 0" # Harden against very small EDNS buffer sizes. - # harden-short-bufsize: no + # harden-short-bufsize: yes # Harden against unseemly large queries. # harden-large-queries: no # Harden against out of zone rrsets, to avoid spoofing attempts. # harden-glue: yes # Harden against receiving dnssec-stripped data. If you turn it # off, failing to validate dnskey data for a trustanchor will # trigger insecure mode for that zone (like without a trustanchor). # Default on, which insists on dnssec data for trust-anchored zones. # harden-dnssec-stripped: yes # Harden against queries that fall under dnssec-signed nxdomain names. # harden-below-nxdomain: yes # Harden the referral path by performing additional queries for # infrastructure data. Validates the replies (if possible). # Default off, because the lookups burden the server. Experimental # implementation of draft-wijngaards-dnsext-resolver-side-mitigation. # harden-referral-path: no # Harden against algorithm downgrade when multiple algorithms are # advertised in the DS record. If no, allows the weakest algorithm # to validate the zone. # harden-algo-downgrade: no # Sent minimum amount of information to upstream servers to enhance # privacy. Only sent minimum required labels of the QNAME and set QTYPE # to A when possible. # qname-minimisation: yes # QNAME minimisation in strict mode. Do not fall-back to sending full # QNAME to potentially broken nameservers. A lot of domains will not be # resolvable when this option in enabled. # This option only has effect when qname-minimisation is enabled. # qname-minimisation-strict: no # Aggressive NSEC uses the DNSSEC NSEC chain to synthesize NXDOMAIN # and other denials, using information from previous NXDOMAINs answers. # aggressive-nsec: no # Use 0x20-encoded random bits in the query to foil spoof attempts. # This feature is an experimental implementation of draft dns-0x20. # use-caps-for-id: no # Domains (and domains in them) without support for dns-0x20 and # the fallback fails because they keep sending different answers. - # caps-whitelist: "licdn.com" - # caps-whitelist: "senderbase.org" + # caps-exempt: "licdn.com" + # caps-exempt: "senderbase.org" # Enforce privacy of these addresses. Strips them away from answers. # It may cause DNSSEC validation to additionally mark it as bogus. # Protects against 'DNS Rebinding' (uses browser as network proxy). # Only 'private-domain' and 'local-data' names are allowed to have # these private addresses. No default. # private-address: 10.0.0.0/8 # private-address: 172.16.0.0/12 # private-address: 192.168.0.0/16 # private-address: 169.254.0.0/16 # private-address: fd00::/8 # private-address: fe80::/10 # private-address: ::ffff:0:0/96 # Allow the domain (and its subdomains) to contain private addresses. # local-data statements are allowed to contain private addresses too. # private-domain: "example.com" # If nonzero, unwanted replies are not only reported in statistics, # but also a running total is kept per thread. If it reaches the # threshold, a warning is printed and a defensive action is taken, # the cache is cleared to flush potential poison out of it. # A suggested value is 10000000, the default is 0 (turned off). # unwanted-reply-threshold: 0 # Do not query the following addresses. No DNS queries are sent there. # List one address per entry. List classless netblocks with /size, # do-not-query-address: 127.0.0.1/8 # do-not-query-address: ::1 # if yes, the above default do-not-query-address entries are present. # if no, localhost can be queried (for testing and debugging). # do-not-query-localhost: yes # if yes, perform prefetching of almost expired message cache entries. # prefetch: no # if yes, perform key lookups adjacent to normal lookups. # prefetch-key: no # deny queries of type ANY with an empty response. # deny-any: no # if yes, Unbound rotates RRSet order in response. - # rrset-roundrobin: no + # rrset-roundrobin: yes # if yes, Unbound doesn't insert authority/additional sections # into response messages when those sections are not required. # minimal-responses: yes # true to disable DNSSEC lameness check in iterator. # disable-dnssec-lame-check: no # module configuration of the server. A string with identifiers # separated by spaces. Syntax: "[dns64] [validator] iterator" # most modules have to be listed at the beginning of the line, # except cachedb(just before iterator), and python (at the beginning, # or, just before the iterator). # module-config: "validator iterator" # File with trusted keys, kept uptodate using RFC5011 probes, # initial file like trust-anchor-file, then it stores metadata. # Use several entries, one per domain name, to track multiple zones. # # If you want to perform DNSSEC validation, run unbound-anchor before - # you start unbound (i.e. in the system boot scripts). And enable: + # you start unbound (i.e. in the system boot scripts). + # And then enable the auto-trust-anchor-file config item. # Please note usage of unbound-anchor root anchor is at your own risk # and under the terms of our LICENSE (see that file in the source). - # auto-trust-anchor-file: "/var/unbound/root.key" + # auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@" # trust anchor signaling sends a RFC8145 key tag query after priming. # trust-anchor-signaling: yes # Root key trust anchor sentinel (draft-ietf-dnsop-kskroll-sentinel) # root-key-sentinel: yes - # File with DLV trusted keys. Same format as trust-anchor-file. - # There can be only one DLV configured, it is trusted from root down. - # DLV is going to be decommissioned. Please do not use it any more. - # dlv-anchor-file: "dlv.isc.org.key" - # File with trusted keys for validation. Specify more than one file # with several entries, one file per entry. # Zone file format, with DS and DNSKEY entries. # Note this gets out of date, use auto-trust-anchor-file please. # trust-anchor-file: "" # Trusted key for validation. DS or DNSKEY. specify the RR on a # single line, surrounded by "". TTL is ignored. class is IN default. # Note this gets out of date, use auto-trust-anchor-file please. # (These examples are from August 2007 and may not be valid anymore). # trust-anchor: "nlnetlabs.nl. DNSKEY 257 3 5 AQPzzTWMz8qSWIQlfRnPckx2BiVmkVN6LPupO3mbz7FhLSnm26n6iG9N Lby97Ji453aWZY3M5/xJBSOS2vWtco2t8C0+xeO1bc/d6ZTy32DHchpW 6rDH1vp86Ll+ha0tmwyy9QP7y2bVw5zSbFCrefk8qCUBgfHm9bHzMG1U BYtEIQ==" # trust-anchor: "jelte.nlnetlabs.nl. DS 42860 5 1 14D739EB566D2B1A5E216A0BA4D17FA9B038BE4A" # File with trusted keys for validation. Specify more than one file # with several entries, one file per entry. Like trust-anchor-file # but has a different file format. Format is BIND-9 style format, # the trusted-keys { name flag proto algo "key"; }; clauses are read. # you need external update procedures to track changes in keys. # trusted-keys-file: "" # Ignore chain of trust. Domain is treated as insecure. # domain-insecure: "example.com" # Override the date for validation with a specific fixed date. # Do not set this unless you are debugging signature inception # and expiration. "" or "0" turns the feature off. -1 ignores date. # val-override-date: "" # The time to live for bogus data, rrsets and messages. This avoids # some of the revalidation, until the time interval expires. in secs. # val-bogus-ttl: 60 # The signature inception and expiration dates are allowed to be off # by 10% of the signature lifetime (expir-incep) from our local clock. # This leeway is capped with a minimum and a maximum. In seconds. # val-sig-skew-min: 3600 # val-sig-skew-max: 86400 + # The maximum number the validator should restart validation with + # another authority in case of failed validation. + # val-max-restart: 5 + # Should additional section of secure message also be kept clean of # unsecure data. Useful to shield the users of this validator from # potential bogus data in the additional section. All unsigned data # in the additional section is removed from secure messages. # val-clean-additional: yes # Turn permissive mode on to permit bogus messages. Thus, messages # for which security checks failed will be returned to clients, # instead of SERVFAIL. It still performs the security checks, which # result in interesting log files and possibly the AD bit in # replies if the message is found secure. The default is off. # val-permissive-mode: no # Ignore the CD flag in incoming queries and refuse them bogus data. # Enable it if the only clients of unbound are legacy servers (w2008) # that set CD but cannot validate themselves. # ignore-cd-flag: no - # Serve expired responses from cache, with TTL 0 in the response, - # and then attempt to fetch the data afresh. + # Serve expired responses from cache, with serve-expired-reply-ttl in + # the response, and then attempt to fetch the data afresh. # serve-expired: no # # Limit serving of expired responses to configured seconds after # expiration. 0 disables the limit. # serve-expired-ttl: 0 # # Set the TTL of expired records to the serve-expired-ttl value after a # failed attempt to retrieve the record from upstream. This makes sure # that the expired records will be served as long as there are queries # for it. # serve-expired-ttl-reset: no + # + # TTL value to use when replying with expired data. + # serve-expired-reply-ttl: 30 + # + # Time in milliseconds before replying to the client with expired data. + # This essentially enables the serve-stale behavior as specified in + # RFC 8767 that first tries to resolve before + # immediately responding with expired data. 0 disables this behavior. + # A recommended value is 1800. + # serve-expired-client-timeout: 0 + + # Return the original TTL as received from the upstream name server rather + # than the decrementing TTL as stored in the cache. Enabling this feature + # does not impact cache expiry, it only changes the TTL unbound embeds in + # responses to queries. Note that enabling this feature implicitly disables + # enforcement of the configured minimum and maximum TTL. + # serve-original-ttl: no # Have the validator log failed validations for your diagnosis. # 0: off. 1: A line per failed user query. 2: With reason and bad IP. # val-log-level: 0 # It is possible to configure NSEC3 maximum iteration counts per # keysize. Keep this table very short, as linear search is done. # A message with an NSEC3 with larger count is marked insecure. # List in ascending order the keysize and count values. - # val-nsec3-keysize-iterations: "1024 150 2048 500 4096 2500" + # val-nsec3-keysize-iterations: "1024 150 2048 150 4096 150" + + # if enabled, ZONEMD verification failures do not block the zone. + # zonemd-permissive-mode: no # instruct the auto-trust-anchor-file probing to add anchors after ttl. # add-holddown: 2592000 # 30 days # instruct the auto-trust-anchor-file probing to del anchors after ttl. # del-holddown: 2592000 # 30 days # auto-trust-anchor-file probing removes missing anchors after ttl. # If the value 0 is given, missing anchors are not removed. # keep-missing: 31622400 # 366 days # debug option that allows very small holddown times for key rollover, # otherwise the RFC mandates probe intervals must be at least 1 hour. # permit-small-holddown: no # the amount of memory to use for the key cache. # plain value in bytes or you can append k, m or G. default is "4Mb". # key-cache-size: 4m # the number of slabs to use for the key cache. # the number of slabs must be a power of 2. # more slabs reduce lock contention, but fragment memory usage. # key-cache-slabs: 4 - # the amount of memory to use for the negative cache (used for DLV). + # the amount of memory to use for the negative cache. # plain value in bytes or you can append k, m or G. default is "1Mb". # neg-cache-size: 1m # By default, for a number of zones a small default 'nothing here' # reply is built-in. Query traffic is thus blocked. If you # wish to serve such zone you can unblock them by uncommenting one # of the nodefault statements below. # You may also have to use domain-insecure: zone to make DNSSEC work, # unless you have your own trust anchors for this zone. # local-zone: "localhost." nodefault # local-zone: "127.in-addr.arpa." nodefault # local-zone: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." nodefault + # local-zone: "home.arpa." nodefault # local-zone: "onion." nodefault # local-zone: "test." nodefault # local-zone: "invalid." nodefault # local-zone: "10.in-addr.arpa." nodefault # local-zone: "16.172.in-addr.arpa." nodefault # local-zone: "17.172.in-addr.arpa." nodefault # local-zone: "18.172.in-addr.arpa." nodefault # local-zone: "19.172.in-addr.arpa." nodefault # local-zone: "20.172.in-addr.arpa." nodefault # local-zone: "21.172.in-addr.arpa." nodefault # local-zone: "22.172.in-addr.arpa." nodefault # local-zone: "23.172.in-addr.arpa." nodefault # local-zone: "24.172.in-addr.arpa." nodefault # local-zone: "25.172.in-addr.arpa." nodefault # local-zone: "26.172.in-addr.arpa." nodefault # local-zone: "27.172.in-addr.arpa." nodefault # local-zone: "28.172.in-addr.arpa." nodefault # local-zone: "29.172.in-addr.arpa." nodefault # local-zone: "30.172.in-addr.arpa." nodefault # local-zone: "31.172.in-addr.arpa." nodefault # local-zone: "168.192.in-addr.arpa." nodefault # local-zone: "0.in-addr.arpa." nodefault # local-zone: "254.169.in-addr.arpa." nodefault # local-zone: "2.0.192.in-addr.arpa." nodefault # local-zone: "100.51.198.in-addr.arpa." nodefault # local-zone: "113.0.203.in-addr.arpa." nodefault # local-zone: "255.255.255.255.in-addr.arpa." nodefault # local-zone: "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." nodefault # local-zone: "d.f.ip6.arpa." nodefault # local-zone: "8.e.f.ip6.arpa." nodefault # local-zone: "9.e.f.ip6.arpa." nodefault # local-zone: "a.e.f.ip6.arpa." nodefault # local-zone: "b.e.f.ip6.arpa." nodefault # local-zone: "8.b.d.0.1.0.0.2.ip6.arpa." nodefault # And for 64.100.in-addr.arpa. to 127.100.in-addr.arpa. + # Add example.com into ipset + # local-zone: "example.com" ipset + # If unbound is running service for the local host then it is useful # to perform lan-wide lookups to the upstream, and unblock the # long list of local-zones above. If this unbound is a dns server # for a network of computers, disabled is better and stops information # leakage of local lan information. # unblock-lan-zones: no # The insecure-lan-zones option disables validation for # these zones, as if they were all listed as domain-insecure. # insecure-lan-zones: no # a number of locally served zones can be configured. # local-zone: # local-data: "" # o deny serves local data (if any), else, drops queries. # o refuse serves local data (if any), else, replies with error. # o static serves local data, else, nxdomain or nodata answer. # o transparent gives local data, but resolves normally for other names # o redirect serves the zone data for any subdomain in the zone. # o nodefault can be used to normally resolve AS112 zones. # o typetransparent resolves normally for other types and other names # o inform acts like transparent, but logs client IP address # o inform_deny drops queries and logs client IP address # o inform_redirect redirects queries and logs client IP address - # o always_transparent, always_refuse, always_nxdomain, resolve in - # that way but ignore local data for that name + # o always_transparent, always_refuse, always_nxdomain, always_nodata, + # always_deny resolve in that way but ignore local data for + # that name + # o always_null returns 0.0.0.0 or ::0 for any name in the zone. # o noview breaks out of that view towards global local-zones. # # defaults are localhost address, reverse for 127.0.0.1 and ::1 # and nxdomain for AS112 zones. If you configure one of these zones # the default content is omitted, or you can omit it with 'nodefault'. # # If you configure local-data without specifying local-zone, by # default a transparent local-zone is created for the data. # # You can add locally served data with # local-zone: "local." static # local-data: "mycomputer.local. IN A 192.0.2.51" # local-data: 'mytext.local TXT "content of text record"' # # You can override certain queries with # local-data: "adserver.example.com A 127.0.0.1" # # You can redirect a domain to a fixed address with # (this makes example.com, www.example.com, etc, all go to 192.0.2.3) # local-zone: "example.com" redirect # local-data: "example.com A 192.0.2.3" # # Shorthand to make PTR records, "IPv4 name" or "IPv6 name". # You can also add PTR records using local-data directly, but then # you need to do the reverse notation yourself. # local-data-ptr: "192.0.2.3 www.example.com" # tag a localzone with a list of tag names (in "" with spaces between) # local-zone-tag: "example.com" "tag2 tag3" # add a netblock specific override to a localzone, with zone type # local-zone-override: "example.com" 192.0.2.0/24 refuse - # service clients over TLS (on the TCP sockets), with plain DNS inside - # the TLS stream. Give the certificate to use and private key. + # service clients over TLS (on the TCP sockets) with plain DNS inside + # the TLS stream, and over HTTPS using HTTP/2 as specified in RFC8484. + # Give the certificate to use and private key. # default is "" (disabled). requires restart to take effect. # tls-service-key: "path/to/privatekeyfile.key" # tls-service-pem: "path/to/publiccertfile.pem" # tls-port: 853 + # https-port: 443 # cipher setting for TLSv1.2 # tls-ciphers: "DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256" # cipher setting for TLSv1.3 # tls-ciphersuites: "TLS_AES_128_GCM_SHA256:TLS_AES_128_CCM_8_SHA256:TLS_AES_128_CCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256" + # Pad responses to padded queries received over TLS + # pad-responses: yes + + # Padded responses will be padded to the closest multiple of this size. + # pad-responses-block-size: 468 + + # Use the SNI extension for TLS connections. Default is yes. + # Changing the value requires a reload. + # tls-use-sni: yes + # Add the secret file for TLS Session Ticket. # Secret file must be 80 bytes of random data. # First key use to encrypt and decrypt TLS session tickets. # Other keys use to decrypt only. # requires restart to take effect. # tls-session-ticket-keys: "path/to/secret_file1" # tls-session-ticket-keys: "path/to/secret_file2" # request upstream over TLS (with plain DNS inside the TLS stream). # Default is no. Can be turned on and off with unbound-control. # tls-upstream: no # Certificates used to authenticate connections made upstream. # tls-cert-bundle: "" # Add system certs to the cert bundle, from the Windows Cert Store # tls-win-cert: no + # Pad queries over TLS upstreams + # pad-queries: yes + + # Padded queries will be padded to the closest multiple of this size. + # pad-queries-block-size: 128 + # Also serve tls on these port numbers (eg. 443, ...), by listing # tls-additional-port: portno for each of the port numbers. + # HTTP endpoint to provide DNS-over-HTTPS service on. + # http-endpoint: "/dns-query" + + # HTTP/2 SETTINGS_MAX_CONCURRENT_STREAMS value to use. + # http-max-streams: 100 + + # Maximum number of bytes used for all HTTP/2 query buffers. + # http-query-buffer-size: 4m + + # Maximum number of bytes used for all HTTP/2 response buffers. + # http-response-buffer-size: 4m + + # Set TCP_NODELAY socket option on sockets used for DNS-over-HTTPS + # service. + # http-nodelay: yes + + # Disable TLS for DNS-over-HTTP downstream service. + # http-notls-downstream: no + # DNS64 prefix. Must be specified when DNS64 is use. # Enable dns64 in module-config. Used to synthesize IPv6 from IPv4. # dns64-prefix: 64:ff9b::0/96 # DNS64 ignore AAAA records for these domains and use A instead. # dns64-ignore-aaaa: "example.com" # ratelimit for uncached, new queries, this limits recursion effort. # ratelimiting is experimental, and may help against randomqueryflood. # if 0(default) it is disabled, otherwise state qps allowed per zone. # ratelimit: 0 # ratelimits are tracked in a cache, size in bytes of cache (or k,m). # ratelimit-size: 4m # ratelimit cache slabs, reduces lock contention if equal to cpucount. # ratelimit-slabs: 4 # 0 blocks when ratelimited, otherwise let 1/xth traffic through # ratelimit-factor: 10 # override the ratelimit for a specific domain name. # give this setting multiple times to have multiple overrides. # ratelimit-for-domain: example.com 1000 # override the ratelimits for all domains below a domain name # can give this multiple times, the name closest to the zone is used. # ratelimit-below-domain: com 1000 # global query ratelimit for all ip addresses. # feature is experimental. # if 0(default) it is disabled, otherwise states qps allowed per ip address # ip-ratelimit: 0 # ip ratelimits are tracked in a cache, size in bytes of cache (or k,m). # ip-ratelimit-size: 4m # ip ratelimit cache slabs, reduces lock contention if equal to cpucount. # ip-ratelimit-slabs: 4 # 0 blocks when ip is ratelimited, otherwise let 1/xth traffic through # ip-ratelimit-factor: 10 # Limit the number of connections simultaneous from a netblock # tcp-connection-limit: 192.0.2.0/24 12 # select from the fastest servers this many times out of 1000. 0 means # the fast server select is disabled. prefetches are not sped up. # fast-server-permil: 0 # the number of servers that will be used in the fast server selection. # fast-server-num: 3 # Specific options for ipsecmod. unbound needs to be configured with # --enable-ipsecmod for these to take effect. # # Enable or disable ipsecmod (it still needs to be defined in # module-config above). Can be used when ipsecmod needs to be # enabled/disabled via remote-control(below). # ipsecmod-enabled: yes # # Path to executable external hook. It must be defined when ipsecmod is # listed in module-config (above). # ipsecmod-hook: "./my_executable" # # When enabled unbound will reply with SERVFAIL if the return value of # the ipsecmod-hook is not 0. # ipsecmod-strict: no # # Maximum time to live (TTL) for cached A/AAAA records with IPSECKEY. # ipsecmod-max-ttl: 3600 # # Reply with A/AAAA even if the relevant IPSECKEY is bogus. Mainly used for # testing. # ipsecmod-ignore-bogus: no # # Domains for which ipsecmod will be triggered. If not defined (default) - # all domains are treated as being whitelisted. - # ipsecmod-whitelist: "example.com" - # ipsecmod-whitelist: "nlnetlabs.nl" + # all domains are treated as being allowed. + # ipsecmod-allow: "example.com" + # ipsecmod-allow: "nlnetlabs.nl" + + # Timeout for REUSE entries in milliseconds. + # tcp-reuse-timeout: 60000 + # Max number of queries on a reuse connection. + # max-reuse-tcp-queries: 200 + # Timeout in milliseconds for TCP queries to auth servers. + # tcp-auth-query-timeout: 3000 # Python config section. To enable: # o use --with-pythonmodule to configure before compiling. # o list python in the module-config string (above) to enable. # It can be at the start, it gets validated results, or just before # the iterator and process before DNSSEC validation. # o and give a python-script to run. python: # Script file to load - # python-script: "/var/unbound/ubmodule-tst.py" + # python-script: "@UNBOUND_SHARE_DIR@/ubmodule-tst.py" + +# Dynamic library config section. To enable: +# o use --with-dynlibmodule to configure before compiling. +# o list dynlib in the module-config string (above) to enable. +# It can be placed anywhere, the dynlib module is only a very thin wrapper +# to load modules dynamically. +# o and give a dynlib-file to run. If more than one dynlib entry is listed in +# the module-config then you need one dynlib-file per instance. +dynlib: + # Script file to load + # dynlib-file: "@UNBOUND_SHARE_DIR@/dynlib.so" # Remote control config section. remote-control: # Enable remote control with unbound-control(8) here. # set up the keys and certificates with unbound-control-setup. # control-enable: no # what interfaces are listened to for remote control. # give 0.0.0.0 and ::0 to listen to all interfaces. # set to an absolute path to use a unix local name pipe, certificates # are not used for that, so key and cert files need not be present. # control-interface: 127.0.0.1 # control-interface: ::1 # port number for remote control operations. # control-port: 8953 # for localhost, you can disable use of TLS by setting this to "no" # For local sockets this option is ignored, and TLS is not used. # control-use-cert: "yes" # unbound server key file. - # server-key-file: "/var/unbound/unbound_server.key" + # server-key-file: "@UNBOUND_RUN_DIR@/unbound_server.key" # unbound server certificate file. - # server-cert-file: "/var/unbound/unbound_server.pem" + # server-cert-file: "@UNBOUND_RUN_DIR@/unbound_server.pem" # unbound-control key file. - # control-key-file: "/var/unbound/unbound_control.key" + # control-key-file: "@UNBOUND_RUN_DIR@/unbound_control.key" # unbound-control certificate file. - # control-cert-file: "/var/unbound/unbound_control.pem" + # control-cert-file: "@UNBOUND_RUN_DIR@/unbound_control.pem" # Stub zones. # Create entries like below, to make all queries for 'example.com' and # 'example.org' go to the given list of nameservers. list zero or more # nameservers by hostname or by ipaddress. If you set stub-prime to yes, # the list is treated as priming hints (default is no). # With stub-first yes, it attempts without the stub if it fails. # Consider adding domain-insecure: name and local-zone: name nodefault # to the server: section if the stub is a locally served zone. # stub-zone: # name: "example.com" # stub-addr: 192.0.2.68 # stub-prime: no # stub-first: no +# stub-tcp-upstream: no # stub-tls-upstream: no # stub-no-cache: no # stub-zone: # name: "example.org" # stub-host: ns.example.com. # Forward zones # Create entries like below, to make all queries for 'example.com' and # 'example.org' go to the given list of servers. These servers have to handle # recursion to other nameservers. List zero or more nameservers by hostname # or by ipaddress. Use an entry with name "." to forward all queries. # If you enable forward-first, it attempts without the forward if it fails. # forward-zone: # name: "example.com" # forward-addr: 192.0.2.68 # forward-addr: 192.0.2.73@5355 # forward to port 5355. # forward-first: no +# forward-tcp-upstream: no # forward-tls-upstream: no # forward-no-cache: no # forward-zone: # name: "example.org" # forward-host: fwd.example.com # Authority zones # The data for these zones is kept locally, from a file or downloaded. # The data can be served to downstream clients, or used instead of the # upstream (which saves a lookup to the upstream). The first example # has a copy of the root for local usage. The second serves example.org # authoritatively. zonefile: reads from file (and writes to it if you also -# download it), master: fetches with AXFR and IXFR, or url to zonefile. -# With allow-notify: you can give additional (apart from masters) sources of +# download it), primary: fetches with AXFR and IXFR, or url to zonefile. +# With allow-notify: you can give additional (apart from primaries) sources of # notifies. # auth-zone: # name: "." -# master: 199.9.14.201 # b.root-servers.net -# master: 192.33.4.12 # c.root-servers.net -# master: 199.7.91.13 # d.root-servers.net -# master: 192.5.5.241 # f.root-servers.net -# master: 192.112.36.4 # g.root-servers.net -# master: 193.0.14.129 # k.root-servers.net -# master: 192.0.47.132 # xfr.cjr.dns.icann.org -# master: 192.0.32.132 # xfr.lax.dns.icann.org -# master: 2001:500:200::b # b.root-servers.net -# master: 2001:500:2::c # c.root-servers.net -# master: 2001:500:2d::d # d.root-servers.net -# master: 2001:500:2f::f # f.root-servers.net -# master: 2001:500:12::d0d # g.root-servers.net -# master: 2001:7fd::1 # k.root-servers.net -# master: 2620:0:2830:202::132 # xfr.cjr.dns.icann.org -# master: 2620:0:2d0:202::132 # xfr.lax.dns.icann.org +# primary: 199.9.14.201 # b.root-servers.net +# primary: 192.33.4.12 # c.root-servers.net +# primary: 199.7.91.13 # d.root-servers.net +# primary: 192.5.5.241 # f.root-servers.net +# primary: 192.112.36.4 # g.root-servers.net +# primary: 193.0.14.129 # k.root-servers.net +# primary: 192.0.47.132 # xfr.cjr.dns.icann.org +# primary: 192.0.32.132 # xfr.lax.dns.icann.org +# primary: 2001:500:200::b # b.root-servers.net +# primary: 2001:500:2::c # c.root-servers.net +# primary: 2001:500:2d::d # d.root-servers.net +# primary: 2001:500:2f::f # f.root-servers.net +# primary: 2001:500:12::d0d # g.root-servers.net +# primary: 2001:7fd::1 # k.root-servers.net +# primary: 2620:0:2830:202::132 # xfr.cjr.dns.icann.org +# primary: 2620:0:2d0:202::132 # xfr.lax.dns.icann.org # fallback-enabled: yes # for-downstream: no # for-upstream: yes # auth-zone: # name: "example.org" # for-downstream: yes # for-upstream: yes +# zonemd-check: no +# zonemd-reject-absence: no # zonefile: "example.org.zone" # Views # Create named views. Name must be unique. Map views to requests using # the access-control-view option. Views can contain zero or more local-zone # and local-data options. Options from matching views will override global # options. Global options will be used if no matching view is found. # With view-first yes, it will try to answer using the global local-zone and # local-data elements if there is no view specific match. # view: # name: "viewname" # local-zone: "example.com" redirect # local-data: "example.com A 192.0.2.3" # local-data-ptr: "192.0.2.3 www.example.com" # view-first: no # view: # name: "anotherview" # local-zone: "example.com" refuse # DNSCrypt # Caveats: # 1. the keys/certs cannot be produced by unbound. You can use dnscrypt-wrapper # for this: https://github.com/cofyc/dnscrypt-wrapper/blob/master/README.md#usage # 2. dnscrypt channel attaches to an interface. you MUST set interfaces to # listen on `dnscrypt-port` with the follo0wing snippet: # server: # interface: 0.0.0.0@443 # interface: ::0@443 # # Finally, `dnscrypt` config has its own section. # dnscrypt: # dnscrypt-enable: yes # dnscrypt-port: 443 # dnscrypt-provider: 2.dnscrypt-cert.example.com. # dnscrypt-secret-key: /path/unbound-conf/keys1/1.key # dnscrypt-secret-key: /path/unbound-conf/keys2/1.key # dnscrypt-provider-cert: /path/unbound-conf/keys1/1.cert # dnscrypt-provider-cert: /path/unbound-conf/keys2/1.cert # CacheDB # Enable external backend DB as auxiliary cache. Specify the backend name # (default is "testframe", which has no use other than for debugging and # testing) and backend-specific options. The 'cachedb' module must be # included in module-config, just before the iterator module. # cachedb: # backend: "testframe" # # secret seed string to calculate hashed keys # secret-seed: "default" # # # For "redis" backend: # # redis server's IP address or host name # redis-server-host: 127.0.0.1 # # redis server's TCP port # redis-server-port: 6379 # # timeout (in ms) for communication with the redis server # redis-timeout: 100 +# # set timeout on redis records based on DNS response TTL +# redis-expire-records: no + +# IPSet +# Add specify domain into set via ipset. +# Note: To enable ipset unbound needs to run as root user. +# ipset: +# # set name for ip v4 addresses +# name-v4: "list-v4" +# # set name for ip v6 addresses +# name-v6: "list-v6" +# + +# Dnstap logging support, if compiled in. To enable, set the dnstap-enable +# to yes and also some of dnstap-log-..-messages to yes. And select an +# upstream log destination, by socket path, TCP or TLS destination. +# dnstap: +# dnstap-enable: no +# # if set to yes frame streams will be used in bidirectional mode +# dnstap-bidirectional: yes +# dnstap-socket-path: "@DNSTAP_SOCKET_PATH@" +# # if "" use the unix socket in dnstap-socket-path, otherwise, +# # set it to "IPaddress[@port]" of the destination. +# dnstap-ip: "" +# # if set to yes if you want to use TLS to dnstap-ip, no for TCP. +# dnstap-tls: yes +# # name for authenticating the upstream server. or "" disabled. +# dnstap-tls-server-name: "" +# # if "", it uses the cert bundle from the main unbound config. +# dnstap-tls-cert-bundle: "" +# # key file for client authentication, or "" disabled. +# dnstap-tls-client-key-file: "" +# # cert file for client authentication, or "" disabled. +# dnstap-tls-client-cert-file: "" +# dnstap-send-identity: no +# dnstap-send-version: no +# # if "" it uses the hostname. +# dnstap-identity: "" +# # if "" it uses the package version. +# dnstap-version: "" +# dnstap-log-resolver-query-messages: no +# dnstap-log-resolver-response-messages: no +# dnstap-log-client-query-messages: no +# dnstap-log-client-response-messages: no +# dnstap-log-forwarder-query-messages: no +# dnstap-log-forwarder-response-messages: no + +# Response Policy Zones +# RPZ policies. Applied in order of configuration. QNAME, Response IP +# Address, nsdname, nsip and clientip triggers are supported. Supported +# actions are: NXDOMAIN, NODATA, PASSTHRU, DROP, Local Data, tcp-only +# and drop. Policies can be loaded from a file, or using zone +# transfer, or using HTTP. The respip module needs to be added +# to the module-config, e.g.: module-config: "respip validator iterator". +# rpz: +# name: "rpz.example.com" +# zonefile: "rpz.example.com" +# primary: 192.0.2.0 +# allow-notify: 192.0.2.0/32 +# url: http://www.example.com/rpz.example.org.zone +# rpz-action-override: cname +# rpz-cname-override: www.example.org +# rpz-log: yes +# rpz-log-name: "example policy" +# tags: "example" diff --git a/contrib/unbound/doc/libunbound.3 b/contrib/unbound/doc/libunbound.3 index fd5c336e0903..6c5217aa04c4 100644 --- a/contrib/unbound/doc/libunbound.3 +++ b/contrib/unbound/doc/libunbound.3 @@ -1,433 +1,434 @@ -.TH "libunbound" "3" "Jun 17, 2019" "NLnet Labs" "unbound 1.9.2" +.TH "libunbound" "3" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" .\" .\" libunbound.3 -- unbound library functions manual .\" .\" Copyright (c) 2007, NLnet Labs. All rights reserved. .\" .\" See LICENSE for the license. .\" .\" .SH "NAME" .B libunbound, .B unbound.h, .B ub_ctx, .B ub_result, .B ub_callback_type, .B ub_ctx_create, .B ub_ctx_delete, .B ub_ctx_set_option, .B ub_ctx_get_option, .B ub_ctx_config, .B ub_ctx_set_fwd, .B ub_ctx_set_stub, .B ub_ctx_set_tls, .B ub_ctx_resolvconf, .B ub_ctx_hosts, .B ub_ctx_add_ta, .B ub_ctx_add_ta_autr, .B ub_ctx_add_ta_file, .B ub_ctx_trustedkeys, .B ub_ctx_debugout, .B ub_ctx_debuglevel, .B ub_ctx_async, .B ub_poll, .B ub_wait, .B ub_fd, .B ub_process, .B ub_resolve, .B ub_resolve_async, .B ub_cancel, .B ub_resolve_free, .B ub_strerror, .B ub_ctx_print_local_zones, .B ub_ctx_zone_add, .B ub_ctx_zone_remove, .B ub_ctx_data_add, .B ub_ctx_data_remove -\- Unbound DNS validating resolver 1.9.2 functions. +\- Unbound DNS validating resolver 1.14.0 functions. .SH "SYNOPSIS" .B #include .LP \fIstruct ub_ctx *\fR \fBub_ctx_create\fR(\fIvoid\fR); .LP \fIvoid\fR \fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx); .LP \fIint\fR \fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val); .LP \fIint\fR \fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val); .LP \fIint\fR \fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); .LP \fIint\fR \fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr); .LP \fIint\fR \fBub_ctx_set_stub\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone, \fIchar*\fR addr, .br \fIint\fR isprime); .LP \fIint\fR \fBub_ctx_set_tls\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR tls); .LP \fIint\fR \fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); .LP \fIint\fR \fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); .LP \fIint\fR \fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta); .LP \fIint\fR \fBub_ctx_add_ta_autr\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); .LP \fIint\fR \fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); .LP \fIint\fR \fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); .LP \fIint\fR \fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out); .LP \fIint\fR \fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d); .LP \fIint\fR \fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread); .LP \fIint\fR \fBub_poll\fR(\fIstruct ub_ctx*\fR ctx); .LP \fIint\fR \fBub_wait\fR(\fIstruct ub_ctx*\fR ctx); .LP \fIint\fR \fBub_fd\fR(\fIstruct ub_ctx*\fR ctx); .LP \fIint\fR \fBub_process\fR(\fIstruct ub_ctx*\fR ctx); .LP \fIint\fR \fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name, .br \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result); .LP \fIint\fR \fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name, .br \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata, .br \fIub_callback_type\fR callback, \fIint*\fR async_id); .LP \fIint\fR \fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id); .LP \fIvoid\fR \fBub_resolve_free\fR(\fIstruct ub_result*\fR result); .LP \fIconst char *\fR \fBub_strerror\fR(\fIint\fR err); .LP \fIint\fR \fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx); .LP \fIint\fR \fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type); .LP \fIint\fR \fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name); .LP \fIint\fR \fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); .LP \fIint\fR \fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); .SH "DESCRIPTION" .B 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 \fIunbound\fR(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. .P The library uses a variable of type \fIstruct ub_ctx\fR to keep context between calls. The user must maintain it, creating it with .B ub_ctx_create and deleting it with .B ub_ctx_delete\fR. 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. .P 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. .P The functions are discussed in turn below. .SH "FUNCTIONS" .TP .B ub_ctx_create Create a new context, initialised with defaults. The information from /etc/resolv.conf and /etc/hosts is not utilised by default. Use .B ub_ctx_resolvconf and .B 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. .TP .B ub_ctx_delete Delete validation context and free associated resources. Outstanding async queries are killed and callbacks are not called for them. .TP .B ub_ctx_set_option A power\-user interface that lets you specify one of the options from the config file format, see \fIunbound.conf\fR(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 ':'. .TP .B 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. .TP .B ub_ctx_config A power\-user interface that lets you specify an unbound config file, see \fIunbound.conf\fR(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. .TP .B 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. .TP .B 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. .TP .B ub_ctx_set_tls Enable DNS over TLS (DoT) for machines set with .B ub_ctx_set_fwd. At this time it is only possible to set configuration before the first resolve is done. .TP .B 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 "/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 \fIresolv.conf\fR(5) are ignored. If fname NULL is passed, "/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. .TP .B ub_ctx_hosts Read list of hosts from the filename given. Usually "/etc/hosts". When queried for, these addresses are not marked DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used (if on Windows, etc/hosts from WINDIR is picked instead). At this time it is only possible to set configuration before the first resolve is done. .TP .B 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. .TP .B 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 \fIunbound\-anchor\fR(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. .TP .B 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. .TP .B 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. .TP .B 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. .TP .B ub_ctx_debuglevel Set debug verbosity for the context. Output is directed to stderr. Higher debug level gives more output. .TP .B ub_ctx_async Set a context behaviour for asynchronous action. if set to true, enables threading and a call to .B 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 .B ub_resolve_async calls have been made have no effect (delete and re\-create the context to change). .TP .B 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 .B ub_process to do callbacks. .TP .B ub_wait Wait for a context to finish with results. Calls .B ub_process after the wait for you. After the wait, there are no more outstanding asynchronous queries. .TP .B 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 \fBub_process\fR to continue processing. .TP .B ub_process Call this routine to continue processing results from the validating resolver (when the fd becomes readable). Will perform necessary callbacks. .TP .B 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. .TP .B ub_resolve_async Perform asynchronous resolution and validation of the target name. Arguments mean the same as for \fBub_resolve\fR 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 .IP void my_callback_function(void* my_arg, int err, .br struct ub_result* result); .IP 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. .TP .B 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. .TP .B ub_resolve_free Free struct ub_result contents after use. .TP .B ub_strerror Convert error value from one of the unbound library functions to a human readable string. .TP .B ub_ctx_print_local_zones Debug printout the local authority information to debug output. .TP .B ub_ctx_zone_add Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5) statement. .TP .B ub_ctx_zone_remove Delete zone from local authority info. .TP .B ub_ctx_data_add Add resource record data to local authority info, like local\-data \fIunbound.conf\fR(5) statement. .TP .B ub_ctx_data_remove Delete local authority data from the name given. .SH "RESULT DATA STRUCTURE" The result of the DNS resolution and validation is returned as \fIstruct ub_result\fR. The result structure contains the following entries. .P .nf 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 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 */ + 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 */ }; .fi .P 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. .SH "RETURN VALUES" Many routines return an error code. The value 0 (zero) denotes no error happened. Other values can be passed to .B ub_strerror to obtain a readable error string. .B ub_strerror returns a zero terminated string. .B ub_ctx_create returns NULL on an error (a malloc failure). .B ub_poll returns true if some information may be available, false otherwise. .B ub_fd returns a file descriptor or \-1 on error. .B ub_ctx_config and .B ub_ctx_resolvconf attempt to leave errno informative on a function return with file read failure. .SH "SEE ALSO" \fIunbound.conf\fR(5), \fIunbound\fR(8). .SH "AUTHORS" .B Unbound developers are mentioned in the CREDITS file in the distribution. diff --git a/contrib/unbound/doc/unbound-anchor.8 b/contrib/unbound/doc/unbound-anchor.8 index 60759eb19f4f..ddab3d27f120 100644 --- a/contrib/unbound/doc/unbound-anchor.8 +++ b/contrib/unbound/doc/unbound-anchor.8 @@ -1,182 +1,189 @@ -.TH "unbound-anchor" "8" "Jun 17, 2019" "NLnet Labs" "unbound 1.9.2" +.TH "unbound-anchor" "8" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" .\" .\" unbound-anchor.8 -- unbound anchor maintenance utility manual .\" .\" Copyright (c) 2008, NLnet Labs. All rights reserved. .\" .\" See LICENSE for the license. .\" .\" .SH "NAME" .B unbound\-anchor \- Unbound anchor utility. .SH "SYNOPSIS" .B unbound\-anchor .RB [ opts ] .SH "DESCRIPTION" .B Unbound\-anchor performs setup or update of the root trust anchor for DNSSEC validation. The program fetches the trust anchor with the method from RFC7958 when regular RFC5011 update fails to bring it up to date. It can be run (as root) from the commandline, or run as part of startup scripts. Before you start the \fIunbound\fR(8) DNS server. .P Suggested usage: .P .nf # in the init scripts. # provide or update the root anchor (if necessary) - unbound-anchor \-a "/var/unbound/root.key" + 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: "/var/unbound/root.key" + # auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@" unbound \-c unbound.conf .fi .P This tool provides builtin default contents for the root anchor and root update certificate files. .P 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 (RFC7958), if all checks are successful, it updates the root anchor file. Otherwise the root anchor file is unchanged. It performs RFC5011 tracking if the DNSSEC information available via the DNS makes that possible. .P It does not perform an update if the certificate is expired, if the network is down or other errors occur. .P The available options are: .TP .B \-a \fIfile The root anchor key file, that is read in and written out. -Default is /var/unbound/root.key. +Default is @UNBOUND_ROOTKEY_FILE@. If the file does not exist, or is empty, a builtin root key is written to it. .TP .B \-c \fIfile The root update certificate file, that is read in. -Default is /var/unbound/icannbundle.pem. +Default is @UNBOUND_ROOTCERT_FILE@. If the file does not exist, or is empty, a builtin certificate is used. .TP .B \-l List the builtin root key and builtin root update certificate on stdout. .TP .B \-u \fIname 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 \-P. You can pass an IPv4 address or IPv6 address (no brackets) if you want. .TP +.B \-S +Do not use SNI for the HTTPS connection. Default is to use SNI. +.TP +.B \-b \fIaddress +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). +.TP .B \-x \fIpath The pathname to the root\-anchors.xml file on the server. (forms URL with \-u). The default is /root\-anchors/root\-anchors.xml. .TP .B \-s \fIpath The pathname to the root\-anchors.p7s file on the server. (forms URL with \-u). The default is /root\-anchors/root\-anchors.p7s. This file has to be a PKCS7 signature over the xml file, using the pem file (\-c) as trust anchor. .TP .B \-n \fIname The emailAddress for the Subject of the signer's certificate from the p7s signature file. Only signatures from this name are allowed. default is dnssec@iana.org. If you pass "" then the emailAddress is not checked. .TP .B \-4 Use IPv4 for domain resolution and contacting the server on https. Default is to use IPv4 and IPv6 where appropriate. .TP .B \-6 Use IPv6 for domain resolution and contacting the server on https. Default is to use IPv4 and IPv6 where appropriate. .TP .B \-f \fIresolv.conf Use the given resolv.conf file. Not enabled by default, but you could try to pass /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. .TP .B \-r \fIroot.hints 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 (\-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. .TP .B \-R Allow fallback from \-f resolv.conf 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. .TP .B \-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. .TP .B \-C \fIunbound.conf Debug option to read unbound.conf into the resolver process used. .TP .B \-P \fIport Set the port number to use for the https connection. The default is 443. .TP .B \-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. .TP .B \-h Show the version and commandline option help. .SH "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 RFC5011 tracking, or if an error occurred. .P You can check the exit value in this manner: .nf unbound-anchor \-a "root.key" || logger "Please check root.key" .fi Or something more suitable for your operational environment. .SH "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 http://unbound.nlnetlabs.nl/svn/trunk/LICENSE) and might be stale or not suitable to your purpose. .P By running "unbound\-anchor \-l" the keys and certificate that are configured in the code are printed for your convenience. .P The build\-in configuration can be overridden by providing a root\-cert file and a rootkey file. .SH "FILES" .TP -.I /var/unbound/root.key +.I @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. .TP -.I /var/unbound/icannbundle.pem +.I @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. .TP .I https://data.iana.org/root\-anchors/root\-anchors.xml Source for the root key information. .TP .I https://data.iana.org/root\-anchors/root\-anchors.p7s Signature on the root key information. .SH "SEE ALSO" \fIunbound.conf\fR(5), \fIunbound\fR(8). diff --git a/contrib/unbound/doc/unbound-checkconf.8 b/contrib/unbound/doc/unbound-checkconf.8 index affb2996bdf7..bd1ab8ad696d 100644 --- a/contrib/unbound/doc/unbound-checkconf.8 +++ b/contrib/unbound/doc/unbound-checkconf.8 @@ -1,52 +1,52 @@ -.TH "unbound-checkconf" "8" "Jun 17, 2019" "NLnet Labs" "unbound 1.9.2" +.TH "unbound-checkconf" "8" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" .\" .\" unbound-checkconf.8 -- unbound configuration checker manual .\" .\" Copyright (c) 2007, NLnet Labs. All rights reserved. .\" .\" See LICENSE for the license. .\" .\" .SH "NAME" .B unbound\-checkconf \- Check unbound configuration file for errors. .SH "SYNOPSIS" .B unbound\-checkconf .RB [ \-h ] .RB [ \-f ] .RB [ \-o .IR option ] .RI [ cfgfile ] .SH "DESCRIPTION" .B Unbound\-checkconf checks the configuration file for the \fIunbound\fR(8) DNS resolver for syntax and other errors. The config file syntax is described in \fIunbound.conf\fR(5). .P The available options are: .TP .B \-h Show the version and commandline option help. .TP .B \-f Print full pathname, with chroot applied to it. Use with the \-o option. .TP .B \-o\fI option If given, after checking the config file the value of this option is printed to stdout. For "" (disabled) options an empty line is printed. .TP .I cfgfile The config file to read with settings for unbound. It is checked. If omitted, the config file at the default location is checked. .SH "EXIT CODE" The unbound\-checkconf program exits with status code 1 on error, 0 for a correct config file. .SH "FILES" .TP -.I /var/unbound/unbound.conf +.I @ub_conf_file@ unbound configuration file. .SH "SEE ALSO" \fIunbound.conf\fR(5), \fIunbound\fR(8). diff --git a/contrib/unbound/doc/unbound-control.8 b/contrib/unbound/doc/unbound-control.8 index 7b4026378146..ab5413c9a0ba 100644 --- a/contrib/unbound/doc/unbound-control.8 +++ b/contrib/unbound/doc/unbound-control.8 @@ -1,673 +1,699 @@ -.TH "unbound-control" "8" "Jun 17, 2019" "NLnet Labs" "unbound 1.9.2" +.TH "unbound-control" "8" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" .\" .\" unbound-control.8 -- unbound remote control manual .\" .\" Copyright (c) 2008, NLnet Labs. All rights reserved. .\" .\" See LICENSE for the license. .\" .\" .SH "NAME" .B unbound\-control, .B unbound\-control\-setup \- Unbound remote server control utility. .SH "SYNOPSIS" .B unbound\-control .RB [ \-hq ] .RB [ \-c .IR cfgfile ] .RB [ \-s .IR server ] .IR command .SH "DESCRIPTION" .B Unbound\-control performs remote administration on the \fIunbound\fR(8) DNS server. It reads the configuration file, contacts the unbound server over SSL sends the command and displays the result. .P The available options are: .TP .B \-h Show the version and commandline option help. .TP .B \-c \fIcfgfile The config file to read with settings. If not given the default -config file /var/unbound/unbound.conf is used. +config file @ub_conf_file@ is used. .TP .B \-s \fIserver[@port] IPv4 or IPv6 address of the server to contact. If not given, the address is read from the config file. .TP .B \-q quiet, if the option is given it does not print anything if it works ok. .SH "COMMANDS" There are several commands that the server understands. .TP .B start Start the server. Simply execs \fIunbound\fR(8). The unbound executable is searched for in the \fBPATH\fR set in the environment. It is started with the config file specified using \fI\-c\fR or the default config file. .TP .B stop Stop the server. The server daemon exits. .TP .B reload Reload the server. This flushes the cache and reads the config file fresh. .TP .B verbosity \fInumber Change verbosity value for logging. Same values as \fBverbosity\fR keyword in \fIunbound.conf\fR(5). This new setting lasts until the server is issued a reload (taken from config file again), or the next verbosity control command. .TP .B log_reopen Reopen the logfile, close and open it. Useful for logrotation to make the daemon release the file it is logging to. If you are using syslog it will attempt to close and open the syslog (which may not work if chrooted). .TP .B stats Print statistics. Resets the internal counters to zero, this can be controlled using the \fBstatistics\-cumulative\fR config statement. Statistics are printed with one [name]: [value] per line. .TP .B stats_noreset Peek at statistics. Prints them like the \fBstats\fR command does, but does not reset the internal counters to zero. .TP .B status Display server status. Exit code 3 if not running (the connection to the port is refused), 1 on error, 0 if running. .TP .B local_zone \fIname\fR \fItype Add new local zone with name and type. Like \fBlocal\-zone\fR config statement. If the zone already exists, the type is changed to the given argument. .TP .B local_zone_remove \fIname Remove the local zone with the given name. Removes all local data inside it. If the zone does not exist, the command succeeds. .TP .B local_data \fIRR data... Add new local data, the given resource record. Like \fBlocal\-data\fR config statement, except for when no covering zone exists. In that case this remote control command creates a transparent zone with the same -name as this record. This command is not good at returning detailed syntax -errors. +name as this record. .TP .B local_data_remove \fIname Remove all RR data from local name. If the name already has no items, nothing happens. Often results in NXDOMAIN for the name (in a static zone), but if the name has become an empty nonterminal (there is still data in domain names below the removed name), NOERROR nodata answers are the result for that name. .TP .B local_zones Add local zones read from stdin of unbound\-control. Input is read per line, with name space type on a line. For bulk additions. .TP .B local_zones_remove Remove local zones read from stdin of unbound\-control. Input is one name per line. For bulk removals. .TP .B local_datas Add local data RRs read from stdin of unbound\-control. Input is one RR per line. For bulk additions. .TP .B local_datas_remove Remove local data RRs read from stdin of unbound\-control. Input is one name per line. For bulk removals. .TP .B dump_cache The contents of the cache is printed in a text format to stdout. You can redirect it to a file to store the cache in a file. .TP .B load_cache The contents of the cache is loaded from stdin. Uses the same format as dump_cache uses. Loading the cache with old, or wrong data can result in old or wrong data returned to clients. Loading data into the cache in this way is supported in order to aid with debugging. .TP .B lookup \fIname Print to stdout the name servers that would be used to look up the name specified. .TP .B flush \fIname Remove the name from the cache. Removes the types A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV and NAPTR. Because that is fast to do. Other record types can be removed using .B flush_type or .B flush_zone\fR. .TP .B flush_type \fIname\fR \fItype Remove the name, type information from the cache. .TP .B flush_zone \fIname Remove all information at or below the name from the cache. The rrsets and key entries are removed so that new lookups will be performed. This needs to walk and inspect the entire cache, and is a slow operation. The entries are set to expired in the implementation of this command (so, with serve\-expired enabled, it'll serve that information but schedule a prefetch for new information). .TP .B flush_bogus Remove all bogus data from the cache. .TP .B flush_negative Remove all negative data from the cache. This is nxdomain answers, nodata answers and servfail answers. Also removes bad key entries (which could be due to failed lookups) from the dnssec key cache, and iterator last-resort lookup failures from the rrset cache. .TP .B flush_stats Reset statistics to zero. .TP .B flush_requestlist Drop the queries that are worked on. Stops working on the queries that the server is working on now. The cache is unaffected. No reply is sent for those queries, probably making those users request again later. Useful to make the server restart working on queries with new settings, such as a higher verbosity level. .TP .B dump_requestlist Show what is worked on. Prints all queries that the server is currently working on. Prints the time that users have been waiting. For internal requests, no time is printed. And then prints out the module status. This prints the queries from the first thread, and not queries that are being serviced from other threads. .TP .B flush_infra \fIall|IP If all then entire infra cache is emptied. If a specific IP address, the entry for that address is removed from the cache. It contains EDNS, ping and lameness data. .TP .B dump_infra Show the contents of the infra cache. .TP .B set_option \fIopt: val Set the option to the given value without a reload. The cache is therefore not flushed. The option must end with a ':' and whitespace must be between the option and the value. Some values may not have an effect if set this way, the new values are not written to the config file, not all options are supported. This is different from the set_option call in libunbound, where all values work because unbound has not been initialized. .IP The values that work are: statistics\-interval, statistics\-cumulative, do\-not\-query\-localhost, harden\-short\-bufsize, harden\-large\-queries, harden\-glue, harden\-dnssec\-stripped, harden\-below\-nxdomain, harden\-referral\-path, prefetch, prefetch\-key, log\-queries, hide\-identity, hide\-version, identity, version, val\-log\-level, val\-log\-squelch, ignore\-cd\-flag, add\-holddown, del\-holddown, keep\-missing, tcp\-upstream, ssl\-upstream, max\-udp\-size, ratelimit, ip\-ratelimit, cache\-max\-ttl, cache\-min\-ttl, cache\-max\-negative\-ttl. .TP .B get_option \fIopt Get the value of the option. Give the option name without a trailing ':'. The value is printed. If the value is "", nothing is printed and the connection closes. On error 'error ...' is printed (it gives a syntax error on unknown option). For some options a list of values, one on each line, is printed. The options are shown from the config file as modified with set_option. For some options an override may have been taken that does not show up with this command, not results from e.g. the verbosity and forward control commands. Not all options work, see list_stubs, list_forwards, list_local_zones and list_local_data for those. .TP .B list_stubs List the stub zones in use. These are printed one by one to the output. This includes the root hints in use. .TP .B list_forwards List the forward zones in use. These are printed zone by zone to the output. .TP .B list_insecure List the zones with domain\-insecure. .TP .B list_local_zones List the local zones in use. These are printed one per line with zone type. .TP .B list_local_data List the local data RRs in use. The resource records are printed. .TP .B insecure_add \fIzone Add a \fBdomain\-insecure\fR for the given zone, like the statement in unbound.conf. Adds to the running unbound without affecting the cache contents (which may still be bogus, use \fBflush_zone\fR to remove it), does not affect the config file. .TP .B insecure_remove \fIzone Removes domain\-insecure for the given zone. .TP .B forward_add \fR[\fI+i\fR] \fIzone addr ... Add a new forward zone to running unbound. With +i option also adds a \fIdomain\-insecure\fR for the zone (so it can resolve insecurely if you have a DNSSEC root trust anchor configured for other names). The addr can be IP4, IP6 or nameserver names, like \fIforward-zone\fR config in unbound.conf. .TP .B forward_remove \fR[\fI+i\fR] \fIzone Remove a forward zone from running unbound. The +i also removes a \fIdomain\-insecure\fR for the zone. .TP .B stub_add \fR[\fI+ip\fR] \fIzone addr ... Add a new stub zone to running unbound. With +i option also adds a \fIdomain\-insecure\fR for the zone. With +p the stub zone is set to prime, without it it is set to notprime. The addr can be IP4, IP6 or nameserver names, like the \fIstub-zone\fR config in unbound.conf. .TP .B stub_remove \fR[\fI+i\fR] \fIzone Remove a stub zone from running unbound. The +i also removes a \fIdomain\-insecure\fR for the zone. .TP .B forward \fR[\fIoff\fR | \fIaddr ...\fR ] Setup forwarding mode. Configures if the server should ask other upstream nameservers, should go to the internet root nameservers itself, or show the current config. You could pass the nameservers after a DHCP update. .IP Without arguments the current list of addresses used to forward all queries to is printed. On startup this is from the forward\-zone "." configuration. Afterwards it shows the status. It prints off when no forwarding is used. .IP If \fIoff\fR is passed, forwarding is disabled and the root nameservers are used. This can be used to avoid to avoid buggy or non\-DNSSEC supporting nameservers returned from DHCP. But may not work in hotels or hotspots. .IP If one or more IPv4 or IPv6 addresses are given, those are then used to forward queries to. The addresses must be separated with spaces. With '@port' the port number can be set explicitly (default port is 53 (DNS)). .IP By default the forwarder information from the config file for the root "." is used. The config file is not changed, so after a reload these changes are gone. Other forward zones from the config file are not affected by this command. .TP .B ratelimit_list \fR[\fI+a\fR] List the domains that are ratelimited. Printed one per line with current estimated qps and qps limit from config. With +a it prints all domains, not just the ratelimited domains, with their estimated qps. The ratelimited domains return an error for uncached (new) queries, but cached queries work as normal. .TP .B ip_ratelimit_list \fR[\fI+a\fR] List the ip addresses that are ratelimited. Printed one per line with current estimated qps and qps limit from config. With +a it prints all ips, not just the ratelimited ips, with their estimated qps. The ratelimited ips are dropped before checking the cache. .TP .B list_auth_zones List the auth zones that are configured. Printed one per line with a status, indicating if the zone is expired and current serial number. .TP .B auth_zone_reload \fIzone\fR Reload the auth zone from zonefile. The zonefile is read in overwriting the current contents of the zone in memory. This changes the auth zone contents itself, not the cache contents. Such cache contents exists if you set unbound to validate with for-upstream yes and that can be cleared with \fBflush_zone\fR \fIzone\fR. .TP .B auth_zone_transfer \fIzone\fR Transfer the auth zone from master. The auth zone probe sequence is started, where the masters are probed to see if they have an updated zone (with the SOA serial check). And then the zone is transferred for a newer zone version. .TP +.B rpz_enable \fIzone\fR +Enable the RPZ zone if it had previously been disabled. +.TP +.B rpz_disable \fIzone\fR +Disable the RPZ zone. +.TP .B view_list_local_zones \fIview\fR \fIlist_local_zones\fR for given view. .TP .B view_local_zone \fIview\fR \fIname\fR \fItype \fIlocal_zone\fR for given view. .TP .B view_local_zone_remove \fIview\fR \fIname \fIlocal_zone_remove\fR for given view. .TP .B view_list_local_data \fIview\fR \fIlist_local_data\fR for given view. .TP .B view_local_data \fIview\fR \fIRR data... \fIlocal_data\fR for given view. .TP .B view_local_data_remove \fIview\fR \fIname \fIlocal_data_remove\fR for given view. .TP +.B view_local_datas_remove \fIview\fR +Remove a list of \fIlocal_data\fR for given view from stdin. Like local_datas_remove. +.TP .B view_local_datas \fIview\fR Add a list of \fIlocal_data\fR for given view from stdin. Like local_datas. .SH "EXIT CODE" The unbound\-control program exits with status code 1 on error, 0 on success. .SH "SET UP" The setup requires a self\-signed certificate and private keys for both the server and client. The script \fIunbound\-control\-setup\fR generates these in the default run directory, or with \-d in another directory. If you change the access control permissions on the key files you can decide who can use unbound\-control, by default owner and group but not all users. Run the script under the same username as you have configured in unbound.conf or as root, so that the daemon is permitted to read the files, for example with: .nf sudo \-u unbound unbound\-control\-setup .fi If you have not configured a username in unbound.conf, the keys need read permission for the user credentials under which the daemon is started. The script preserves private keys present in the directory. After running the script as root, turn on \fBcontrol\-enable\fR in \fIunbound.conf\fR. .SH "STATISTIC COUNTERS" The \fIstats\fR command shows a number of statistic counters. .TP .I threadX.num.queries number of queries received by thread .TP .I threadX.num.queries_ip_ratelimited number of queries rate limited by thread .TP .I threadX.num.cachehits number of queries that were successfully answered using a cache lookup .TP .I threadX.num.cachemiss number of queries that needed recursive processing .TP .I threadX.num.dnscrypt.crypted number of queries that were encrypted and successfully decapsulated by dnscrypt. .TP .I threadX.num.dnscrypt.cert number of queries that were requesting dnscrypt certificates. .TP .I threadX.num.dnscrypt.cleartext number of queries received on dnscrypt port that were cleartext and not a request for certificates. .TP .I threadX.num.dnscrypt.malformed number of request that were neither cleartext, not valid dnscrypt messages. .TP .I threadX.num.prefetch number of cache prefetches performed. This number is included in cachehits, as the original query had the unprefetched answer from cache, and resulted in recursive processing, taking a slot in the requestlist. Not part of the recursivereplies (or the histogram thereof) or cachemiss, as a cache response was sent. .TP -.I threadX.num.zero_ttl -number of replies with ttl zero, because they served an expired cache entry. +.I threadX.num.expired +number of replies that served an expired cache entry. .TP .I threadX.num.recursivereplies The number of replies sent to queries that needed recursive processing. Could be smaller than threadX.num.cachemiss if due to timeouts no replies were sent for some queries. .TP .I threadX.requestlist.avg The average number of requests in the internal recursive processing request list on insert of a new incoming recursive processing query. .TP .I threadX.requestlist.max Maximum size attained by the internal recursive processing request list. .TP .I threadX.requestlist.overwritten Number of requests in the request list that were overwritten by newer entries. This happens if there is a flood of queries that recursive processing and the server has a hard time. .TP .I threadX.requestlist.exceeded Queries that were dropped because the request list was full. This happens if a flood of queries need recursive processing, and the server can not keep up. .TP .I threadX.requestlist.current.all Current size of the request list, includes internally generated queries (such as priming queries and glue lookups). .TP .I threadX.requestlist.current.user Current size of the request list, only the requests from client queries. .TP .I threadX.recursion.time.avg Average time it took to answer queries that needed recursive processing. Note that queries that were answered from the cache are not in this average. .TP .I threadX.recursion.time.median The median of the time it took to answer queries that needed recursive processing. The median means that 50% of the user queries were answered in less than this time. Because of big outliers (usually queries to non responsive servers), the average can be bigger than the median. This median has been calculated by interpolation from a histogram. .TP .I threadX.tcpusage The currently held tcp buffers for incoming connections. A spot value on the time of the request. This helps you spot if the incoming\-num\-tcp buffers are full. .TP .I total.num.queries summed over threads. .TP .I total.num.cachehits summed over threads. .TP .I total.num.cachemiss summed over threads. .TP .I total.num.dnscrypt.crypted summed over threads. .TP .I total.num.dnscrypt.cert summed over threads. .TP .I total.num.dnscrypt.cleartext summed over threads. .TP .I total.num.dnscrypt.malformed summed over threads. .TP .I total.num.prefetch summed over threads. .TP -.I total.num.zero_ttl +.I total.num.expired summed over threads. .TP .I total.num.recursivereplies summed over threads. .TP .I total.requestlist.avg averaged over threads. .TP .I total.requestlist.max the maximum of the thread requestlist.max values. .TP .I total.requestlist.overwritten summed over threads. .TP .I total.requestlist.exceeded summed over threads. .TP .I total.requestlist.current.all summed over threads. .TP .I total.recursion.time.median averaged over threads. .TP .I total.tcpusage summed over threads. .TP .I time.now current time in seconds since 1970. .TP .I time.up uptime since server boot in seconds. .TP .I time.elapsed time since last statistics printout, in seconds. .SH EXTENDED STATISTICS .TP .I mem.cache.rrset Memory in bytes in use by the RRset cache. .TP .I mem.cache.message Memory in bytes in use by the message cache. .TP .I mem.cache.dnscrypt_shared_secret Memory in bytes in use by the dnscrypt shared secrets cache. .TP .I mem.cache.dnscrypt_nonce Memory in bytes in use by the dnscrypt nonce cache. .TP .I mem.mod.iterator Memory in bytes in use by the iterator module. .TP .I mem.mod.validator Memory in bytes in use by the validator module. Includes the key cache and negative cache. .TP .I mem.streamwait Memory in bytes in used by the TCP and TLS stream wait buffers. These are answers waiting to be written back to the clients. .TP +.I mem.http.query_buffer +Memory in bytes used by the HTTP/2 query buffers. Containing (partial) DNS +queries waiting for request stream completion. +.TP +.I mem.http.response_buffer +Memory in bytes used by the HTTP/2 response buffers. Containing DNS responses +waiting to be written back to the clients. +.TP .I histogram...to.. Shows a histogram, summed over all threads. Every element counts the recursive queries whose reply time fit between the lower and upper bound. Times larger or equal to the lowerbound, and smaller than the upper bound. There are 40 buckets, with bucket sizes doubling. .TP .I num.query.type.A The total number of queries over all threads with query type A. Printed for the other query types as well, but only for the types for which queries were received, thus =0 entries are omitted for brevity. .TP .I num.query.type.other Number of queries with query types 256\-65535. .TP .I num.query.class.IN The total number of queries over all threads with query class IN (internet). Also printed for other classes (such as CH (CHAOS) sometimes used for debugging), or NONE, ANY, used by dynamic update. num.query.class.other is printed for classes 256\-65535. .TP .I num.query.opcode.QUERY The total number of queries over all threads with query opcode QUERY. Also printed for other opcodes, UPDATE, ... .TP .I num.query.tcp Number of queries that were made using TCP towards the unbound server. .TP .I num.query.tcpout Number of queries that the unbound server made using TCP outgoing towards other servers. .TP .I num.query.tls Number of queries that were made using TLS towards the unbound server. These are also counted in num.query.tcp, because TLS uses TCP. .TP .I num.query.tls.resume Number of TLS session resumptions, these are queries over TLS towards the unbound server where the client negotiated a TLS session resumption key. .TP +.I num.query.https +Number of queries that were made using HTTPS towards the unbound server. +These are also counted in num.query.tcp and num.query.tls, because HTTPS +uses TLS and TCP. +.TP .I num.query.ipv6 Number of queries that were made using IPv6 towards the unbound server. .TP .I num.query.flags.RD The number of queries that had the RD flag set in the header. Also printed for flags QR, AA, TC, RA, Z, AD, CD. Note that queries with flags QR, AA or TC may have been rejected because of that. .TP .I num.query.edns.present number of queries that had an EDNS OPT record present. .TP .I num.query.edns.DO number of queries that had an EDNS OPT record with the DO (DNSSEC OK) bit set. These queries are also included in the num.query.edns.present number. .TP .I num.query.ratelimited The number of queries that are turned away from being send to nameserver due to ratelimiting. .TP .I num.query.dnscrypt.shared_secret.cachemiss The number of dnscrypt queries that did not find a shared secret in the cache. The can be use to compute the shared secret hitrate. .TP .I num.query.dnscrypt.replay The number of dnscrypt queries that found a nonce hit in the nonce cache and hence are considered a query replay. .TP .I num.answer.rcode.NXDOMAIN The number of answers to queries, from cache or from recursion, that had the return code NXDOMAIN. Also printed for the other return codes. .TP .I num.answer.rcode.nodata The number of answers to queries that had the pseudo return code nodata. This means the actual return code was NOERROR, but additionally, no data was carried in the answer (making what is called a NOERROR/NODATA answer). These queries are also included in the num.answer.rcode.NOERROR number. Common for AAAA lookups when an A record exists, and no AAAA. .TP .I num.answer.secure Number of answers that were secure. The answer validated correctly. The AD bit might have been set in some of these answers, where the client signalled (with DO or AD bit in the query) that they were ready to accept the AD bit in the answer. .TP .I num.answer.bogus Number of answers that were bogus. These answers resulted in SERVFAIL to the client because the answer failed validation. .TP .I num.rrset.bogus The number of rrsets marked bogus by the validator. Increased for every RRset inspection that fails. .TP .I unwanted.queries Number of queries that were refused or dropped because they failed the access control settings. .TP .I unwanted.replies Replies that were unwanted or unsolicited. Could have been random traffic, delayed duplicates, very late answers, or could be spoofing attempts. Some low level of late answers and delayed duplicates are to be expected with the UDP protocol. Very high values could indicate a threat (spoofing). .TP .I msg.cache.count The number of items (DNS replies) in the message cache. .TP .I rrset.cache.count The number of RRsets in the rrset cache. This includes rrsets used by the messages in the message cache, but also delegation information. .TP .I infra.cache.count The number of items in the infra cache. These are IP addresses with their timing and protocol support information. .TP .I key.cache.count The number of items in the key cache. These are DNSSEC keys, one item per delegation point, and their validation status. .TP .I dnscrypt_shared_secret.cache.count The number of items in the shared secret cache. These are precomputed shared secrets for a given client public key/server secret key pair. Shared secrets are CPU intensive and this cache allows unbound to avoid recomputing the shared secret when multiple dnscrypt queries are sent from the same client. .TP .I dnscrypt_nonce.cache.count The number of items in the client nonce cache. This cache is used to prevent dnscrypt queries replay. The client nonce must be unique for each client public key/server secret key pair. This cache should be able to host QPS * `replay window` interval keys to prevent replay of a query during `replay window` seconds. .TP .I num.query.authzone.up The number of queries answered from auth\-zone data, upstream queries. These queries would otherwise have been sent (with fallback enabled) to the internet, but are now answered from the auth zone. .TP .I num.query.authzone.down The number of queries for downstream answered from auth\-zone data. These queries are from downstream clients, and have had an answer from the data in the auth zone. .TP .I num.query.aggressive.NOERROR The number of queries answered using cached NSEC records with NODATA RCODE. These queries would otherwise have been sent to the internet, but are now answered using cached data. .TP .I num.query.aggressive.NXDOMAIN The number of queries answered using cached NSEC records with NXDOMAIN RCODE. These queries would otherwise have been sent to the internet, but are now answered using cached data. .TP .I num.query.subnet Number of queries that got an answer that contained EDNS client subnet data. .TP .I num.query.subnet_cache Number of queries answered from the edns client subnet cache. These are counted as cachemiss by the main counters, but hit the client subnet specific cache, after getting processed by the edns client subnet module. +.TP +.I num.rpz.action. +Number of queries answered using configured RPZ policy, per RPZ action type. +Possible actions are: nxdomain, nodata, passthru, drop, tcp\-only, local\-data, +disabled, and cname\-override. .SH "FILES" .TP -.I /var/unbound/unbound.conf +.I @ub_conf_file@ unbound configuration file. .TP -.I /var/unbound +.I @UNBOUND_RUN_DIR@ directory with private keys (unbound_server.key and unbound_control.key) and self\-signed certificates (unbound_server.pem and unbound_control.pem). .SH "SEE ALSO" \fIunbound.conf\fR(5), \fIunbound\fR(8). diff --git a/contrib/unbound/doc/unbound-host.1 b/contrib/unbound/doc/unbound-host.1 index 296bd5994dbe..b7d4d2350074 100644 --- a/contrib/unbound/doc/unbound-host.1 +++ b/contrib/unbound/doc/unbound-host.1 @@ -1,118 +1,118 @@ -.TH "unbound\-host" "1" "Jun 17, 2019" "NLnet Labs" "unbound 1.9.2" +.TH "unbound\-host" "1" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" .\" .\" unbound-host.1 -- unbound DNS lookup utility .\" .\" Copyright (c) 2007, NLnet Labs. All rights reserved. .\" .\" See LICENSE for the license. .\" .\" .SH "NAME" .B unbound\-host \- unbound DNS lookup utility .SH "SYNOPSIS" .B unbound\-host .RB [ \-C .IR configfile ] .RB [ \-vdhr46D ] .RB [ \-c .IR class ] .RB [ \-t .IR type ] .RB [ \-y .IR key ] .RB [ \-f .IR keyfile ] .RB [ \-F .IR namedkeyfile ] .I hostname .SH "DESCRIPTION" .B Unbound\-host uses the unbound validating resolver to query for the hostname and display results. With the \fB\-v\fR option it displays validation status: secure, insecure, bogus (security failure). .P By default it reads no configuration file whatsoever. It attempts to reach the internet root servers. With \fB\-C\fR an unbound config file and with \fB\-r\fR resolv.conf can be read. .P The available options are: .TP .I hostname This name is resolved (looked up in the DNS). If a IPv4 or IPv6 address is given, a reverse lookup is performed. .TP .B \-h Show the version and commandline option help. .TP .B \-v Enable verbose output and it shows validation results, on every line. Secure means that the NXDOMAIN (no such domain name), nodata (no such data) or positive data response validated correctly with one of the keys. Insecure means that that domain name has no security set up for it. Bogus (security failure) means that the response failed one or more checks, it is likely wrong, outdated, tampered with, or broken. .TP .B \-d Enable debug output to stderr. One \-d shows what the resolver and validator are doing and may tell you what is going on. More times, \-d \-d, gives a lot of output, with every packet sent and received. .TP .B \-c \fIclass Specify the class to lookup for, the default is IN the internet class. .TP .B \-t \fItype Specify the type of data to lookup. The default looks for IPv4, IPv6 and mail handler data, or domain name pointers for reverse queries. .TP .B \-y \fIkey Specify a public key to use as trust anchor. This is the base for a chain of trust that is built up from the trust anchor to the response, in order to validate the response message. Can be given as a DS or DNSKEY record. For example \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD". .TP .B \-D Enables DNSSEC validation. Reads the root anchor from the default configured -root anchor at the default location, \fI/var/unbound/root.key\fR. +root anchor at the default location, \fI@UNBOUND_ROOTKEY_FILE@\fR. .TP .B \-f \fIkeyfile Reads keys from a file. Every line has a DS or DNSKEY record, in the format as for \-y. The zone file format, the same as dig and drill produce. .TP .B \-F \fInamedkeyfile Reads keys from a BIND\-style named.conf file. Only the trusted\-key {}; entries are read. .TP .B \-C \fIconfigfile Uses the specified unbound.conf to prime .IR libunbound (3). Pass it as first argument if you want to override some options from the config file with further arguments on the commandline. .TP .B \-r Read /etc/resolv.conf, and use the forward DNS servers from there (those could have been set by DHCP). More info in .IR resolv.conf (5). Breaks validation if those servers do not support DNSSEC. .TP .B \-4 Use solely the IPv4 network for sending packets. .TP .B \-6 Use solely the IPv6 network for sending packets. .SH "EXAMPLES" Some examples of use. The keys shown below are fakes, thus a security failure is encountered. .P $ unbound\-host www.example.com .P $ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" www.example.com .P $ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" 192.0.2.153 .SH "EXIT CODE" The unbound\-host program exits with status code 1 on error, 0 on no error. The data may not be available on exit code 0, exit code 1 means the lookup encountered a fatal error. .SH "SEE ALSO" \fIunbound.conf\fR(5), \fIunbound\fR(8). diff --git a/contrib/unbound/doc/unbound.8 b/contrib/unbound/doc/unbound.8 index 50a51aa3d93e..11b02aebcb2e 100644 --- a/contrib/unbound/doc/unbound.8 +++ b/contrib/unbound/doc/unbound.8 @@ -1,85 +1,88 @@ -.TH "unbound" "8" "Jun 17, 2019" "NLnet Labs" "unbound 1.9.2" +.TH "unbound" "8" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" .\" .\" unbound.8 -- unbound manual .\" .\" Copyright (c) 2007, NLnet Labs. All rights reserved. .\" .\" See LICENSE for the license. .\" .\" .SH "NAME" .B unbound -\- Unbound DNS validating resolver 1.9.2. +\- Unbound DNS validating resolver 1.14.0. .SH "SYNOPSIS" .B unbound .RB [ \-h ] .RB [ \-d ] .RB [ \-p ] .RB [ \-v ] .RB [ \-c .IR cfgfile ] .SH "DESCRIPTION" .B Unbound is a caching DNS resolver. .P It uses a built in list of authoritative nameservers for the root zone (.), the so called root hints. On receiving a DNS query it will ask the root nameservers for an answer and will in almost all cases receive a delegation to a top level domain (TLD) authoritative nameserver. It will then ask that nameserver for an answer. It will recursively continue until an answer is found or no answer is available (NXDOMAIN). For performance and efficiency reasons that answer is cached for a certain time (the answer's time\-to\-live or TTL). A second query for the same name will then be answered from the cache. Unbound can also do DNSSEC validation. .P To use a locally running .B Unbound for resolving put .sp .RS 6n nameserver 127.0.0.1 .RE .sp into .IR resolv.conf (5). .P If authoritative DNS is needed as well using .IR nsd (8), careful setup is required because authoritative nameservers and resolvers are using the same port number (53). .P The available options are: .TP .B \-h -Show the version and commandline option help. +Show the version number and commandline option help, and exit. .TP .B \-c\fI cfgfile Set the config file with settings for unbound to read instead of reading the -file at the default location, /var/unbound/unbound.conf. The syntax is +file at the default location, @ub_conf_file@. The syntax is described in \fIunbound.conf\fR(5). .TP .B \-d Debug flag: do not fork into the background, but stay attached to the console. This flag will also delay writing to the log file until the thread\-spawn time, so that most config and setup errors appear on stderr. If given twice or more, logging does not switch to the log file or to syslog, but the log messages are printed to stderr all the time. .TP .B \-p Don't use a pidfile. This argument should only be used by supervision systems which can ensure that only one instance of unbound will run concurrently. .TP .B \-v Increase verbosity. If given multiple times, more information is logged. This is in addition to the verbosity (if any) from the config file. +.TP +.B \-V +Show the version number and build options, and exit. .SH "SEE ALSO" \fIunbound.conf\fR(5), \fIunbound\-checkconf\fR(8), \fInsd\fR(8). .SH "AUTHORS" .B Unbound developers are mentioned in the CREDITS file in the distribution. diff --git a/contrib/unbound/doc/unbound.conf.5 b/contrib/unbound/doc/unbound.conf.5 index 9320d167d9f1..4c144db22ab5 100644 --- a/contrib/unbound/doc/unbound.conf.5 +++ b/contrib/unbound/doc/unbound.conf.5 @@ -1,2135 +1,2696 @@ -.TH "unbound.conf" "5" "Jun 17, 2019" "NLnet Labs" "unbound 1.9.2" +.TH "unbound.conf" "5" "Dec 9, 2021" "NLnet Labs" "unbound 1.14.0" .\" .\" unbound.conf.5 -- unbound.conf manual .\" .\" Copyright (c) 2007, NLnet Labs. All rights reserved. .\" .\" See LICENSE for the license. .\" .\" .SH "NAME" .B unbound.conf \- Unbound configuration file. .SH "SYNOPSIS" .B unbound.conf .SH "DESCRIPTION" .B unbound.conf is used to configure \fIunbound\fR(8). The file format has attributes and values. Some attributes have attributes inside them. The notation is: attribute: value. .P Comments start with # and last to the end of line. Empty lines are ignored as is whitespace at the beginning of a line. .P The utility \fIunbound\-checkconf\fR(8) can be used to check unbound.conf prior to usage. .SH "EXAMPLE" An example config file is shown below. Copy this to /etc/unbound/unbound.conf and start the server with: .P .nf $ unbound \-c /etc/unbound/unbound.conf .fi .P Most settings are the defaults. Stop the server with: .P .nf $ kill `cat /etc/unbound/unbound.pid` .fi .P Below is a minimal config file. The source distribution contains an extensive example.conf file with all the options. .P .nf # unbound.conf(5) config file for unbound(8). server: directory: "/etc/unbound" username: unbound # make sure unbound can access entropy from inside the chroot. # e.g. on linux the use these commands (on BSD, devfs(8) is used): - # mount \-\-bind \-n /dev/random /etc/unbound/dev/random + # mount \-\-bind \-n /dev/urandom /etc/unbound/dev/urandom # and mount \-\-bind \-n /dev/log /etc/unbound/dev/log chroot: "/etc/unbound" # logfile: "/etc/unbound/unbound.log" #uncomment to use logfile. pidfile: "/etc/unbound/unbound.pid" # verbosity: 1 # uncomment and increase to get more logging. # listen on all interfaces, answer queries from the local subnet. interface: 0.0.0.0 interface: ::0 access\-control: 10.0.0.0/8 allow access\-control: 2001:DB8::/64 allow .fi .SH "FILE FORMAT" -There must be whitespace between keywords. Attribute keywords end with a colon ':'. -An attribute is followed by its containing attributes, or a value. +There must be whitespace between keywords. Attribute keywords end with a +colon ':'. An attribute is followed by a value, or its containing attributes +in which case it is referred to as a clause. Clauses can be repeated throughout +the file (or included files) to group attributes under the same clause. .P Files can be included using the .B include: directive. It can appear anywhere, it accepts a single file name as argument. Processing continues as if the text from the included file was copied into the config file at that point. If also using chroot, using full path names for the included files works, relative pathnames for the included names work if the directory where the daemon is started equals its chroot/working directory or is specified before the include statement with directory: dir. Wildcards can be used to include multiple files, see \fIglob\fR(7). +.P +For a more structural include option, the +.B include\-toplevel: +directive can be used. This closes whatever clause is currently active (if any) +and forces the use of clauses in the included files and right after this +directive. .SS "Server Options" These options are part of the .B server: clause. .TP .B verbosity: \fI -The verbosity number, level 0 means no verbosity, only errors. Level 1 -gives operational information. Level 2 gives detailed operational -information. Level 3 gives query level information, output per query. -Level 4 gives algorithm level information. Level 5 logs client -identification for cache misses. Default is level 1. +The verbosity number, level 0 means no verbosity, only errors. Level 1 +gives operational information. Level 2 gives detailed operational +information including short information per query. Level 3 gives query level +information, output per query. Level 4 gives algorithm level information. +Level 5 logs client identification for cache misses. Default is level 1. The verbosity can also be increased from the commandline, see \fIunbound\fR(8). .TP .B statistics\-interval: \fI The number of seconds between printing statistics to the log for every thread. Disable with value 0 or "". Default is disabled. The histogram statistics are only printed if replies were sent during the statistics interval, requestlist statistics are printed for every interval (but can be 0). This is because the median calculation requires data to be present. .TP .B statistics\-cumulative: \fI If enabled, statistics are cumulative since starting unbound, without clearing the statistics counters after logging the statistics. Default is no. .TP .B extended\-statistics: \fI If enabled, extended statistics are printed from \fIunbound\-control\fR(8). Default is off, because keeping track of more statistics takes time. The counters are listed in \fIunbound\-control\fR(8). .TP .B num\-threads: \fI The number of threads to create to serve clients. Use 1 for no threading. .TP .B port: \fI The port number, default 53, on which the server responds to queries. .TP .B interface: \fI Interface to use to connect to the network. This interface is listened to for queries from clients, and answers to clients are given from it. Can be given multiple times to work on several interfaces. If none are -given the default is to listen to localhost. +given the default is to listen to localhost. If an interface name is used +instead of an ip address, the list of ip addresses on that interface are used. The interfaces are not changed on a reload (kill \-HUP) but only on restart. A port number can be specified with @port (without spaces between interface and port number), if not specified the default port (from \fBport\fR) is used. .TP .B ip\-address: \fI Same as interface: (for ease of compatibility with nsd.conf). .TP .B interface\-automatic: \fI -Detect source interface on UDP queries and copy them to replies. This -feature is experimental, and needs support in your OS for particular socket -options. Default value is no. +Listen on all addresses on all (current and future) interfaces, detect the +source interface on UDP queries and copy them to replies. This is a lot like +ip\-transparent, but this option services all interfaces whilst with +ip\-transparent you can select which (future) interfaces unbound provides +service on. This feature is experimental, and needs support in your OS for +particular socket options. Default value is no. .TP .B outgoing\-interface: \fI Interface to use to connect to the network. This interface is used to send queries to authoritative servers and receive their replies. Can be given multiple times to work on several interfaces. If none are given the default (all) is used. You can specify the same interfaces in .B interface: and .B outgoing\-interface: lines, the interfaces are then used for both purposes. Outgoing queries are sent via a random outgoing interface to counter spoofing. .IP If an IPv6 netblock is specified instead of an individual IPv6 address, outgoing UDP queries will use a randomised source address taken from the netblock to counter spoofing. Requires the IPv6 netblock to be routed to the host running unbound, and requires OS support for unprivileged non-local binds (currently only supported on Linux). Several netblocks may be specified with multiple .B outgoing\-interface: options, but do not specify both an individual IPv6 address and an IPv6 netblock, or the randomisation will be compromised. Consider combining with .B prefer\-ip6: yes to increase the likelihood of IPv6 nameservers being selected for queries. On Linux you need these two commands to be able to use the freebind socket option to receive traffic for the ip6 netblock: ip \-6 addr add mynetblock/64 dev lo && ip \-6 route add local mynetblock/64 dev lo .TP .B outgoing\-range: \fI Number of ports to open. This number of file descriptors can be opened per thread. Must be at least 1. Default depends on compile options. Larger numbers need extra resources from the operating system. For performance a very large value is best, use libevent to make this possible. .TP .B outgoing\-port\-permit: \fI Permit unbound to open this port or range of ports for use to send queries. A larger number of permitted outgoing ports increases resilience against spoofing attempts. Make sure these ports are not needed by other daemons. By default only ports above 1024 that have not been assigned by IANA are used. Give a port number or a range of the form "low\-high", without spaces. .IP The \fBoutgoing\-port\-permit\fR and \fBoutgoing\-port\-avoid\fR statements are processed in the line order of the config file, adding the permitted ports and subtracting the avoided ports from the set of allowed ports. The processing starts with the non IANA allocated ports above 1024 in the set of allowed ports. .TP .B outgoing\-port\-avoid: \fI Do not permit unbound to open this port or range of ports for use to send queries. Use this to make sure unbound does not grab a port that another daemon needs. The port is avoided on all outgoing interfaces, both IP4 and IP6. By default only ports above 1024 that have not been assigned by IANA are used. Give a port number or a range of the form "low\-high", without spaces. .TP .B outgoing\-num\-tcp: \fI Number of outgoing TCP buffers to allocate per thread. Default is 10. If set to 0, or if do\-tcp is "no", no TCP queries to authoritative servers are done. For larger installations increasing this value is a good idea. .TP .B incoming\-num\-tcp: \fI Number of incoming TCP buffers to allocate per thread. Default is 10. If set to 0, or if do\-tcp is "no", no TCP queries from clients are accepted. For larger installations increasing this value is a good idea. .TP .B edns\-buffer\-size: \fI Number of bytes size to advertise as the EDNS reassembly buffer size. This is the value put into datagrams over UDP towards peers. The actual buffer size is determined by msg\-buffer\-size (both for TCP and UDP). Do -not set higher than that value. Default is 4096 which is RFC recommended. -If you have fragmentation reassembly problems, usually seen as timeouts, -then a value of 1472 can fix it. Setting to 512 bypasses even the most -stringent path MTU problems, but is seen as extreme, since the amount -of TCP fallback generated is excessive (probably also for this resolver, -consider tuning the outgoing tcp number). +not set higher than that value. Default is 1232 which is the DNS Flag Day 2020 +recommendation. Setting to 512 bypasses even the most stringent path MTU +problems, but is seen as extreme, since the amount of TCP fallback generated is +excessive (probably also for this resolver, consider tuning the outgoing tcp +number). .TP .B max\-udp\-size: \fI Maximum UDP response size (not applied to TCP response). 65536 disables the udp response size maximum, and uses the choice from the client, always. Suggested values are 512 to 4096. Default is 4096. .TP .B stream\-wait\-size: \fI Number of bytes size maximum to use for waiting stream buffers. Default is 4 megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes or gigabytes (1024*1024 bytes in a megabyte). As TCP and TLS streams queue up multiple results, the amount of memory used for these buffers does not exceed this number, otherwise the responses are dropped. This manages the total memory usage of the server (under heavy use), the number of requests that can be queued up per connection is also limited, with further requests waiting in TCP buffers. .TP .B msg\-buffer\-size: \fI Number of bytes size of the message buffers. Default is 65552 bytes, enough for 64 Kb packets, the maximum DNS message size. No message larger than this can be sent or received. Can be reduced to use less memory, but some requests for DNS data, such as for huge resource records, will result in a SERVFAIL reply to the client. .TP .B msg\-cache\-size: \fI Number of bytes size of the message cache. Default is 4 megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes or gigabytes (1024*1024 bytes in a megabyte). .TP .B msg\-cache\-slabs: \fI Number of slabs in the message cache. Slabs reduce lock contention by threads. Must be set to a power of 2. Setting (close) to the number of cpus is a reasonable guess. .TP .B num\-queries\-per\-thread: \fI The number of queries that every thread will service simultaneously. If more queries arrive that need servicing, and no queries can be jostled out (see \fIjostle\-timeout\fR), then the queries are dropped. This forces the client to resend after a timeout; allowing the server time to work on the existing queries. Default depends on compile options, 512 or 1024. .TP .B jostle\-timeout: \fI Timeout used when the server is very busy. Set to a value that usually results in one roundtrip to the authority servers. If too many queries arrive, then 50% of the queries are allowed to run to completion, and the other 50% are replaced with the new incoming query if they have already spent more than their allowed time. This protects against denial of service by slow queries or high query rates. Default 200 milliseconds. The effect is that the qps for long-lasting queries is about (numqueriesperthread / 2) / (average time for such long queries) qps. The qps for short queries can be about (numqueriesperthread / 2) / (jostletimeout in whole seconds) qps per thread, about (1024/2)*5 = 2560 qps by default. .TP .B delay\-close: \fI Extra delay for timeouted UDP ports before they are closed, in msec. Default is 0, and that disables it. This prevents very delayed answer packets from the upstream (recursive) servers from bouncing against closed ports and setting off all sort of close-port counters, with eg. 1500 msec. When timeouts happen you need extra sockets, it checks the ID and remote IP of packets, and unwanted packets are added to the unwanted packet counter. .TP +.B udp\-connect: \fI +Perform connect for UDP sockets that mitigates ICMP side channel leakage. +Default is yes. +.TP .B unknown\-server\-time\-limit: \fI The wait time in msec for waiting for an unknown server to reply. Increase this if you are behind a slow satellite link, to eg. 1128. That would then avoid re\-querying every initial query because it times out. Default is 376 msec. .TP .B so\-rcvbuf: \fI If not 0, then set the SO_RCVBUF socket option to get more buffer space on UDP port 53 incoming queries. So that short spikes on busy servers do not drop packets (see counter in netstat \-su). Default is 0 (use system value). Otherwise, the number of bytes to ask for, try "4m" on a busy server. The OS caps it at a maximum, on linux unbound needs root permission to bypass the limit, or the admin can use sysctl net.core.rmem_max. On BSD change kern.ipc.maxsockbuf in /etc/sysctl.conf. On OpenBSD change header and recompile kernel. On Solaris ndd \-set /dev/udp udp_max_buf 8388608. .TP .B so\-sndbuf: \fI If not 0, then set the SO_SNDBUF socket option to get more buffer space on UDP port 53 outgoing queries. This for very busy servers handles spikes in answer traffic, otherwise 'send: resource temporarily unavailable' can get logged, the buffer overrun is also visible by netstat \-su. Default is 0 (use system value). Specify the number of bytes to ask for, try "4m" on a very busy server. The OS caps it at a maximum, on linux unbound needs root permission to bypass the limit, or the admin can use sysctl net.core.wmem_max. On BSD, Solaris changes are similar to so\-rcvbuf. .TP .B so\-reuseport: \fI If yes, then open dedicated listening sockets for incoming queries for each thread and try to set the SO_REUSEPORT socket option on each socket. May distribute incoming queries to threads more evenly. Default is yes. On Linux it is supported in kernels >= 3.9. On other systems, FreeBSD, OSX it may also work. You can enable it (on any platform and kernel), it then attempts to open the port and passes the option if it was available at compile time, if that works it is used, if it fails, it continues silently (unless verbosity 3) without the option. At extreme load it could be better to turn it off to distribute the queries evenly, reported for Linux systems (4.4.x). .TP .B ip\-transparent: \fI If yes, then use IP_TRANSPARENT socket option on sockets where unbound is listening for incoming traffic. Default no. Allows you to bind to non\-local interfaces. For example for non\-existent IP addresses that are going to exist later on, with host failover configuration. This is a lot like interface\-automatic, but that one services all interfaces and with this option you can select which (future) interfaces unbound provides service on. This option needs unbound to be started with root permissions on some systems. The option uses IP_BINDANY on FreeBSD systems and SO_BINDANY on OpenBSD systems. .TP .B ip\-freebind: \fI If yes, then use IP_FREEBIND socket option on sockets where unbound is listening to incoming traffic. Default no. Allows you to bind to IP addresses that are nonlocal or do not exist, like when the network interface or IP address is down. Exists only on Linux, where the similar ip\-transparent option is also available. .TP +.B ip-dscp: \fI +The value of the Differentiated Services Codepoint (DSCP) in the +differentiated services field (DS) of the outgoing IP packet headers. +The field replaces the outdated IPv4 Type-Of-Service field and the +IPV6 traffic class field. +.TP .B rrset\-cache\-size: \fI Number of bytes size of the RRset cache. Default is 4 megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes or gigabytes (1024*1024 bytes in a megabyte). .TP .B rrset\-cache\-slabs: \fI Number of slabs in the RRset cache. Slabs reduce lock contention by threads. Must be set to a power of 2. .TP .B cache\-max\-ttl: \fI Time to live maximum for RRsets and messages in the cache. Default is 86400 seconds (1 day). When the TTL expires, the cache item has expired. Can be set lower to force the resolver to query for data often, and not trust (very large) TTL values. Downstream clients also see the lower TTL. .TP .B cache\-min\-ttl: \fI Time to live minimum for RRsets and messages in the cache. Default is 0. If the minimum kicks in, the data is cached for longer than the domain owner intended, and thus less queries are made to look up the data. Zero makes sure the data in the cache is as the domain owner intended, higher values, especially more than an hour or so, can lead to trouble as the data in the cache does not match up with the actual data any more. .TP .B cache\-max\-negative\-ttl: \fI Time to live maximum for negative responses, these have a SOA in the authority section that is limited in time. Default is 3600. This applies to nxdomain and nodata answers. .TP .B infra\-host\-ttl: \fI Time to live for entries in the host cache. The host cache contains roundtrip timing, lameness and EDNS support information. Default is 900. .TP .B infra\-cache\-slabs: \fI Number of slabs in the infrastructure cache. Slabs reduce lock contention by threads. Must be set to a power of 2. .TP .B infra\-cache\-numhosts: \fI Number of hosts for which information is cached. Default is 10000. .TP .B infra\-cache\-min\-rtt: \fI Lower limit for dynamic retransmit timeout calculation in infrastructure cache. Default is 50 milliseconds. Increase this value if using forwarders needing more time to do recursive name resolution. .TP +.B infra\-keep\-probing: \fI +If enabled the server keeps probing hosts that are down, in the one probe +at a time regime. Default is no. Hosts that are down, eg. they did +not respond during the one probe at a time period, are marked as down and +it may take \fBinfra\-host\-ttl\fR time to get probed again. +.TP .B define\-tag: \fI<"list of tags"> Define the tags that can be used with local\-zone and access\-control. Enclose the list between quotes ("") and put spaces between tags. .TP .B do\-ip4: \fI Enable or disable whether ip4 queries are answered or issued. Default is yes. .TP .B do\-ip6: \fI Enable or disable whether ip6 queries are answered or issued. Default is yes. If disabled, queries are not answered on IPv6, and queries are not sent on IPv6 to the internet nameservers. With this option you can disable the ipv6 transport for sending DNS traffic, it does not impact the contents of the DNS traffic, which may have ip4 and ip6 addresses in it. .TP +.B prefer\-ip4: \fI +If enabled, prefer IPv4 transport for sending DNS queries to internet +nameservers. Default is no. Useful if the IPv6 netblock the server has, +the entire /64 of that is not owned by one operator and the reputation of +the netblock /64 is an issue, using IPv4 then uses the IPv4 filters that +the upstream servers have. +.TP .B prefer\-ip6: \fI If enabled, prefer IPv6 transport for sending DNS queries to internet nameservers. Default is no. .TP .B do\-udp: \fI Enable or disable whether UDP queries are answered or issued. Default is yes. .TP .B do\-tcp: \fI Enable or disable whether TCP queries are answered or issued. Default is yes. .TP .B tcp\-mss: \fI Maximum segment size (MSS) of TCP socket on which the server responds to queries. Value lower than common MSS on Ethernet (1220 for example) will address path MTU problem. Note that not all platform supports socket option to set MSS (TCP_MAXSEG). Default is system default MSS determined by interface MTU and negotiation between server and client. .TP .B outgoing\-tcp\-mss: \fI Maximum segment size (MSS) of TCP socket for outgoing queries (from Unbound to other servers). Value lower than common MSS on Ethernet (1220 for example) will address path MTU problem. Note that not all platform supports socket option to set MSS (TCP_MAXSEG). Default is system default MSS determined by interface MTU and negotiation between Unbound and other servers. .TP .B tcp-idle-timeout: \fI\fR The period Unbound will wait for a query on a TCP connection. If this timeout expires Unbound closes the connection. This option defaults to 30000 milliseconds. When the number of free incoming TCP buffers falls below 50% of the total number configured, the option value used is progressively reduced, first to 1% of the configured value, then to 0.2% of the configured value if the number of free buffers falls below 35% of the total number configured, and finally to 0 if the number of free buffers falls below 20% of the total number configured. A minimum timeout of 200 milliseconds is observed regardless of the option value used. .TP +.B tcp-reuse-timeout: \fI\fR +The period Unbound will keep TCP persistent connections open to +authority servers. This option defaults to 60000 milliseconds. +.TP +.B max-reuse-tcp-queries: \fI\fR +The maximum number of queries that can be sent on a persistent TCP +connection. +This option defaults to 200 queries. +.TP +.B tcp-auth-query-timeout: \fI\fR +Timeout in milliseconds for TCP queries to auth servers. +This option defaults to 3000 milliseconds. +.TP .B edns-tcp-keepalive: \fI\fR Enable or disable EDNS TCP Keepalive. Default is no. .TP .B edns-tcp-keepalive-timeout: \fI\fR The period Unbound will wait for a query on a TCP connection when EDNS TCP Keepalive is active. If this timeout expires Unbound closes the connection. If the client supports the EDNS TCP Keepalive option, Unbound sends the timeout value to the client to encourage it to close the connection before the server times out. This option defaults to 120000 milliseconds. When the number of free incoming TCP buffers falls below 50% of the total number configured, the advertised timeout is progressively reduced to 1% of the configured value, then to 0.2% of the configured value if the number of free buffers falls below 35% of the total number configured, and finally to 0 if the number of free buffers falls below 20% of the total number configured. A minimum actual timeout of 200 milliseconds is observed regardless of the advertised timeout. .TP .B tcp\-upstream: \fI Enable or disable whether the upstream queries use TCP only for transport. -Default is no. Useful in tunneling scenarios. +Default is no. Useful in tunneling scenarios. If set to no you can specify +TCP transport only for selected forward or stub zones using forward-tcp-upstream +or stub-tcp-upstream respectively. .TP .B udp\-upstream\-without\-downstream: \fI Enable udp upstream even if do-udp is no. Default is no, and this does not change anything. Useful for TLS service providers, that want no udp downstream but use udp to fetch data upstream. .TP .B tls\-upstream: \fI Enabled or disable whether the upstream queries use TLS only for transport. Default is no. Useful in tunneling scenarios. The TLS contains plain DNS in TCP wireformat. The other server must support this (see \fBtls\-service\-key\fR). If you enable this, also configure a tls\-cert\-bundle or use tls\-win\-cert to load CA certs, otherwise the connections cannot be authenticated. This option enables TLS for all of them, but if you do not set this you can configure TLS specifically for some forward zones with forward\-tls\-upstream. And also with stub\-tls\-upstream. .TP .B ssl\-upstream: \fI Alternate syntax for \fBtls\-upstream\fR. If both are present in the config file the last is used. .TP .B tls\-service\-key: \fI -If enabled, the server provides TLS service on the TCP ports marked -implicitly or explicitly for TLS service with tls\-port. The file must -contain the private key for the TLS session, the public certificate is in -the tls\-service\-pem file and it must also be specified if tls\-service\-key -is specified. The default is "", turned off. Enabling or disabling -this service requires a restart (a reload is not enough), because the -key is read while root permissions are held and before chroot (if any). -The ports enabled implicitly or explicitly via \fBtls\-port:\fR do not provide -normal DNS TCP service. +If enabled, the server provides DNS-over-TLS or DNS-over-HTTPS service on the +TCP ports marked implicitly or explicitly for these services with tls\-port or +https\-port. The file must contain the private key for the TLS session, the +public certificate is in the tls\-service\-pem file and it must also be +specified if tls\-service\-key is specified. The default is "", turned off. +Enabling or disabling this service requires a restart (a reload is not enough), +because the key is read while root permissions are held and before chroot (if any). +The ports enabled implicitly or explicitly via \fBtls\-port:\fR and +\fBhttps\-port:\fR do not provide normal DNS TCP service. Unbound needs to be +compiled with libnghttp2 in order to provide DNS-over-HTTPS. .TP .B ssl\-service\-key: \fI Alternate syntax for \fBtls\-service\-key\fR. .TP .B tls\-service\-pem: \fI The public key certificate pem file for the tls service. Default is "", turned off. .TP .B ssl\-service\-pem: \fI Alternate syntax for \fBtls\-service\-pem\fR. .TP .B tls\-port: \fI The port number on which to provide TCP TLS service, default 853, only interfaces configured with that port number as @number get the TLS service. .TP .B ssl\-port: \fI Alternate syntax for \fBtls\-port\fR. .TP .B tls\-cert\-bundle: \fI If null or "", no file is used. Set it to the certificate bundle file, for example "/etc/pki/tls/certs/ca\-bundle.crt". These certificates are used for authenticating connections made to outside peers. For example auth\-zone -urls, and also DNS over TLS connections. +urls, and also DNS over TLS connections. It is read at start up before +permission drop and chroot. .TP .B ssl\-cert\-bundle: \fI Alternate syntax for \fBtls\-cert\-bundle\fR. .TP .B tls\-win\-cert: \fI Add the system certificates to the cert bundle certificates for authentication. If no cert bundle, it uses only these certificates. Default is no. On windows this option uses the certificates from the cert store. Use the tls\-cert\-bundle option on other systems. .TP .B tls\-additional\-port: \fI List portnumbers as tls\-additional\-port, and when interfaces are defined, eg. with the @port suffix, as this port number, they provide dns over TLS service. Can list multiple, each on a new statement. .TP .B tls-session-ticket-keys: \fI If not "", lists files with 80 bytes of random contents that are used to perform TLS session resumption for clients using the unbound server. These files contain the secret key for the TLS session tickets. First key use to encrypt and decrypt TLS session tickets. Other keys use to decrypt only. With this you can roll over to new keys, by generating a new first file and allowing decrypt of the old file by listing it after the first file for some time, after the wait clients are not using the old key any more and the old key can be removed. One way to create the file is dd if=/dev/random bs=1 count=80 of=ticket.dat The first 16 bytes should be different from the old one if you create a second key, that is the name used to identify the key. Then there is 32 bytes random data for an AES key and then 32 bytes random data for the HMAC key. .TP .B tls\-ciphers: \fI Set the list of ciphers to allow when serving TLS. Use "" for defaults, and that is the default. .TP .B tls\-ciphersuites: \fI Set the list of ciphersuites to allow when serving TLS. This is for newer TLS 1.3 connections. Use "" for defaults, and that is the default. .TP +.B pad\-responses: \fI +If enabled, TLS serviced queries that contained an EDNS Padding option will +cause responses padded to the closest multiple of the size specified in +\fBpad\-responses\-block\-size\fR. +Default is yes. +.TP +.B pad\-responses\-block\-size: \fI +The block size with which to pad responses serviced over TLS. Only responses +to padded queries will be padded. +Default is 468. +.TP +.B pad\-queries: \fI +If enabled, all queries sent over TLS upstreams will be padded to the closest +multiple of the size specified in \fBpad\-queries\-block\-size\fR. +Default is yes. +.TP +.B pad\-queries\-block\-size: \fI +The block size with which to pad queries sent over TLS upstreams. +Default is 128. +.TP +.B tls\-use\-sni: \fI +Enable or disable sending the SNI extension on TLS connections. +Default is yes. +Changing the value requires a reload. +.TP +.B https\-port: \fI +The port number on which to provide DNS-over-HTTPS service, default 443, only +interfaces configured with that port number as @number get the HTTPS service. +.TP +.B http\-endpoint: \fI +The HTTP endpoint to provide DNS-over-HTTPS service on. Default "/dns-query". +.TP +.B http\-max\-streams: \fI +Number used in the SETTINGS_MAX_CONCURRENT_STREAMS parameter in the HTTP/2 +SETTINGS frame for DNS-over-HTTPS connections. Default 100. +.TP +.B http\-query\-buffer\-size: \fI +Maximum number of bytes used for all HTTP/2 query buffers combined. These +buffers contain (partial) DNS queries waiting for request stream completion. +An RST_STREAM frame will be send to streams exceeding this limit. Default is 4 +megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, +megabytes or gigabytes (1024*1024 bytes in a megabyte). +.TP +.B http\-response\-buffer\-size: \fI +Maximum number of bytes used for all HTTP/2 response buffers combined. These +buffers contain DNS responses waiting to be written back to the clients. +An RST_STREAM frame will be send to streams exceeding this limit. Default is 4 +megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, +megabytes or gigabytes (1024*1024 bytes in a megabyte). +.TP +.B http\-nodelay: \fI +Set TCP_NODELAY socket option on sockets used to provide DNS-over-HTTPS service. +Ignored if the option is not available. Default is yes. +.TP +.B http\-notls\-downstream: \fI +Disable use of TLS for the downstream DNS-over-HTTP connections. Useful for +local back end servers. Default is no. +.TP .B use\-systemd: \fI Enable or disable systemd socket activation. Default is no. .TP .B do\-daemonize: \fI Enable or disable whether the unbound server forks into the background as a daemon. Set the value to \fIno\fR when unbound runs as systemd service. Default is yes. .TP .B tcp\-connection\-limit: \fI Allow up to \fIlimit\fR simultaneous TCP connections from the given netblock. When at the limit, further connections are accepted but closed immediately. This option is experimental at this time. .TP .B access\-control: \fI The netblock is given as an IP4 or IP6 address with /size appended for a classless network block. The action can be \fIdeny\fR, \fIrefuse\fR, \fIallow\fR, \fIallow_setrd\fR, \fIallow_snoop\fR, \fIdeny_non_local\fR or \fIrefuse_non_local\fR. The most specific netblock match is used, if none match \fIdeny\fR is used. The order of the access\-control statements therefore does not matter. .IP The action \fIdeny\fR stops queries from hosts from that netblock. .IP The action \fIrefuse\fR stops queries too, but sends a DNS rcode REFUSED error message back. .IP The action \fIallow\fR gives access to clients from that netblock. It gives only access for recursion clients (which is what almost all clients need). Nonrecursive queries are refused. .IP The \fIallow\fR action does allow nonrecursive queries to access the local\-data that is configured. The reason is that this does not involve the unbound server recursive lookup algorithm, and static data is served in the reply. This supports normal operations where nonrecursive queries are made for the authoritative data. For nonrecursive queries any replies from the dynamic cache are refused. .IP The \fIallow_setrd\fR action ignores the recursion desired (RD) bit and treats all requests as if the recursion desired bit is set. Note that this behavior violates RFC 1034 which states that a name server should never perform recursive service unless asked via the RD bit since this interferes with trouble shooting of name servers and their databases. This prohibited behavior may be useful if another DNS server must forward requests for specific zones to a resolver DNS server, but only supports stub domains and sends queries to the resolver DNS server with the RD bit cleared. .IP The action \fIallow_snoop\fR gives nonrecursive access too. This give both recursive and non recursive access. The name \fIallow_snoop\fR refers to cache snooping, a technique to use nonrecursive queries to examine the cache contents (for malicious acts). However, nonrecursive queries can also be a valuable debugging tool (when you want to examine the cache contents). In that case use \fIallow_snoop\fR for your administration host. .IP By default only localhost is \fIallow\fRed, the rest is \fIrefuse\fRd. The default is \fIrefuse\fRd, because that is protocol\-friendly. The DNS protocol is not designed to handle dropped packets due to policy, and dropping may result in (possibly excessive) retried queries. .IP The deny_non_local and refuse_non_local settings are for hosts that are only allowed to query for the authoritative local\-data, they are not allowed full recursion but only the static data. With deny_non_local, messages that are disallowed are dropped, with refuse_non_local they receive error code REFUSED. .TP .B access\-control\-tag: \fI <"list of tags"> Assign tags to access-control elements. Clients using this access control element use localzones that are tagged with one of these tags. Tags must be defined in \fIdefine\-tags\fR. Enclose list of tags in quotes ("") and put spaces between tags. If access\-control\-tag is configured for a netblock that does not have an access\-control, an access\-control element with action \fIallow\fR is configured for this netblock. .TP .B access\-control\-tag\-action: \fI Set action for particular tag for given access control element. If you have multiple tag values, the tag used to lookup the action is the first tag match between access\-control\-tag and local\-zone\-tag where "first" comes from the order of the define-tag values. .TP .B access\-control\-tag\-data: \fI <"resource record string"> Set redirect data for particular tag for given access control element. .TP .B access\-control\-view: \fI Set view for given access control element. .TP .B chroot: \fI If chroot is enabled, you should pass the configfile (from the commandline) as a full path from the original root. After the chroot has been performed the now defunct portion of the config file path is removed to be able to reread the config after a reload. .IP All other file paths (working dir, logfile, roothints, and key files) can be specified in several ways: as an absolute path relative to the new root, as a relative path to the working directory, or as an absolute path relative to the original root. In the last case the path is adjusted to remove the unused portion. .IP The pidfile can be either a relative path to the working directory, or an absolute path relative to the original root. It is written just prior to chroot and dropping permissions. This allows the pidfile to be -/var/run/unbound.pid and the chroot to be /var/unbound, for example. +/var/run/unbound.pid and the chroot to be /var/unbound, for example. Note that +Unbound is not able to remove the pidfile after termination when it is located +outside of the chroot directory. .IP -Additionally, unbound may need to access /dev/random (for entropy) +Additionally, unbound may need to access /dev/urandom (for entropy) from inside the chroot. .IP If given a chroot is done to the given directory. By default chroot is -enabled and the default is "/var/unbound". If you give "" no +enabled and the default is "@UNBOUND_CHROOT_DIR@". If you give "" no chroot is performed. .TP .B username: \fI If given, after binding the port the user privileges are dropped. Default is -"unbound". If you give username: "" no user change is performed. +"@UNBOUND_USERNAME@". If you give username: "" no user change is performed. .IP If this user is not capable of binding the port, reloads (by signal HUP) will still retain the opened ports. If you change the port number in the config file, and that new port number requires privileges, then a reload will fail; a restart is needed. .TP .B directory: \fI -Sets the working directory for the program. Default is "/var/unbound". +Sets the working directory for the program. Default is "@UNBOUND_RUN_DIR@". On Windows the string "%EXECUTABLE%" tries to change to the directory that unbound.exe resides in. If you give a server: directory: dir before include: file statements then those includes can be relative to the working directory. .TP .B logfile: \fI If "" is given, logging goes to stderr, or nowhere once daemonized. The logfile is appended to, in the following format: .nf [seconds since 1970] unbound[pid:tid]: type: message. .fi If this option is given, the use\-syslog is option is set to "no". The logfile is reopened (for append) when the config file is reread, on SIGHUP. .TP .B use\-syslog: \fI Sets unbound to send log messages to the syslogd, using \fIsyslog\fR(3). The log facility LOG_DAEMON is used, with identity "unbound". The logfile setting is overridden when use\-syslog is turned on. The default is to log to syslog. .TP .B log\-identity: \fI If "" is given (default), then the name of the executable, usually "unbound" is used to report to the log. Enter a string to override it with that, which is useful on systems that run more than one instance of unbound, with different configurations, so that the logs can be easily distinguished against. .TP .B log\-time\-ascii: \fI Sets logfile lines to use a timestamp in UTC ascii. Default is no, which prints the seconds since 1970 in brackets. No effect if using syslog, in that case syslog formats the timestamp printed into the log files. .TP .B log\-queries: \fI Prints one line per query to the log, with the log timestamp and IP address, name, type and class. Default is no. Note that it takes time to print these lines which makes the server (significantly) slower. Odd (nonprintable) characters in names are printed as '?'. .TP .B log\-replies: \fI Prints one line per reply to the log, with the log timestamp and IP address, name, type, class, return code, time to resolve, from cache and response size. Default is no. Note that it takes time to print these lines which makes the server (significantly) slower. Odd (nonprintable) characters in names are printed as '?'. .TP .B log\-tag\-queryreply: \fI Prints the word 'query' and 'reply' with log\-queries and log\-replies. This makes filtering logs easier. The default is off (for backwards compatibility). .TP .B log\-local\-actions: \fI Print log lines to inform about local zone actions. These lines are like the local\-zone type inform prints out, but they are also printed for the other types of local zones. .TP .B log\-servfail: \fI Print log lines that say why queries return SERVFAIL to clients. This is separate from the verbosity debug logs, much smaller, and printed at the error level, not the info level of debug info from verbosity. .TP .B pidfile: \fI -The process id is written to the file. Default is "/var/unbound/unbound.pid". +The process id is written to the file. Default is "@UNBOUND_PIDFILE@". So, .nf -kill \-HUP `cat /var/unbound/unbound.pid` +kill \-HUP `cat @UNBOUND_PIDFILE@` .fi triggers a reload, .nf -kill \-TERM `cat /var/unbound/unbound.pid` +kill \-TERM `cat @UNBOUND_PIDFILE@` .fi gracefully terminates. .TP .B root\-hints: \fI Read the root hints from this file. Default is nothing, using builtin hints for the IN class. The file has the format of zone files, with root nameserver names and addresses only. The default may become outdated, when servers change, therefore it is good practice to use a root\-hints file. .TP .B hide\-identity: \fI If enabled id.server and hostname.bind queries are refused. .TP .B identity: \fI Set the identity to report. If set to "", the default, then the hostname of the server is returned. .TP .B hide\-version: \fI If enabled version.server and version.bind queries are refused. .TP .B version: \fI Set the version to report. If set to "", the default, then the package version is returned. .TP +.B hide\-http\-user\-agent: \fI +If enabled the HTTP header User-Agent is not set. Use with caution as some +webserver configurations may reject HTTP requests lacking this header. +If needed, it is better to explicitly set the +.B http\-user\-agent +below. +.TP +.B http\-user\-agent: \fI +Set the HTTP User-Agent header for outgoing HTTP requests. If set to "", +the default, then the package name and version are used. +.TP +.B nsid:\fR +Add the specified nsid to the EDNS section of the answer when queried +with an NSID EDNS enabled packet. As a sequence of hex characters or +with ascii_ prefix and then an ascii string. +.TP .B hide\-trustanchor: \fI If enabled trustanchor.unbound queries are refused. .TP .B target\-fetch\-policy: \fI<"list of numbers"> Set the target fetch policy used by unbound to determine if it should fetch nameserver target addresses opportunistically. The policy is described per dependency depth. .IP The number of values determines the maximum dependency depth that unbound will pursue in answering a query. A value of \-1 means to fetch all targets opportunistically for that dependency depth. A value of 0 means to fetch on demand only. A positive value fetches that many targets opportunistically. .IP Enclose the list between quotes ("") and put spaces between numbers. The default is "3 2 1 0 0". Setting all zeroes, "0 0 0 0 0" gives behaviour closer to that of BIND 9, while setting "\-1 \-1 \-1 \-1 \-1" gives behaviour rumoured to be closer to that of BIND 8. .TP .B harden\-short\-bufsize: \fI -Very small EDNS buffer sizes from queries are ignored. Default is off, since -it is legal protocol wise to send these, and unbound tries to give very -small answers to these queries, where possible. +Very small EDNS buffer sizes from queries are ignored. Default is on, as +described in the standard. .TP .B harden\-large\-queries: \fI Very large queries are ignored. Default is off, since it is legal protocol wise to send these, and could be necessary for operation if TSIG or EDNS payload is very large. .TP .B harden\-glue: \fI -Will trust glue only if it is within the servers authority. Default is on. +Will trust glue only if it is within the servers authority. Default is yes. .TP .B harden\-dnssec\-stripped: \fI Require DNSSEC data for trust\-anchored zones, if such data is absent, the zone becomes bogus. If turned off, and no DNSSEC data is received (or the DNSKEY data fails to validate), then the zone is made insecure, this behaves like there is no trust anchor. You could turn this off if you are sometimes behind an intrusive firewall (of some sort) that removes DNSSEC data from packets, or a zone changes from signed to unsigned to badly signed often. If turned off you run the risk of a -downgrade attack that disables security for a zone. Default is on. +downgrade attack that disables security for a zone. Default is yes. .TP .B harden\-below\-nxdomain: \fI From RFC 8020 (with title "NXDOMAIN: There Really Is Nothing Underneath"), returns nxdomain to queries for a name below another name that is already known to be nxdomain. DNSSEC mandates noerror for empty nonterminals, hence this is possible. Very old software might return nxdomain for empty nonterminals (that usually happen for reverse IP address lookups), and thus may be incompatible with this. To try to avoid this only DNSSEC-secure nxdomains are used, because the old software does not -have DNSSEC. Default is on. +have DNSSEC. Default is yes. The nxdomain must be secure, this means nsec3 with optout is insufficient. .TP .B harden\-referral\-path: \fI Harden the referral path by performing additional queries for infrastructure data. Validates the replies if trust anchors are configured and the zones are signed. This enforces DNSSEC validation on nameserver NS sets and the nameserver addresses that are encountered on the referral path to the answer. Default no, because it burdens the authority servers, and it is not RFC standard, and could lead to performance problems because of the extra query load that is generated. Experimental option. If you enable it consider adding more numbers after the target\-fetch\-policy to increase the max depth that is checked to. .TP .B harden\-algo\-downgrade: \fI Harden against algorithm downgrade when multiple algorithms are advertised in the DS record. If no, allows the weakest algorithm to validate the zone. Default is no. Zone signers must produce zones that allow this feature to work, but sometimes they do not, and turning this option off avoids that validation failure. .TP .B use\-caps\-for\-id: \fI Use 0x20\-encoded random bits in the query to foil spoof attempts. This perturbs the lowercase and uppercase of query names sent to authority servers and checks if the reply still has the correct casing. Disabled by default. This feature is an experimental implementation of draft dns\-0x20. .TP -.B caps\-whitelist: \fI -Whitelist the domain so that it does not receive caps\-for\-id perturbed +.B caps\-exempt: \fI +Exempt the domain so that it does not receive caps\-for\-id perturbed queries. For domains that do not support 0x20 and also fail with fallback because they keep sending different answers, like some load balancers. Can be given multiple times, for different domains. .TP +.B caps\-whitelist: \fI +Alternate syntax for \fBcaps\-exempt\fR. +.TP .B qname\-minimisation: \fI Send minimum amount of information to upstream servers to enhance privacy. Only send minimum required labels of the QNAME and set QTYPE to A when possible. Best effort approach; full QNAME and original QTYPE will be sent when upstream replies with a RCODE other than NOERROR, except when receiving NXDOMAIN from a DNSSEC signed zone. Default is yes. .TP .B qname\-minimisation\-strict: \fI QNAME minimisation in strict mode. Do not fall-back to sending full QNAME to potentially broken nameservers. A lot of domains will not be resolvable when this option in enabled. Only use if you know what you are doing. -This option only has effect when qname-minimisation is enabled. Default is off. +This option only has effect when qname-minimisation is enabled. Default is no. .TP .B aggressive\-nsec: \fI Aggressive NSEC uses the DNSSEC NSEC chain to synthesize NXDOMAIN and other denials, using information from previous NXDOMAINs answers. Default is no. It helps to reduce the query rate towards targets that get a very high nonexistent name lookup rate. .TP .B private\-address: \fI Give IPv4 of IPv6 addresses or classless subnets. These are addresses on your private network, and are not allowed to be returned for public internet names. Any occurrence of such addresses are removed from DNS answers. Additionally, the DNSSEC validator may mark the answers bogus. This protects against so\-called DNS Rebinding, where a user browser is turned into a network proxy, allowing remote access through the browser to other parts of your private network. Some names can be allowed to contain your private addresses, by default all the \fBlocal\-data\fR that you configured is allowed to, and you can specify additional names using \fBprivate\-domain\fR. No private addresses are enabled by default. We consider to enable this for the RFC1918 private IP address space by default in later releases. That would enable private addresses for 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16 fd00::/8 and fe80::/10, since the RFC standards say these addresses should not be visible on the public internet. Turning on 127.0.0.0/8 would hinder many spamblocklists as they use that. Adding ::ffff:0:0/96 stops IPv4-mapped IPv6 addresses from bypassing the filter. .TP .B private\-domain: \fI Allow this domain, and all its subdomains to contain private addresses. Give multiple times to allow multiple domain names to contain private addresses. Default is none. .TP .B unwanted\-reply\-threshold: \fI If set, a total number of unwanted replies is kept track of in every thread. When it reaches the threshold, a defensive action is taken and a warning is printed to the log. The defensive action is to clear the rrset and message caches, hopefully flushing away any poison. A value of 10 million is suggested. Default is 0 (turned off). .TP .B do\-not\-query\-address: \fI Do not query the given IP address. Can be IP4 or IP6. Append /num to indicate a classless delegation netblock, for example like 10.2.3.4/24 or 2001::11/64. .TP .B do\-not\-query\-localhost: \fI If yes, localhost is added to the do\-not\-query\-address entries, both IP6 ::1 and IP4 127.0.0.1/8. If no, then localhost can be used to send queries to. Default is yes. .TP .B prefetch: \fI If yes, message cache elements are prefetched before they expire to keep the cache up to date. Default is no. Turning it on gives about 10 percent more traffic and load on the machine, but popular items do not expire from the cache. .TP .B prefetch\-key: \fI If yes, fetch the DNSKEYs earlier in the validation process, when a DS record is encountered. This lowers the latency of requests. It does use a little more CPU. Also if the cache is set to 0, it is no use. Default is no. .TP .B deny\-any: \fI If yes, deny queries of type ANY with an empty response. Default is no. If disabled, unbound responds with a short list of resource records if some can be found in the cache and makes the upstream type ANY query if there are none. .TP .B rrset\-roundrobin: \fI If yes, Unbound rotates RRSet order in response (the random number is taken -from the query ID, for speed and thread safety). Default is no. +from the query ID, for speed and thread safety). Default is yes. .TP .B minimal-responses: \fI -If yes, Unbound doesn't insert authority/additional sections into response +If yes, Unbound does not insert authority/additional sections into response messages when those sections are not required. This reduces response size significantly, and may avoid TCP fallback for some responses. This may cause a slight speedup. The default is yes, even though the DNS protocol RFCs mandate these sections, and the additional content could be of use and save roundtrips for clients. Because they are not used, and the saved roundtrips are easier saved with prefetch, whilst this is faster. .TP .B disable-dnssec-lame-check: \fI If true, disables the DNSSEC lameness check in the iterator. This check sees if RRSIGs are present in the answer, when dnssec is expected, and retries another authority if RRSIGs are unexpectedly missing. The validator will insist in RRSIGs for DNSSEC signed domains regardless of this setting, if a trust anchor is loaded. .TP .B module\-config: \fI<"module names"> Module configuration, a list of module names separated by spaces, surround -the string with quotes (""). The modules can be validator, iterator. -Setting this to "iterator" will result in a non\-validating server. -Setting this to "validator iterator" will turn on DNSSEC validation. -The ordering of the modules is important. -You must also set trust\-anchors for validation to be useful. -The default is "validator iterator". When the server is built with -EDNS client subnet support the default is "subnetcache validator iterator". +the string with quotes (""). The modules can be \fIrespip\fR, +\fIvalidator\fR, or \fIiterator\fR (and possibly more, see below). +Setting this to just "\fIiterator\fR" will result in a non\-validating +server. +Setting this to "\fIvalidator iterator\fR" will turn on DNSSEC validation. +The ordering of the modules is significant, the order decides the +order of processing. +You must also set \fItrust\-anchors\fR for validation to be useful. +Adding \fIrespip\fR to the front will cause RPZ processing to be done on +all queries. +The default is "\fIvalidator iterator\fR". +.IP +When the server is built with +EDNS client subnet support the default is "\fIsubnetcache validator +iterator\fR". Most modules that need to be listed here have to be listed at the beginning -of the line. The cachedb module has to be listed just before the iterator. +of the line. The subnetcachedb module has to be listed just before +the iterator. The python module can be listed in different places, it then processes the -output of the module it is just before. +output of the module it is just before. The dynlib module can be listed pretty +much anywhere, it is only a very thin wrapper that allows dynamic libraries to +run in its place. .TP .B trust\-anchor\-file: \fI File with trusted keys for validation. Both DS and DNSKEY entries can appear in the file. The format of the file is the standard DNS Zone file format. Default is "", or no trust anchor file. .TP .B auto\-trust\-anchor\-file: \fI File with trust anchor for one zone, which is tracked with RFC5011 probes. -The probes are several times per month, thus the machine must be online +The probes are run several times per month, thus the machine must be online frequently. The initial file can be one with contents as described in \fBtrust\-anchor\-file\fR. The file is written to when the anchor is updated, so the unbound user must have write permission. Write permission to the file, but also to the directory it is in (to create a temporary file, which is necessary to deal with filesystem full events), it must also be inside the chroot (if that is used). .TP .B trust\-anchor: \fI<"Resource Record"> A DS or DNSKEY RR for a key to use for validation. Multiple entries can be given to specify multiple trusted keys, in addition to the trust\-anchor\-files. The resource record is entered in the same format as 'dig' or 'drill' prints them, the same format as in the zone file. Has to be on a single line, with "" around it. A TTL can be specified for ease of cut and paste, but is ignored. A class can be specified, but class IN is default. .TP .B trusted\-keys\-file: \fI File with trusted keys for validation. Specify more than one file with several entries, one file per entry. Like \fBtrust\-anchor\-file\fR but has a different file format. Format is BIND\-9 style format, the trusted\-keys { name flag proto algo "key"; }; clauses are read. It is possible to use wildcards with this statement, the wildcard is expanded on start and on reload. .TP .B trust\-anchor\-signaling: \fI -Send RFC8145 key tag query after trust anchor priming. Default is on. +Send RFC8145 key tag query after trust anchor priming. Default is yes. .TP .B root\-key\-sentinel: \fI -Root key trust anchor sentinel. Default is on. -.TP -.B dlv\-anchor\-file: \fI -This option was used during early days DNSSEC deployment when no parent-side -DS record registrations were easily available. Nowadays, it is best to have -DS records registered with the parent zone (many top level zones are signed). -File with trusted keys for DLV (DNSSEC Lookaside Validation). Both DS and -DNSKEY entries can be used in the file, in the same format as for -\fItrust\-anchor\-file:\fR statements. Only one DLV can be configured, more -would be slow. The DLV configured is used as a root trusted DLV, this -means that it is a lookaside for the root. Default is "", or no dlv anchor -file. DLV is going to be decommissioned. Please do not use it any more. -.TP -.B dlv\-anchor: \fI<"Resource Record"> -Much like trust\-anchor, this is a DLV anchor with the DS or DNSKEY inline. -DLV is going to be decommissioned. Please do not use it any more. +Root key trust anchor sentinel. Default is yes. .TP .B domain\-insecure: \fI Sets domain name to be insecure, DNSSEC chain of trust is ignored towards the domain name. So a trust anchor above the domain name can not make the domain secure with a DS record, such a DS record is then ignored. -Also keys from DLV are ignored for the domain. Can be given multiple times +Can be given multiple times to specify multiple domains that are treated as if unsigned. If you set trust anchors for the domain they override this setting (and the domain is secured). .IP This can be useful if you want to make sure a trust anchor for external lookups does not affect an (unsigned) internal domain. A DS record externally can create validation failures for that internal domain. .TP .B val\-override\-date: \fI Default is "" or "0", which disables this debugging feature. If enabled by giving a RRSIG style date, that date is used for verifying RRSIG inception and expiration dates, instead of the current date. Do not set this unless you are debugging signature inception and expiration. The value \-1 ignores the date altogether, useful for some special applications. .TP .B val\-sig\-skew\-min: \fI Minimum number of seconds of clock skew to apply to validated signatures. A value of 10% of the signature lifetime (expiration \- inception) is used, capped by this setting. Default is 3600 (1 hour) which allows for daylight savings differences. Lower this value for more strict checking of short lived signatures. .TP .B val\-sig\-skew\-max: \fI Maximum number of seconds of clock skew to apply to validated signatures. A value of 10% of the signature lifetime (expiration \- inception) is used, capped by this setting. Default is 86400 (24 hours) which allows for timezone setting problems in stable domains. Setting both min and max very low disables the clock skew allowances. Setting both min and max very high makes the validator check the signature timestamps less strictly. .TP +.B val\-max\-restart: \fI +The maximum number the validator should restart validation with +another authority in case of failed validation. Default is 5. +.TP .B val\-bogus\-ttl: \fI The time to live for bogus data. This is data that has failed validation; due to invalid signatures or other checks. The TTL from that data cannot be trusted, and this value is used instead. The value is in seconds, default 60. The time interval prevents repeated revalidation of bogus data. .TP .B val\-clean\-additional: \fI Instruct the validator to remove data from the additional section of secure messages that are not signed properly. Messages that are insecure, bogus, indeterminate or unchecked are not affected. Default is yes. Use this setting to protect the users that rely on this validator for authentication from potentially bad data in the additional section. .TP .B val\-log\-level: \fI Have the validator print validation failures to the log. Regardless of the verbosity setting. Default is 0, off. At 1, for every user query that fails a line is printed to the logs. This way you can monitor what happens with validation. Use a diagnosis tool, such as dig or drill, to find out why validation is failing for these queries. At 2, not only the query that failed is printed but also the reason why unbound thought it was wrong and which server sent the faulty data. .TP .B val\-permissive\-mode: \fI Instruct the validator to mark bogus messages as indeterminate. The security checks are performed, but if the result is bogus (failed security), the reply is not withheld from the client with SERVFAIL as usual. The client receives the bogus data. For messages that are found to be secure the AD bit is set in replies. Also logging is performed as for full validation. The default value is "no". .TP .B ignore\-cd\-flag: \fI Instruct unbound to ignore the CD flag from clients and refuse to return bogus answers to them. Thus, the CD (Checking Disabled) flag does not disable checking any more. This is useful if legacy (w2008) servers that set the CD flag but cannot validate DNSSEC themselves are the clients, and then unbound provides them with DNSSEC protection. The default value is "no". .TP .B serve\-expired: \fI If enabled, unbound attempts to serve old responses from cache with a -TTL of 0 in the response without waiting for the actual resolution to finish. -The actual resolution answer ends up in the cache later on. Default is "no". +TTL of \fBserve\-expired\-reply\-ttl\fR in the response without waiting for the +actual resolution to finish. The actual resolution answer ends up in the cache +later on. Default is "no". .TP .B serve\-expired\-ttl: \fI Limit serving of expired responses to configured seconds after expiration. 0 -disables the limit. This option only applies when \fBserve\-expired\fR is -enabled. The default is 0. +disables the limit. This option only applies when \fBserve\-expired\fR is +enabled. A suggested value per RFC 8767 is between +86400 (1 day) and 259200 (3 days). The default is 0. .TP .B serve\-expired\-ttl\-reset: \fI Set the TTL of expired records to the \fBserve\-expired\-ttl\fR value after a -failed attempt to retrieve the record from upstream. This makes sure that the -expired records will be served as long as there are queries for it. Default is +failed attempt to retrieve the record from upstream. This makes sure that the +expired records will be served as long as there are queries for it. Default is "no". .TP +.B serve\-expired\-reply\-ttl: \fI +TTL value to use when replying with expired data. If +\fBserve\-expired\-client\-timeout\fR is also used then it is RECOMMENDED to +use 30 as the value (RFC 8767). The default is 30. +.TP +.B serve\-expired\-client\-timeout: \fI +Time in milliseconds before replying to the client with expired data. This +essentially enables the serve-stale behavior as specified in +RFC 8767 that first tries to resolve before immediately +responding with expired data. A recommended value per +RFC 8767 is 1800. Setting this to 0 will disable this +behavior. Default is 0. +.TP +.B serve\-original\-ttl: \fI +If enabled, unbound will always return the original TTL as received from +the upstream name server rather than the decrementing TTL as +stored in the cache. This feature may be useful if unbound serves as a +front-end to a hidden authoritative name server. Enabling this feature does +not impact cache expiry, it only changes the TTL unbound embeds in responses to +queries. Note that enabling this feature implicitly disables enforcement of +the configured minimum and maximum TTL, as it is assumed users who enable this +feature do not want unbound to change the TTL obtained from an upstream server. +Thus, the values set using \fBcache\-min\-ttl\fR and \fBcache\-max\-ttl\fR are +ignored. +Default is "no". +.TP .B val\-nsec3\-keysize\-iterations: \fI<"list of values"> List of keysize and iteration count values, separated by spaces, surrounded -by quotes. Default is "1024 150 2048 500 4096 2500". This determines the +by quotes. Default is "1024 150 2048 150 4096 150". This determines the maximum allowed NSEC3 iteration count before a message is simply marked insecure instead of performing the many hashing iterations. The list must be in ascending order and have at least one entry. If you set it to "1024 65535" there is no restriction to NSEC3 iteration values. This table must be kept short; a very long list could cause slower operation. .TP +.B zonemd\-permissive\-mode: \fI +If enabled the ZONEMD verification failures are only logged and do not cause +the zone to be blocked and only return servfail. Useful for testing out +if it works, or if the operator only wants to be notified of a problem without +disrupting service. Default is no. +.TP .B add\-holddown: \fI Instruct the \fBauto\-trust\-anchor\-file\fR probe mechanism for RFC5011 autotrust updates to add new trust anchors only after they have been visible for this time. Default is 30 days as per the RFC. .TP .B del\-holddown: \fI Instruct the \fBauto\-trust\-anchor\-file\fR probe mechanism for RFC5011 autotrust updates to remove revoked trust anchors after they have been kept in the revoked list for this long. Default is 30 days as per the RFC. .TP .B keep\-missing: \fI Instruct the \fBauto\-trust\-anchor\-file\fR probe mechanism for RFC5011 autotrust updates to remove missing trust anchors after they have been unseen for this long. This cleans up the state file if the target zone does not perform trust anchor revocation, so this makes the auto probe mechanism work with zones that perform regular (non\-5011) rollovers. The default is 366 days. The value 0 does not remove missing anchors, as per the RFC. .TP .B permit\-small\-holddown: \fI Debug option that allows the autotrust 5011 rollover timers to assume very small values. Default is no. .TP .B key\-cache\-size: \fI Number of bytes size of the key cache. Default is 4 megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes or gigabytes (1024*1024 bytes in a megabyte). .TP .B key\-cache\-slabs: \fI Number of slabs in the key cache. Slabs reduce lock contention by threads. Must be set to a power of 2. Setting (close) to the number of cpus is a reasonable guess. .TP .B neg\-cache\-size: \fI Number of bytes size of the aggressive negative cache. Default is 1 megabyte. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes or gigabytes (1024*1024 bytes in a megabyte). .TP .B unblock\-lan\-zones: \fI Default is disabled. If enabled, then for private address space, the reverse lookups are no longer filtered. This allows unbound when running as dns service on a host where it provides service for that host, to put out all of the queries for the 'lan' upstream. When enabled, only localhost, 127.0.0.1 reverse and ::1 reverse zones are configured with default local zones. Disable the option when unbound is running as a (DHCP-) DNS network resolver for a group of machines, where such lookups should be filtered (RFC compliance), this also stops potential data leakage about the local network to the upstream DNS servers. .TP .B insecure\-lan\-zones: \fI Default is disabled. If enabled, then reverse lookups in private address space are not validated. This is usually required whenever \fIunblock\-lan\-zones\fR is used. .TP .B local\-zone: \fI Configure a local zone. The type determines the answer to give if there is no match from local\-data. The types are deny, refuse, static, transparent, redirect, nodefault, typetransparent, inform, inform_deny, -inform_redirect, always_transparent, always_refuse, always_nxdomain, noview, +inform_redirect, always_transparent, always_refuse, always_nxdomain, always_null, noview, and are explained below. After that the default settings are listed. Use local\-data: to enter data into the local zone. Answers for local zones are authoritative DNS answers. By default the zones are class IN. .IP If you need more complicated authoritative data, with referrals, wildcards, CNAME/DNAME support, or DNSSEC authoritative service, setup a stub\-zone for it as detailed in the stub zone section below. .TP 10 \h'5'\fIdeny\fR Do not send an answer, drop the query. If there is a match from local data, the query is answered. .TP 10 \h'5'\fIrefuse\fR Send an error message reply, with rcode REFUSED. If there is a match from local data, the query is answered. .TP 10 \h'5'\fIstatic\fR If there is a match from local data, the query is answered. Otherwise, the query is answered with nodata or nxdomain. For a negative answer a SOA is included in the answer if present as local\-data for the zone apex domain. .TP 10 \h'5'\fItransparent\fR If there is a match from local data, the query is answered. Otherwise if the query has a different name, the query is resolved normally. If the query is for a name given in localdata but no such type of data is given in localdata, then a noerror nodata answer is returned. If no local\-zone is given local\-data causes a transparent zone to be created by default. .TP 10 \h'5'\fItypetransparent\fR If there is a match from local data, the query is answered. If the query is for a different name, or for the same name but for a different type, the query is resolved normally. So, similar to transparent but types that are not listed in local data are resolved normally, so if an A record is in the local data that does not cause a nodata reply for AAAA queries. .TP 10 \h'5'\fIredirect\fR The query is answered from the local data for the zone name. There may be no local data beneath the zone name. This answers queries for the zone, and all subdomains of the zone with the local data for the zone. It can be used to redirect a domain to return a different address record to the end user, with local\-zone: "example.com." redirect and local\-data: "example.com. A 127.0.0.1" queries for www.example.com and www.foo.example.com are redirected, so that users with web browsers cannot access sites with suffix example.com. .TP 10 \h'5'\fIinform\fR The query is answered normally, same as transparent. The client IP address (@portnumber) is printed to the logfile. The log message is: timestamp, unbound-pid, info: zonename inform IP@port queryname type class. This option can be used for normal resolution, but machines looking up infected names are logged, eg. to run antivirus on them. .TP 10 \h'5'\fIinform_deny\fR The query is dropped, like 'deny', and logged, like 'inform'. Ie. find infected machines without answering the queries. .TP 10 \h'5'\fIinform_redirect\fR The query is redirected, like 'redirect', and logged, like 'inform'. Ie. answer queries with fixed data and also log the machines that ask. .TP 10 \h'5'\fIalways_transparent\fR Like transparent, but ignores local data and resolves normally. .TP 10 \h'5'\fIalways_refuse\fR Like refuse, but ignores local data and refuses the query. .TP 10 \h'5'\fIalways_nxdomain\fR Like static, but ignores local data and returns nxdomain for the query. .TP 10 +\h'5'\fIalways_nodata\fR +Like static, but ignores local data and returns nodata for the query. +.TP 10 +\h'5'\fIalways_deny\fR +Like deny, but ignores local data and drops the query. +.TP 10 +\h'5'\fIalways_null\fR +Always returns 0.0.0.0 or ::0 for every name in the zone. Like redirect +with zero data for A and AAAA. Ignores local data in the zone. Used for +some block lists. +.TP 10 \h'5'\fInoview\fR Breaks out of that view and moves towards the global local zones for answer to the query. If the view first is no, it'll resolve normally. If view first is enabled, it'll break perform that step and check the global answers. For when the view has view specific overrides but some zone has to be answered from global local zone contents. .TP 10 \h'5'\fInodefault\fR Used to turn off default contents for AS112 zones. The other types also turn off default contents for the zone. The 'nodefault' option has no other effect than turning off default contents for the given zone. Use \fInodefault\fR if you use exactly that zone, if you want to use a subzone, use \fItransparent\fR. .P -The default zones are localhost, reverse 127.0.0.1 and ::1, the onion, test, -invalid and the AS112 zones. The AS112 zones are reverse DNS zones for -private use and reserved IP addresses for which the servers on the internet -cannot provide correct answers. They are configured by default to give -nxdomain (no reverse information) answers. The defaults can be turned off -by specifying your own local\-zone of that name, or using the 'nodefault' -type. Below is a list of the default zone contents. +The default zones are localhost, reverse 127.0.0.1 and ::1, the home.arpa, +the onion, test, invalid and the AS112 zones. The AS112 zones are reverse +DNS zones for private use and reserved IP addresses for which the servers +on the internet cannot provide correct answers. They are configured by +default to give nxdomain (no reverse information) answers. The defaults +can be turned off by specifying your own local\-zone of that name, or +using the 'nodefault' type. Below is a list of the default zone contents. .TP 10 \h'5'\fIlocalhost\fR The IP4 and IP6 localhost information is given. NS and SOA records are provided for completeness and to satisfy some DNS update tools. Default content: .nf local\-zone: "localhost." redirect local\-data: "localhost. 10800 IN NS localhost." local\-data: "localhost. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" local\-data: "localhost. 10800 IN A 127.0.0.1" local\-data: "localhost. 10800 IN AAAA ::1" .fi .TP 10 \h'5'\fIreverse IPv4 loopback\fR Default content: .nf local\-zone: "127.in\-addr.arpa." static local\-data: "127.in\-addr.arpa. 10800 IN NS localhost." local\-data: "127.in\-addr.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" local\-data: "1.0.0.127.in\-addr.arpa. 10800 IN PTR localhost." .fi .TP 10 \h'5'\fIreverse IPv6 loopback\fR Default content: .nf local\-zone: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0. 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." static local\-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0. 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN NS localhost." local\-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0. 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" local\-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0. 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN PTR localhost." .fi .TP 10 +\h'5'\fIhome.arpa (RFC 8375)\fR +Default content: +.nf +local\-zone: "home.arpa." static +local\-data: "home.arpa. 10800 IN NS localhost." +local\-data: "home.arpa. 10800 IN + SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" +.fi +.TP 10 \h'5'\fIonion (RFC 7686)\fR Default content: .nf local\-zone: "onion." static local\-data: "onion. 10800 IN NS localhost." local\-data: "onion. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" .fi .TP 10 -\h'5'\fItest (RFC 2606)\fR +\h'5'\fItest (RFC 6761)\fR Default content: .nf local\-zone: "test." static local\-data: "test. 10800 IN NS localhost." local\-data: "test. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" .fi .TP 10 -\h'5'\fIinvalid (RFC 2606)\fR +\h'5'\fIinvalid (RFC 6761)\fR Default content: .nf local\-zone: "invalid." static local\-data: "invalid. 10800 IN NS localhost." local\-data: "invalid. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" .fi .TP 10 \h'5'\fIreverse RFC1918 local use zones\fR Reverse data for zones 10.in\-addr.arpa, 16.172.in\-addr.arpa to 31.172.in\-addr.arpa, 168.192.in\-addr.arpa. The \fBlocal\-zone:\fR is set static and as \fBlocal\-data:\fR SOA and NS records are provided. .TP 10 \h'5'\fIreverse RFC3330 IP4 this, link\-local, testnet and broadcast\fR Reverse data for zones 0.in\-addr.arpa, 254.169.in\-addr.arpa, 2.0.192.in\-addr.arpa (TEST NET 1), 100.51.198.in\-addr.arpa (TEST NET 2), 113.0.203.in\-addr.arpa (TEST NET 3), 255.255.255.255.in\-addr.arpa. And from 64.100.in\-addr.arpa to 127.100.in\-addr.arpa (Shared Address Space). .TP 10 \h'5'\fIreverse RFC4291 IP6 unspecified\fR Reverse data for zone .nf 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0. 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. .fi .TP 10 \h'5'\fIreverse RFC4193 IPv6 Locally Assigned Local Addresses\fR Reverse data for zone D.F.ip6.arpa. .TP 10 \h'5'\fIreverse RFC4291 IPv6 Link Local Addresses\fR Reverse data for zones 8.E.F.ip6.arpa to B.E.F.ip6.arpa. .TP 10 \h'5'\fIreverse IPv6 Example Prefix\fR Reverse data for zone 8.B.D.0.1.0.0.2.ip6.arpa. This zone is used for tutorials and examples. You can remove the block on this zone with: .nf local\-zone: 8.B.D.0.1.0.0.2.ip6.arpa. nodefault .fi You can also selectively unblock a part of the zone by making that part transparent with a local\-zone statement. This also works with the other default zones. .\" End of local-zone listing. .TP 5 .B local\-data: \fI"" Configure local data, which is served in reply to queries for it. The query has to match exactly unless you configure the local\-zone as redirect. If not matched exactly, the local\-zone type determines further processing. If local\-data is configured that is not a subdomain of a local\-zone, a transparent local\-zone is configured. For record types such as TXT, use single quotes, as in local\-data: 'example. TXT "text"'. .IP If you need more complicated authoritative data, with referrals, wildcards, CNAME/DNAME support, or DNSSEC authoritative service, setup a stub\-zone for it as detailed in the stub zone section below. .TP 5 .B local\-data\-ptr: \fI"IPaddr name" Configure local data shorthand for a PTR record with the reversed IPv4 or IPv6 address and the host name. For example "192.0.2.4 www.example.com". TTL can be inserted like this: "2001:DB8::4 7200 www.example.com" .TP 5 .B local\-zone\-tag: \fI <"list of tags"> Assign tags to localzones. Tagged localzones will only be applied when the used access-control element has a matching tag. Tags must be defined in \fIdefine\-tags\fR. Enclose list of tags in quotes ("") and put spaces between tags. When there are multiple tags it checks if the intersection of the list of tags for the query and local\-zone\-tag is non-empty. .TP 5 .B local\-zone\-override: \fI Override the localzone type for queries from addresses matching netblock. Use this localzone type, regardless the type configured for the local-zone (both tagged and untagged) and regardless the type configured using access\-control\-tag\-action. .TP 5 +.B response\-ip: \fI +This requires use of the "respip" module. +.IP +If the IP address in an AAAA or A RR in the answer section of a +response matches the specified IP netblock, the specified action will +apply. +\fI\fR has generally the same semantics as that for +\fIaccess-control-tag-action\fR, but there are some exceptions. +.IP +Actions for \fIresponse-ip\fR are different from those for +\fIlocal-zone\fR in that in case of the former there is no point of +such conditions as "the query matches it but there is no local data". +Because of this difference, the semantics of \fIresponse-ip\fR actions +are modified or simplified as follows: The \fIstatic, refuse, +transparent, typetransparent,\fR and \fInodefault\fR actions are +invalid for \fIresponse-ip\fR. +Using any of these will cause the configuration to be rejected as +faulty. The \fIdeny\fR action is non-conditional, i.e. it always +results in dropping the corresponding query. +The resolution result before applying the deny action is still cached +and can be used for other queries. +.TP 5 +.B response-ip-data: \fI <"resource record string"> +This requires use of the "respip" module. +.IP +This specifies the action data for \fIresponse-ip\fR with action being +to redirect as specified by "\fIresource record string\fR". "Resource +record string" is similar to that of \fIaccess-control-tag-action\fR, +but it must be of either AAAA, A or CNAME types. +If the IP-netblock is an IPv6/IPV4 prefix, the record +must be AAAA/A respectively, unless it is a CNAME (which can be used +for both versions of IP netblocks). If it is CNAME there must not be +more than one \fIresponse-ip-data\fR for the same IP-netblock. +Also, CNAME and other types of records must not coexist for the same +IP-netblock, following the normal rules for CNAME records. +The textual domain name for the CNAME does not have to be explicitly +terminated with a dot ("."); the root name is assumed to be the origin +for the name. +.TP 5 +.B response-ip-tag: \fI <"list of tags"> +This requires use of the "respip" module. +.IP +Assign tags to response IP-netblocks. If the IP address in an AAAA or +A RR in the answer section of a response matches the specified +IP-netblock, the specified tags are assigned to the IP address. +Then, if an \fIaccess-control-tag\fR is defined for the client and it +includes one of the tags for the response IP, the corresponding +\fIaccess-control-tag-action\fR will apply. +Tag matching rule is the same as that for \fIaccess-control-tag\fR and +\fIlocal-zones\fR. +Unlike \fIlocal-zone-tag\fR, \fIresponse-ip-tag\fR can be defined for +an IP-netblock even if no \fIresponse-ip\fR is defined for that +netblock. +If multiple \fIresponse-ip-tag\fR options are specified for the same +IP-netblock in different statements, all but the first will be +ignored. +However, this will not be flagged as a configuration error, but the +result is probably not what was intended. +.IP +Actions specified in an +\fIaccess-control-tag-action\fR that has a matching tag with +\fIresponse-ip-tag\fR can be those that are "invalid" for +\fIresponse-ip\fR listed above, since \fIaccess-control-tag-action\fRs +can be shared with local zones. +For these actions, if they behave differently depending on whether +local data exists or not in case of local zones, the behavior for +\fIresponse-ip-data\fR will generally result in NOERROR/NODATA instead +of NXDOMAIN, since the \fIresponse-ip\fR data are inherently type +specific, and non-existence of data does not indicate anything about +the existence or non-existence of the qname itself. +For example, if the matching tag action is \fIstatic\fR but there is +no data for the corresponding \fIresponse-ip\fR configuration, then +the result will be NOERROR/NODATA. +The only case where NXDOMAIN is returned is when an +\fIalways_nxdomain\fR action applies. +.TP 5 .B ratelimit: \fI Enable ratelimiting of queries sent to nameserver for performing recursion. If 0, the default, it is disabled. This option is experimental at this time. The ratelimit is in queries per second that are allowed. More queries are turned away with an error (servfail). This stops recursive floods, eg. random query names, but not spoofed reflection floods. Cached responses are not ratelimited by this setting. The zone of the query is determined by examining the nameservers for it, the zone name is used to keep track of the rate. For example, 1000 may be a suitable value to stop the server from being overloaded with random names, and keeps unbound from sending traffic to the nameservers for those zones. .TP 5 .B ratelimit\-size: \fI Give the size of the data structure in which the current ongoing rates are kept track in. Default 4m. In bytes or use m(mega), k(kilo), g(giga). The ratelimit structure is small, so this data structure likely does not need to be large. .TP 5 .B ratelimit\-slabs: \fI Give power of 2 number of slabs, this is used to reduce lock contention in the ratelimit tracking data structure. Close to the number of cpus is a fairly good setting. .TP 5 .B ratelimit\-factor: \fI Set the amount of queries to rate limit when the limit is exceeded. If set to 0, all queries are dropped for domains where the limit is exceeded. If set to another value, 1 in that number is allowed through to complete. Default is 10, allowing 1/10 traffic to flow normally. This can make ordinary queries complete (if repeatedly queried for), and enter the cache, whilst also mitigating the traffic flow by the factor given. .TP 5 .B ratelimit\-for\-domain: \fI Override the global ratelimit for an exact match domain name with the listed number. You can give this for any number of names. For example, for a top\-level\-domain you may want to have a higher limit than other names. A value of 0 will disable ratelimiting for that domain. .TP 5 .B ratelimit\-below\-domain: \fI Override the global ratelimit for a domain name that ends in this name. You can give this multiple times, it then describes different settings in different parts of the namespace. The closest matching suffix is used to determine the qps limit. The rate for the exact matching domain name is not changed, use ratelimit\-for\-domain to set that, you might want to use different settings for a top\-level\-domain and subdomains. A value of 0 will disable ratelimiting for domain names that end in this name. .TP 5 .B ip\-ratelimit: \fI Enable global ratelimiting of queries accepted per ip address. If 0, the default, it is disabled. This option is experimental at this time. The ratelimit is in queries per second that are allowed. More queries are completely dropped and will not receive a reply, SERVFAIL or otherwise. IP ratelimiting happens before looking in the cache. This may be useful for mitigating amplification attacks. .TP 5 .B ip\-ratelimit\-size: \fI Give the size of the data structure in which the current ongoing rates are kept track in. Default 4m. In bytes or use m(mega), k(kilo), g(giga). The ip ratelimit structure is small, so this data structure likely does not need to be large. .TP 5 .B ip\-ratelimit\-slabs: \fI Give power of 2 number of slabs, this is used to reduce lock contention in the ip ratelimit tracking data structure. Close to the number of cpus is a fairly good setting. .TP 5 .B ip\-ratelimit\-factor: \fI Set the amount of queries to rate limit when the limit is exceeded. If set to 0, all queries are dropped for addresses where the limit is exceeded. If set to another value, 1 in that number is allowed through to complete. Default is 10, allowing 1/10 traffic to flow normally. This can make ordinary queries complete (if repeatedly queried for), and enter the cache, whilst also mitigating the traffic flow by the factor given. .TP 5 +.B outbound\-msg\-retry: \fI +The number of retries unbound will do in case of a non positive response is +received. If a forward nameserver is used, this is the number of retries per +forward nameserver in case of throwaway response. +.TP 5 .B fast\-server\-permil: \fI Specify how many times out of 1000 to pick from the set of fastest servers. 0 turns the feature off. A value of 900 would pick from the fastest servers 90 percent of the time, and would perform normal exploration of random servers for the remaining time. When prefetch is enabled (or serve\-expired), such prefetches are not sped up, because there is no one waiting for it, and it presents a good moment to perform server exploration. The \fBfast\-server\-num\fR option can be used to specify the size of the fastest servers set. The default for fast\-server\-permil is 0. .TP 5 .B fast\-server\-num: \fI Set the number of servers that should be used for fast server selection. Only use the fastest specified number of servers with the fast\-server\-permil option, that turns this on or off. The default is to use the fastest 3 servers. +.TP 5 +.B edns\-client\-string: \fI +Include an EDNS0 option containing configured ascii string in queries with +destination address matching the configured IP netblock. This configuration +option can be used multiple times. The most specific match will be used. +.TP 5 +.B edns\-client\-string\-opcode: \fI +EDNS0 option code for the \fIedns\-client\-string\fR option, from 0 to 65535. +A value from the `Reserved for Local/Experimental` range (65001-65534) should +be used. Default is 65001. .SS "Remote Control Options" In the .B remote\-control: clause are the declarations for the remote control facility. If this is enabled, the \fIunbound\-control\fR(8) utility can be used to send commands to the running unbound server. The server uses these clauses to setup TLSv1 security for the connection. The \fIunbound\-control\fR(8) utility also reads the \fBremote\-control\fR section for options. To setup the correct self\-signed certificates use the \fIunbound\-control\-setup\fR(8) utility. .TP 5 .B control\-enable: \fI The option is used to enable remote control, default is "no". If turned off, the server does not listen for control commands. .TP 5 .B control\-interface: \fI Give IPv4 or IPv6 addresses or local socket path to listen on for control commands. By default localhost (127.0.0.1 and ::1) is listened to. Use 0.0.0.0 and ::0 to listen to all interfaces. If you change this and permissions have been dropped, you must restart the server for the change to take effect. .IP If you set it to an absolute path, a local socket is used. The local socket does not use the certificates and keys, so those files need not be present. To restrict access, unbound sets permissions on the file to the user and group that is configured, the access bits are set to allow the group members to access the control socket file. Put users that need to access the socket in the that group. To restrict access further, create a directory to put the control socket in and restrict access to that directory. .TP 5 .B control\-port: \fI The port number to listen on for IPv4 or IPv6 control interfaces, default is 8953. If you change this and permissions have been dropped, you must restart the server for the change to take effect. .TP 5 .B control\-use\-cert: \fI For localhost control-interface you can disable the use of TLS by setting this option to "no", default is "yes". For local sockets, TLS is disabled and the value of this option is ignored. .TP 5 .B server\-key\-file: \fI Path to the server private key, by default unbound_server.key. This file is generated by the \fIunbound\-control\-setup\fR utility. This file is used by the unbound server, but not by \fIunbound\-control\fR. .TP 5 .B server\-cert\-file: \fI Path to the server self signed certificate, by default unbound_server.pem. This file is generated by the \fIunbound\-control\-setup\fR utility. This file is used by the unbound server, and also by \fIunbound\-control\fR. .TP 5 .B control\-key\-file: \fI Path to the control client private key, by default unbound_control.key. This file is generated by the \fIunbound\-control\-setup\fR utility. This file is used by \fIunbound\-control\fR. .TP 5 .B control\-cert\-file: \fI Path to the control client certificate, by default unbound_control.pem. This certificate has to be signed with the server certificate. This file is generated by the \fIunbound\-control\-setup\fR utility. This file is used by \fIunbound\-control\fR. .SS "Stub Zone Options" .LP There may be multiple .B stub\-zone: clauses. Each with a name: and zero or more hostnames or IP addresses. For the stub zone this list of nameservers is used. Class IN is assumed. The servers should be authority servers, not recursors; unbound performs the recursive processing itself for stub zones. .P The stub zone can be used to configure authoritative data to be used by the resolver that cannot be accessed using the public internet servers. This is useful for company\-local data or private zones. Setup an authoritative server on a different host (or different port). Enter a config entry for unbound with .B stub\-addr: . The unbound resolver can then access the data, without referring to the public internet for it. .P This setup allows DNSSEC signed zones to be served by that authoritative server, in which case a trusted key entry with the public key can be put in config, so that unbound can validate the data and set the AD bit on replies for the private zone (authoritative servers do not set the AD bit). This setup makes unbound capable of answering queries for the private zone, and can even set the AD bit ('authentic'), but the AA ('authoritative') bit is not set on these replies. .P Consider adding \fBserver:\fR statements for \fBdomain\-insecure:\fR and for \fBlocal\-zone:\fI name nodefault\fR for the zone if it is a locally served zone. The insecure clause stops DNSSEC from invalidating the zone. The local zone nodefault (or \fItransparent\fR) clause makes the (reverse\-) zone bypass unbound's filtering of RFC1918 zones. .TP .B name: \fI -Name of the stub zone. +Name of the stub zone. This is the full domain name of the zone. .TP .B stub\-host: \fI Name of stub zone nameserver. Is itself resolved before it is used. .TP .B stub\-addr: \fI IP address of stub zone nameserver. Can be IP 4 or IP 6. To use a nondefault port for DNS communication append '@' with the port number. +If tls is enabled, then you can append a '#' and a name, then it'll check +the tls authentication certificates with that name. If you combine +the '@' and '#', the '@' comes first. .TP .B stub\-prime: \fI This option is by default no. If enabled it performs NS set priming, which is similar to root hints, where it starts using the list of nameservers currently published by the zone. Thus, if the hint list is slightly outdated, the resolver picks up a correct list online. .TP .B stub\-first: \fI If enabled, a query is attempted without the stub clause if it fails. The data could not be retrieved and would have caused SERVFAIL because the servers are unreachable, instead it is tried without this clause. The default is no. .TP .B stub\-tls\-upstream: \fI Enabled or disable whether the queries to this stub use TLS for transport. Default is no. .TP .B stub\-ssl\-upstream: \fI Alternate syntax for \fBstub\-tls\-upstream\fR. .TP +.B stub\-tcp\-upstream: \fI +If it is set to "yes" then upstream queries use TCP only for transport regardless of global flag tcp-upstream. +Default is no. +.TP .B stub\-no\-cache: \fI Default is no. If enabled, data inside the stub is not cached. This is useful when you want immediate changes to be visible. .SS "Forward Zone Options" .LP There may be multiple .B forward\-zone: clauses. Each with a \fBname:\fR and zero or more hostnames or IP addresses. For the forward zone this list of nameservers is used to forward the queries to. The servers listed as \fBforward\-host:\fR and \fBforward\-addr:\fR have to handle further recursion for the query. Thus, those servers are not authority servers, but are (just like unbound is) recursive servers too; unbound does not perform recursion itself for the forward zone, it lets the remote server do it. Class IN is assumed. CNAMEs are chased by unbound itself, asking the remote server for every name in the indirection chain, to protect the local cache from illegal indirect referenced items. A forward\-zone entry with name "." and a forward\-addr target will forward all queries to that other server (unless it can answer from the cache). .TP .B name: \fI -Name of the forward zone. +Name of the forward zone. This is the full domain name of the zone. .TP .B forward\-host: \fI Name of server to forward to. Is itself resolved before it is used. .TP .B forward\-addr: \fI IP address of server to forward to. Can be IP 4 or IP 6. To use a nondefault port for DNS communication append '@' with the port number. If tls is enabled, then you can append a '#' and a name, then it'll check the tls authentication certificates with that name. If you combine the '@' and '#', the '@' comes first. .IP At high verbosity it logs the TLS certificate, with TLS enabled. If you leave out the '#' and auth name from the forward\-addr, any name is accepted. The cert must also match a CA from the tls\-cert\-bundle. .TP .B forward\-first: \fI If a forwarded query is met with a SERVFAIL error, and this option is enabled, unbound will fall back to normal recursive resolution for this query as if no query forwarding had been specified. The default is "no". .TP .B forward\-tls\-upstream: \fI Enabled or disable whether the queries to this forwarder use TLS for transport. Default is no. If you enable this, also configure a tls\-cert\-bundle or use tls\-win\-cert to load CA certs, otherwise the connections cannot be authenticated. .TP .B forward\-ssl\-upstream: \fI Alternate syntax for \fBforward\-tls\-upstream\fR. .TP +.B forward\-tcp\-upstream: \fI +If it is set to "yes" then upstream queries use TCP only for transport regardless of global flag tcp-upstream. +Default is no. +.TP .B forward\-no\-cache: \fI Default is no. If enabled, data inside the forward is not cached. This is useful when you want immediate changes to be visible. .SS "Authority Zone Options" .LP Authority zones are configured with \fBauth\-zone:\fR, and each one must have a \fBname:\fR. There can be multiple ones, by listing multiple auth\-zone clauses, each with a different name, pertaining to that part of the namespace. The authority zone with the name closest to the name looked up is used. Authority zones are processed after \fBlocal\-zones\fR and before cache (\fBfor\-downstream:\fR \fIyes\fR), and when used in this manner make unbound respond like an authority server. Authority zones are also processed after cache, just before going to the network to fetch information for recursion (\fBfor\-upstream:\fR \fIyes\fR), and when used in this manner provide a local copy of an authority server that speeds up lookups of that data. .LP Authority zones can be read from zonefile. And can be kept updated via AXFR and IXFR. After update the zonefile is rewritten. The update mechanism uses the SOA timer values and performs SOA UDP queries to detect zone changes. .LP If the update fetch fails, the timers in the SOA record are used to time another fetch attempt. Until the SOA expiry timer is reached. Then the zone is expired. When a zone is expired, queries are SERVFAIL, and -any new serial number is accepted from the master (even if older), and if +any new serial number is accepted from the primary (even if older), and if fallback is enabled, the fallback activates to fetch from the upstream instead of the SERVFAIL. .TP .B name: \fI Name of the authority zone. .TP -.B master: \fI +.B primary: \fI Where to download a copy of the zone from, with AXFR and IXFR. Multiple -masters can be specified. They are all tried if one fails. -With the "ip#name" notation a AXFR over TLS can be used. +primaries can be specified. They are all tried if one fails. +To use a nondefault port for DNS communication append '@' with the port number. +You can append a '#' and a name, then AXFR over TLS can be used and the tls authentication certificates will be checked with that name. If you combine +the '@' and '#', the '@' comes first. +If you point it at another Unbound instance, it would not work because +that does not support AXFR/IXFR for the zone, but if you used \fBurl:\fR to download +the zonefile as a text file from a webserver that would work. +If you specify the hostname, you cannot use the domain from the zonefile, +because it may not have that when retrieving that data, instead use a plain +IP address to avoid a circular dependency on retrieving that IP address. +.TP +.B master: \fI +Alternate syntax for \fBprimary\fR. .TP .B url: \fI Where to download a zonefile for the zone. With http or https. An example for the url is "http://www.example.com/example.org.zone". Multiple url statements can be given, they are tried in turn. If only urls are given the SOA refresh timer is used to wait for making new downloads. If also -masters are listed, the masters are first probed with UDP SOA queries to +primaries are listed, the primaries are first probed with UDP SOA queries to see if the SOA serial number has changed, reducing the number of downloads. -If none of the urls work, the masters are tried with IXFR and AXFR. +If none of the urls work, the primaries are tried with IXFR and AXFR. For https, the \fBtls\-cert\-bundle\fR and the hostname from the url are used to authenticate the connection. +If you specify a hostname in the URL, you cannot use the domain from the +zonefile, because it may not have that when retrieving that data, instead +use a plain IP address to avoid a circular dependency on retrieving that IP +address. Avoid dependencies on name lookups by using a notation like +"http://192.0.2.1/unbound-primaries/example.com.zone", with an explicit IP address. .TP .B allow\-notify: \fI With allow\-notify you can specify additional sources of notifies. When notified, the server attempts to first probe and then zone transfer. -If the notify is from a master, it first attempts that master. Otherwise -other masters are attempted. If there are no masters, but only urls, the -file is downloaded when notified. The masters from master: statements are +If the notify is from a primary, it first attempts that primary. Otherwise +other primaries are attempted. If there are no primaries, but only urls, the +file is downloaded when notified. The primaries from primary: statements are allowed notify by default. .TP .B fallback\-enabled: \fI Default no. If enabled, unbound falls back to querying the internet as a resolver for this zone when lookups fail. For example for DNSSEC validation failures. .TP .B for\-downstream: \fI Default yes. If enabled, unbound serves authority responses to downstream clients for this zone. This option makes unbound behave, for the queries with names in this zone, like one of the authority servers for that zone. Turn it off if you want unbound to provide recursion for the zone but have a local copy of zone data. If for\-downstream is no and for\-upstream is yes, then unbound will DNSSEC validate the contents of the zone before serving the zone contents to clients and store validation results in the cache. .TP .B for\-upstream: \fI Default yes. If enabled, unbound fetches data from this data collection for answering recursion queries. Instead of sending queries over the internet to the authority servers for this zone, it'll fetch the data directly from the zone data. Turn it on when you want unbound to provide recursion for downstream clients, and use the zone data as a local copy to speed up lookups. .TP +.B zonemd\-check: \fI +Enable this option to check ZONEMD records in the zone. Default is disabled. +The ZONEMD record is a checksum over the zone data. This includes glue in +the zone and data from the zone file, and excludes comments from the zone file. +When there is a DNSSEC chain of trust, DNSSEC signatures are checked too. +.TP +.B zonemd\-reject\-absence: \fI +Enable this option to reject the absence of the ZONEMD record. Without it, +when zonemd is not there it is not checked. It is useful to enable for a +nonDNSSEC signed zone where the operator wants to require the verification +of a ZONEMD, hence a missing ZONEMD is a failure. The action upon +failure is controlled by the \fBzonemd\-permissive\-mode\fR option, for +log only or also block the zone. The default is no. +.IP +Without the option absence of a ZONEMD is only a failure when the zone is +DNSSEC signed, and we have a trust anchor, and the DNSSEC verification of +the absence of the ZONEMD fails. With the option enabled, the absence of +a ZONEMD is always a failure, also for nonDNSSEC signed zones. +.TP .B zonefile: \fI The filename where the zone is stored. If not given then no zonefile is used. If the file does not exist or is empty, unbound will attempt to fetch zone -data (eg. from the master servers). +data (eg. from the primary servers). .SS "View Options" .LP There may be multiple .B view: clauses. Each with a \fBname:\fR and zero or more \fBlocal\-zone\fR and \fBlocal\-data\fR elements. Views can also contain view\-first, response\-ip, response\-ip\-data and local\-data\-ptr elements. View can be mapped to requests by specifying the view name in an \fBaccess\-control\-view\fR element. Options from matching views will override global options. Global options will be used if no matching view is found, or when the matching view does not have the option specified. .TP .B name: \fI Name of the view. Must be unique. This name is used in access\-control\-view elements. .TP .B local\-zone: \fI View specific local\-zone elements. Has the same types and behaviour as the global local\-zone elements. When there is at least one local\-zone specified and view\-first is no, the default local-zones will be added to this view. Defaults can be disabled using the nodefault type. When view\-first is yes or when a view does not have a local\-zone, the global local\-zone will be used including it's default zones. .TP .B local\-data: \fI"" View specific local\-data elements. Has the same behaviour as the global local\-data elements. .TP .B local\-data\-ptr: \fI"IPaddr name" View specific local\-data\-ptr elements. Has the same behaviour as the global local\-data\-ptr elements. .TP .B view\-first: \fI If enabled, it attempts to use the global local\-zone and local\-data if there is no match in the view specific options. The default is no. .SS "Python Module Options" .LP The .B python: clause gives the settings for the \fIpython\fR(1) script module. This module acts like the iterator and validator modules do, on queries and answers. To enable the script module it has to be compiled into the daemon, and the word "python" has to be put in the \fBmodule\-config:\fR option -(usually first, or between the validator and iterator). +(usually first, or between the validator and iterator). Multiple instances of +the python module are supported by adding the word "python" more than once. .LP If the \fBchroot:\fR option is enabled, you should make sure Python's library directory structure is bind mounted in the new root environment, see \fImount\fR(8). Also the \fBpython\-script:\fR path should be specified as an absolute path relative to the new root, or as a relative path to the working directory. .TP .B python\-script: \fI\fR -The script file to load. +The script file to load. Repeat this option for every python module instance +added to the \fBmodule\-config:\fR option. +.SS "Dynamic Library Module Options" +.LP +The +.B dynlib: +clause gives the settings for the \fIdynlib\fR module. This module is only +a very small wrapper that allows dynamic modules to be loaded on runtime +instead of being compiled into the application. To enable the dynlib module it +has to be compiled into the daemon, and the word "dynlib" has to be put in the +\fBmodule\-config:\fR option. Multiple instances of dynamic libraries are +supported by adding the word "dynlib" more than once. +.LP +The \fBdynlib\-file:\fR path should be specified as an absolute path relative +to the new path set by \fBchroot:\fR option, or as a relative path to the +working directory. +.TP +.B dynlib\-file: \fI\fR +The dynamic library file to load. Repeat this option for every dynlib module +instance added to the \fBmodule\-config:\fR option. .SS "DNS64 Module Options" .LP The dns64 module must be configured in the \fBmodule\-config:\fR "dns64 validator iterator" directive and be compiled into the daemon to be enabled. These settings go in the \fBserver:\fR section. .TP .B dns64\-prefix: \fI\fR This sets the DNS64 prefix to use to synthesize AAAA records with. It must be /96 or shorter. The default prefix is 64:ff9b::/96. .TP .B dns64\-synthall: \fI\fR Debug option, default no. If enabled, synthesize all AAAA records despite the presence of actual AAAA records. .TP .B dns64\-ignore\-aaaa: \fI\fR List domain for which the AAAA records are ignored and the A record is used by dns64 processing instead. Can be entered multiple times, list a new domain for which it applies, one per line. Applies also to names underneath the name given. .SS "DNSCrypt Options" .LP The .B dnscrypt: clause gives the settings of the dnscrypt channel. While those options are available, they are only meaningful if unbound was compiled with \fB\-\-enable\-dnscrypt\fR. Currently certificate and secret/public keys cannot be generated by unbound. You can use dnscrypt-wrapper to generate those: https://github.com/cofyc/\ dnscrypt-wrapper/blob/master/README.md#usage .TP .B dnscrypt\-enable: \fI\fR Whether or not the \fBdnscrypt\fR config should be enabled. You may define configuration but not activate it. The default is no. .TP .B dnscrypt\-port: \fI On which port should \fBdnscrypt\fR should be activated. Note that you should have a matching \fBinterface\fR option defined in the \fBserver\fR section for this port. .TP .B dnscrypt\-provider: \fI\fR The provider name to use to distribute certificates. This is of the form: \fB2.dnscrypt-cert.example.com.\fR. The name \fIMUST\fR end with a dot. .TP .B dnscrypt\-secret\-key: \fI\fR Path to the time limited secret key file. This option may be specified multiple times. .TP .B dnscrypt\-provider\-cert: \fI\fR Path to the certificate related to the \fBdnscrypt\-secret\-key\fRs. This option may be specified multiple times. .TP .B dnscrypt\-provider\-cert\-rotated: \fI\fR Path to a certificate that we should be able to serve existing connection from but do not want to advertise over \fBdnscrypt\-provider\fR's TXT record certs distribution. A typical use case is when rotating certificates, existing clients may still use the client magic from the old cert in their queries until they fetch and update the new cert. Likewise, it would allow one to prime the new cert/key without distributing the new cert yet, this can be useful when using a network of servers using anycast and on which the configuration may not get updated at the exact same time. By priming the cert, the servers can handle both old and new certs traffic while distributing only one. This option may be specified multiple times. .TP .B dnscrypt\-shared\-secret\-cache\-size: \fI Give the size of the data structure in which the shared secret keys are kept in. Default 4m. In bytes or use m(mega), k(kilo), g(giga). The shared secret cache is used when a same client is making multiple queries using the same public key. It saves a substantial amount of CPU. .TP .B dnscrypt\-shared\-secret\-cache\-slabs: \fI Give power of 2 number of slabs, this is used to reduce lock contention in the dnscrypt shared secrets cache. Close to the number of cpus is a fairly good setting. .TP .B dnscrypt\-nonce\-cache\-size: \fI Give the size of the data structure in which the client nonces are kept in. Default 4m. In bytes or use m(mega), k(kilo), g(giga). The nonce cache is used to prevent dnscrypt message replaying. Client nonce should be unique for any pair of client pk/server sk. .TP .B dnscrypt\-nonce\-cache\-slabs: \fI Give power of 2 number of slabs, this is used to reduce lock contention in the dnscrypt nonce cache. Close to the number of cpus is a fairly good setting. .SS "EDNS Client Subnet Module Options" .LP The ECS module must be configured in the \fBmodule\-config:\fR "subnetcache validator iterator" directive and be compiled into the daemon to be enabled. These settings go in the \fBserver:\fR section. .LP -If the destination address is whitelisted with Unbound will add the EDNS0 -option to the query containing the relevant part of the client's address. When -an answer contains the ECS option the response and the option are placed in a -specialized cache. If the authority indicated no support, the response is +If the destination address is allowed in the configuration Unbound will add the +EDNS0 option to the query containing the relevant part of the client's address. +When an answer contains the ECS option the response and the option are placed in +a specialized cache. If the authority indicated no support, the response is stored in the regular cache. .LP Additionally, when a client includes the option in its queries, Unbound will -forward the option to the authority if present in the whitelist, or +forward the option when sending the query to addresses that are explicitly +allowed in the configuration using \fBsend\-client\-subnet\fR. The option will +always be forwarded, regardless the allowed addresses, if \fBclient\-subnet\-always\-forward\fR is set to yes. In this case the lookup in the regular cache is skipped. .LP The maximum size of the ECS cache is controlled by 'msg-cache-size' in the configuration file. On top of that, for each query only 100 different subnets are allowed to be stored for each address family. Exceeding that number, older entries will be purged from cache. .TP .B send\-client\-subnet: \fI\fR Send client source address to this authority. Append /num to indicate a classless delegation netblock, for example like 10.2.3.4/24 or 2001::11/64. Can be given multiple times. Authorities not listed will not receive edns-subnet information, unless domain in query is specified in \fBclient\-subnet\-zone\fR. .TP .B client\-subnet\-zone: \fI\fR Send client source address in queries for this domain and its subdomains. Can be given multiple times. Zones not listed will not receive edns-subnet information, unless hosted by authority specified in \fBsend\-client\-subnet\fR. .TP .B client\-subnet\-always\-forward: \fI\fR -Specify whether the ECS whitelist check (configured using +Specify whether the ECS address check (configured using \fBsend\-client\-subnet\fR) is applied for all queries, even if the triggering query contains an ECS record, or only for queries for which the ECS record is generated using the querier address (and therefore did not contain ECS data in -the client query). If enabled, the whitelist check is skipped when the client -query contains an ECS record. Default is no. +the client query). If enabled, the address check is skipped when the client +query contains an ECS record. And the lookup in the regular cache is skipped. +Default is no. .TP .B max\-client\-subnet\-ipv6: \fI\fR Specifies the maximum prefix length of the client source address we are willing to expose to third parties for IPv6. Defaults to 56. .TP .B max\-client\-subnet\-ipv4: \fI\fR Specifies the maximum prefix length of the client source address we are willing to expose to third parties for IPv4. Defaults to 24. .TP .B min\-client\-subnet\-ipv6: \fI\fR Specifies the minimum prefix length of the IPv6 source mask we are willing to accept in queries. Shorter source masks result in REFUSED answers. Source mask of 0 is always accepted. Default is 0. .TP .B min\-client\-subnet\-ipv4: \fI\fR Specifies the minimum prefix length of the IPv4 source mask we are willing to accept in queries. Shorter source masks result in REFUSED answers. Source mask of 0 is always accepted. Default is 0. .TP .B max\-ecs\-tree\-size\-ipv4: \fI\fR Specifies the maximum number of subnets ECS answers kept in the ECS radix tree. This number applies for each qname/qclass/qtype tuple. Defaults to 100. .TP .B max\-ecs\-tree\-size\-ipv6: \fI\fR Specifies the maximum number of subnets ECS answers kept in the ECS radix tree. This number applies for each qname/qclass/qtype tuple. Defaults to 100. .SS "Opportunistic IPsec Support Module Options" .LP The IPsec module must be configured in the \fBmodule\-config:\fR "ipsecmod validator iterator" directive and be compiled into the daemon to be enabled. These settings go in the \fBserver:\fR section. .LP When unbound receives an A/AAAA query that is not in the cache and finds a valid answer, it will withhold returning the answer and instead will generate an IPSECKEY subquery for the same domain name. If an answer was found, unbound will call an external hook passing the following arguments: .TP 10 \h'5'\fIQNAME\fR Domain name of the A/AAAA and IPSECKEY query. In string format. .TP 10 \h'5'\fIIPSECKEY TTL\fR TTL of the IPSECKEY RRset. .TP 10 \h'5'\fIA/AAAA\fR String of space separated IP addresses present in the A/AAAA RRset. The IP addresses are in string format. .TP 10 \h'5'\fIIPSECKEY\fR String of space separated IPSECKEY RDATA present in the IPSECKEY RRset. The IPSECKEY RDATA are in DNS presentation format. .LP The A/AAAA answer is then cached and returned to the client. If the external hook was called the TTL changes to ensure it doesn't surpass \fBipsecmod-max-ttl\fR. .LP The same procedure is also followed when \fBprefetch:\fR is used, but the A/AAAA answer is given to the client before the hook is called. \fBipsecmod-max-ttl\fR ensures that the A/AAAA answer given from cache is still relevant for opportunistic IPsec. .TP .B ipsecmod-enabled: \fI\fR Specifies whether the IPsec module is enabled or not. The IPsec module still needs to be defined in the \fBmodule\-config:\fR directive. This option facilitates turning on/off the module without restarting/reloading unbound. Defaults to yes. .TP .B ipsecmod\-hook: \fI\fR Specifies the external hook that unbound will call with \fIsystem\fR(3). The file can be specified as an absolute/relative path. The file needs the proper permissions to be able to be executed by the same user that runs unbound. It must be present when the IPsec module is defined in the \fBmodule\-config:\fR directive. .TP .B ipsecmod-strict: \fI\fR If enabled unbound requires the external hook to return a success value of 0. Failing to do so unbound will reply with SERVFAIL. The A/AAAA answer will also not be cached. Defaults to no. .TP .B ipsecmod\-max-ttl: \fI\fR Time to live maximum for A/AAAA cached records after calling the external hook. Defaults to 3600. .TP .B ipsecmod-ignore-bogus: \fI\fR Specifies the behaviour of unbound when the IPSECKEY answer is bogus. If set to yes, the hook will be called and the A/AAAA answer will be returned to the client. If set to no, the hook will not be called and the answer to the A/AAAA query will be SERVFAIL. Mainly used for testing. Defaults to no. .TP -.B ipsecmod\-whitelist: \fI\fR -Whitelist the domain so that the module logic will be executed. Can -be given multiple times, for different domains. If the option is not -specified, all domains are treated as being whitelisted (default). +.B ipsecmod\-allow: \fI\fR +Allow the ipsecmod functionality for the domain so that the module logic will be +executed. Can be given multiple times, for different domains. If the option is +not specified, all domains are treated as being allowed (default). +.TP +.B ipsecmod\-whitelist: \fI +Alternate syntax for \fBipsecmod\-allow\fR. .SS "Cache DB Module Options" .LP The Cache DB module must be configured in the \fBmodule\-config:\fR "validator cachedb iterator" directive and be compiled into the daemon with \fB\-\-enable\-cachedb\fR. If this module is enabled and configured, the specified backend database works as a second level cache: When Unbound cannot find an answer to a query in its built-in in-memory cache, it consults the specified backend. If it finds a valid answer in the backend, Unbound uses it to respond to the query without performing iterative DNS resolution. If Unbound cannot even find an answer in the backend, it resolves the query as usual, and stores the answer in the backend. .P +This module interacts with the \fBserve\-expired\-*\fR options and will reply +with expired data if unbound is configured for that. Currently the use +of \fBserve\-expired\-client\-timeout:\fR and +\fBserve\-expired\-reply\-ttl:\fR is not consistent for data originating from +the external cache as these will result in a reply with 0 TTL without trying to +update the data first, ignoring the configured values. +.P If Unbound was built with \fB\-\-with\-libhiredis\fR on a system that has installed the hiredis C client library of Redis, then the "redis" backend can be used. This backend communicates with the specified Redis server over a TCP connection to store and retrieve cache data. It can be used as a persistent and/or shared cache backend. It should be noted that Unbound never removes data stored in the Redis server, even if some data have expired in terms of DNS TTL or the Redis server has cached too much data; if necessary the Redis server must be configured to limit the cache size, preferably with some kind of least-recently-used eviction policy. +Additionally, the \fBredis\-expire\-records\fR option can be used in order to +set the relative DNS TTL of the message as timeout to the Redis records; keep +in mind that some additional memory is used per key and that the expire +information is stored as absolute Unix timestamps in Redis (computer time must +be stable). This backend uses synchronous communication with the Redis server based on the assumption that the communication is stable and sufficiently fast. The thread waiting for a response from the Redis server cannot handle other DNS queries. Although the backend has the ability to reconnect to the server when the connection is closed unexpectedly and there is a configurable timeout in case the server is overly slow or hangs up, these cases are assumed to be very rare. If connection close or timeout happens too often, Unbound will be effectively unusable with this backend. It's the administrator's responsibility to make the assumption hold. .P The .B cachedb: clause gives custom settings of the cache DB module. .TP .B backend: \fI\fR Specify the backend database name. The default database is the in-memory backend named "testframe", which, as the name suggests, is not of any practical use. Depending on the build-time configuration, "redis" backend may also be used as described above. .TP .B secret-seed: \fI<"secret string">\fR Specify a seed to calculate a hash value from query information. This value will be used as the key of the corresponding answer for the backend database and can be customized if the hash should not be predictable operationally. If the backend database is shared by multiple Unbound instances, all instances must use the same secret seed. This option defaults to "default". .P The following .B cachedb -otions are specific to the redis backend. +options are specific to the redis backend. .TP .B redis-server-host: \fI\fR The IP (either v6 or v4) address or domain name of the Redis server. In general an IP address should be specified as otherwise Unbound will have to resolve the name of the server every time it establishes a connection to the server. This option defaults to "127.0.0.1". .TP .B redis-server-port: \fI\fR The TCP port number of the Redis server. This option defaults to 6379. .TP .B redis-timeout: \fI\fR The period until when Unbound waits for a response from the Redis sever. If this timeout expires Unbound closes the connection, treats it as if the Redis server does not have the requested data, and will try to re-establish a new connection later. This option defaults to 100 milliseconds. +.TP +.B redis-expire-records: \fI +If Redis record expiration is enabled. If yes, unbound sets timeout for Redis +records so that Redis can evict keys that have expired automatically. If +unbound is configured with \fBserve-expired\fR and \fBserve-expired-ttl\fR is 0, +this option is internally reverted to "no". Redis SETEX support is required +for this option (Redis >= 2.0.0). +This option defaults to no. +.SS DNSTAP Logging Options +DNSTAP support, when compiled in, is enabled in the \fBdnstap:\fR section. +This starts an extra thread (when compiled with threading) that writes +the log information to the destination. If unbound is compiled without +threading it does not spawn a thread, but connects per-process to the +destination. +.TP +.B dnstap-enable: \fI +If dnstap is enabled. Default no. If yes, it connects to the dnstap server +and if any of the dnstap-log-..-messages options is enabled it sends logs +for those messages to the server. +.TP +.B dnstap-bidirectional: \fI +Use frame streams in bidirectional mode to transfer DNSTAP messages. Default is +yes. +.TP +.B dnstap-socket-path: \fI +Sets the unix socket file name for connecting to the server that is +listening on that socket. Default is "@DNSTAP_SOCKET_PATH@". +.TP +.B dnstap-ip: \fI +If "", the unix socket is used, if set with an IP address (IPv4 or IPv6) +that address is used to connect to the server. +.TP +.B dnstap-tls: \fI +Set this to use TLS to connect to the server specified in \fBdnstap-ip\fR. +The default is yes. If set to no, TCP is used to connect to the server. +.TP +.B dnstap-tls-server-name: \fI +The TLS server name to authenticate the server with. Used when \fBdnstap-tls\fR is enabled. If "" it is ignored, default "". +.TP +.B dnstap-tls-cert-bundle: \fI +The pem file with certs to verify the TLS server certificate. If "" the +server default cert bundle is used, or the windows cert bundle on windows. +Default is "". +.TP +.B dnstap-tls-client-key-file: \fI +The client key file for TLS client authentication. If "" client +authentication is not used. Default is "". +.TP +.B dnstap-tls-client-cert-file: \fI +The client cert file for TLS client authentication. Default is "". +.TP +.B dnstap-send-identity: \fI +If enabled, the server identity is included in the log messages. +Default is no. +.TP +.B dnstap-send-version: \fI +If enabled, the server version if included in the log messages. +Default is no. +.TP +.B dnstap-identity: \fI +The identity to send with messages, if "" the hostname is used. +Default is "". +.TP +.B dnstap-version: \fI +The version to send with messages, if "" the package version is used. +Default is "". +.TP +.B dnstap-log-resolver-query-messages: \fI +Enable to log resolver query messages. Default is no. +These are messages from unbound to upstream servers. +.TP +.B dnstap-log-resolver-response-messages: \fI +Enable to log resolver response messages. Default is no. +These are replies from upstream servers to unbound. +.TP +.B dnstap-log-client-query-messages: \fI +Enable to log client query messages. Default is no. +These are client queries to unbound. +.TP +.B dnstap-log-client-response-messages: \fI +Enable to log client response messages. Default is no. +These are responses from unbound to clients. +.TP +.B dnstap-log-forwarder-query-messages: \fI +Enable to log forwarder query messages. Default is no. +.TP +.B dnstap-log-forwarder-response-messages: \fI +Enable to log forwarder response messages. Default is no. +.SS Response Policy Zone Options +.LP +Response Policy Zones are configured with \fBrpz:\fR, and each one must have a +\fBname:\fR. There can be multiple ones, by listing multiple rpz clauses, each +with a different name. RPZ clauses are applied in order of configuration. The +\fBrespip\fR module needs to be added to the \fBmodule-config\fR, e.g.: +\fBmodule-config: "respip validator iterator"\fR. +.P +QNAME, Response IP Address, nsdname, nsip and clientip triggers are supported. +Supported actions are: NXDOMAIN, NODATA, PASSTHRU, DROP, Local Data, tcp\-only +and drop. RPZ QNAME triggers are applied after \fBlocal\-zones\fR and +before \fBauth\-zones\fR. +.P +The rpz zone is formatted with a SOA start record as usual. The items in +the zone are entries, that specify what to act on (the trigger) and what to +do (the action). The trigger to act on is recorded in the name, the action +to do is recorded as the resource record. The names all end in the zone +name, so you could type the trigger names without a trailing dot in the +zonefile. +.P +An example RPZ record, that answers example.com with NXDOMAIN +.nf + example.com CNAME . +.fi +.P +The triggers are encoded in the name on the left +.nf + name query name + netblock.rpz-client-ip client IP address + netblock.rpz-ip response IP address in the answer + name.rpz-nsdname nameserver name + netblock.rpz-nsip nameserver IP address +.fi +The netblock is written as .. +For IPv6 use 'zz' for '::'. Specify individual addresses with scope length +of 32 or 128. For example, 24.10.100.51.198.rpz-ip is 198.51.100.10/24 and +32.10.zz.db8.2001.rpz-ip is 2001:db8:0:0:0:0:0:10/32. +.P +The actions are specified with the record on the right +.nf + CNAME . nxdomain reply + CNAME *. nodata reply + CNAME rpz-passthru. do nothing, allow to continue + CNAME rpz-drop. the query is dropped + CNAME rpz-tcp-only. answer over TCP + A 192.0.2.1 answer with this IP address +.fi +Other records like AAAA, TXT and other CNAMEs (not rpz-..) can also be used to +answer queries with that content. +.P +The RPZ zones can be configured in the config file with these settings in the \fBrpz:\fR block. +.TP +.B name: \fI +Name of the authority zone. +.TP +.B primary: \fI +Where to download a copy of the zone from, with AXFR and IXFR. Multiple +primaries can be specified. They are all tried if one fails. +To use a nondefault port for DNS communication append '@' with the port number. +You can append a '#' and a name, then AXFR over TLS can be used and the tls authentication certificates will be checked with that name. If you combine +the '@' and '#', the '@' comes first. +If you point it at another Unbound instance, it would not work because +that does not support AXFR/IXFR for the zone, but if you used \fBurl:\fR to download +the zonefile as a text file from a webserver that would work. +If you specify the hostname, you cannot use the domain from the zonefile, +because it may not have that when retrieving that data, instead use a plain +IP address to avoid a circular dependency on retrieving that IP address. +.TP +.B master: \fI +Alternate syntax for \fBprimary\fR. +.TP +.B url: \fI +Where to download a zonefile for the zone. With http or https. An example +for the url is "http://www.example.com/example.org.zone". Multiple url +statements can be given, they are tried in turn. If only urls are given +the SOA refresh timer is used to wait for making new downloads. If also +primaries are listed, the primaries are first probed with UDP SOA queries to +see if the SOA serial number has changed, reducing the number of downloads. +If none of the urls work, the primaries are tried with IXFR and AXFR. +For https, the \fBtls\-cert\-bundle\fR and the hostname from the url are used +to authenticate the connection. +.TP +.B allow\-notify: \fI +With allow\-notify you can specify additional sources of notifies. +When notified, the server attempts to first probe and then zone transfer. +If the notify is from a primary, it first attempts that primary. Otherwise +other primaries are attempted. If there are no primaries, but only urls, the +file is downloaded when notified. The primaries from primary: statements are +allowed notify by default. +.TP +.B zonefile: \fI +The filename where the zone is stored. If not given then no zonefile is used. +If the file does not exist or is empty, unbound will attempt to fetch zone +data (eg. from the primary servers). +.TP +.B rpz\-action\-override: \fI +Always use this RPZ action for matching triggers from this zone. Possible action +are: nxdomain, nodata, passthru, drop, disabled and cname. +.TP +.B rpz\-cname\-override: \fI +The CNAME target domain to use if the cname action is configured for +\fBrpz\-action\-override\fR. +.TP +.B rpz\-log: \fI +Log all applied RPZ actions for this RPZ zone. Default is no. +.TP +.B rpz\-log\-name: \fI +Specify a string to be part of the log line, for easy referencing. +.TP +.B tags: \fI +Limit the policies from this RPZ clause to clients with a matching tag. Tags +need to be defined in \fBdefine\-tag\fR and can be assigned to client addresses +using \fBaccess\-control\-tag\fR. Enclose list of tags in quotes ("") and put +spaces between tags. If no tags are specified the policies from this clause will +be applied for all clients. .SH "MEMORY CONTROL EXAMPLE" In the example config settings below memory usage is reduced. Some service levels are lower, notable very large data and a high TCP load are no longer supported. Very large data and high TCP loads are exceptional for the DNS. DNSSEC validation is enabled, just add trust anchors. If you do not have to worry about programs using more than 3 Mb of memory, the below example is not for you. Use the defaults to receive full service, which on BSD\-32bit tops out at 30\-40 Mb after heavy usage. .P .nf # example settings that reduce memory usage server: num\-threads: 1 outgoing\-num\-tcp: 1 # this limits TCP service, uses less buffers. incoming\-num\-tcp: 1 outgoing\-range: 60 # uses less memory, but less performance. msg\-buffer\-size: 8192 # note this limits service, 'no huge stuff'. msg\-cache\-size: 100k msg\-cache\-slabs: 1 rrset\-cache\-size: 100k rrset\-cache\-slabs: 1 infra\-cache\-numhosts: 200 infra\-cache\-slabs: 1 key\-cache\-size: 100k key\-cache\-slabs: 1 neg\-cache\-size: 10k num\-queries\-per\-thread: 30 target\-fetch\-policy: "2 1 0 0 0 0" harden\-large\-queries: "yes" harden\-short\-bufsize: "yes" .fi .SH "FILES" .TP -.I /var/unbound +.I @UNBOUND_RUN_DIR@ default unbound working directory. .TP -.I /var/unbound +.I @UNBOUND_CHROOT_DIR@ default \fIchroot\fR(2) location. .TP -.I /var/unbound/unbound.conf +.I @ub_conf_file@ unbound configuration file. .TP -.I /var/unbound/unbound.pid +.I @UNBOUND_PIDFILE@ default unbound pidfile with process ID of the running daemon. .TP .I unbound.log unbound log file. default is to log to \fIsyslog\fR(3). .SH "SEE ALSO" \fIunbound\fR(8), \fIunbound\-checkconf\fR(8). .SH "AUTHORS" .B Unbound was written by NLnet Labs. Please see CREDITS file in the distribution for further details.