diff options
Diffstat (limited to 'static/freebsd/man5/unbound.conf.5')
| -rw-r--r-- | static/freebsd/man5/unbound.conf.5 | 3239 |
1 files changed, 3239 insertions, 0 deletions
diff --git a/static/freebsd/man5/unbound.conf.5 b/static/freebsd/man5/unbound.conf.5 new file mode 100644 index 00000000..af03aefb --- /dev/null +++ b/static/freebsd/man5/unbound.conf.5 @@ -0,0 +1,3239 @@ +.TH "unbound.conf" "5" "Jul 16, 2025" "NLnet Labs" "unbound 1.23.1" +.\" +.\" 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/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 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<number> +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<seconds> +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<yes or no> +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<yes or no> +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 statistics\-inhibit\-zero: \fI<yes or no> +If enabled, selected extended statistics with a value of 0 are inhibited from +printing with \fIunbound\-control\fR(8). +These are query types, query classes, query opcodes, answer rcodes +(except NOERROR, FORMERR, SERVFAIL, NXDOMAIN, NOTIMPL, REFUSED) and +RPZ actions. +Default is on. +.TP +.B num\-threads: \fI<number> +The number of threads to create to serve clients. Use 1 for no threading. +.TP +.B port: \fI<port number> +The port number, default 53, on which the server responds to queries. +.TP +.B interface: \fI<ip address or interface name [@port]> +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. 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<ip address or interface name [@port]> +Same as interface: (for ease of compatibility with nsd.conf). +.TP +.B interface\-automatic: \fI<yes or 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 interface\-automatic\-ports: \fI<string> +List the port numbers that interface-automatic listens on. If empty, the +default port is listened on. The port numbers are separated by spaces in the +string. Default is "". +.IP +This can be used to have interface automatic to deal with the interface, +and listen on the normal port number, by including it in the list, and +also https or dns over tls port numbers by putting them in the list as well. +.TP +.B outgoing\-interface: \fI<ip address or ip6 netblock> +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> +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<port number or range> +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<port number or range> +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> +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> +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> +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 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<number> +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 1232. The default value is the +same as the default for edns\-buffer\-size. +.TP +.B stream\-wait\-size: \fI<number> +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> +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> +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> +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<number> +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<msec> +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<msec> +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<yes or no> +Perform connect for UDP sockets that mitigates ICMP side channel leakage. +Default is yes. +.TP +.B unknown\-server\-time\-limit: \fI<msec> +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 discard\-timeout: \fI<msec> +The wait time in msec where recursion requests are dropped. This is +to stop a large number of replies from accumulating. They receive +no reply, the work item continues to recurse. It is nice to be a bit +larger than serve\-expired\-client\-timeout if that is enabled. +A value of 1900 msec is suggested. The value 0 disables it. +Default 1900 msec. +.TP +.B wait\-limit: \fI<number> +The number of replies that can wait for recursion, for an IP address. +This makes a ratelimit per IP address of waiting replies for recursion. +It stops very large amounts of queries waiting to be returned to one +destination. The value 0 disables wait limits. Default is 1000. +.TP +.B wait\-limit\-cookie: \fI<number> +The number of replies that can wait for recursion, for an IP address +that sent the query with a valid DNS cookie. Since the cookie validates +the client address, the limit can be higher. Default is 10000. +.TP +.B wait\-limit\-netblock: \fI<netblock> <number> +The wait limit for the netblock. If not given the wait\-limit value is +used. The most specific netblock is used to determine the limit. Useful for +overriding the default for a specific, group or individual, server. +The value -1 disables wait limits for the netblock. +By default the loopback has a wait limit netblock of -1, it is not limited, +because it is separated from the rest of network for spoofed packets. +The loopback addresses 127.0.0.0/8 and ::1/128 are default at -1. +.TP +.B wait\-limit\-cookie\-netblock: \fI<netblock> <number> +The wait limit for the netblock, when the query has a DNS cookie. +If not given, the wait\-limit\-cookie value is used. +The value -1 disables wait limits for the netblock. +The loopback addresses 127.0.0.0/8 and ::1/128 are default at -1. +.TP +.B so\-rcvbuf: \fI<number> +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<number> +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<yes or no> +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<yes or no> +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<yes or no> +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<number> +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> +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> +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<seconds> +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<seconds> +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<seconds> +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 cache\-min\-negative\-ttl: \fI<seconds> +Time to live minimum for negative responses, these have a SOA in the +authority section that is limited in time. +Default is 0 (disabled). +If this is disabled and \fBcache-min-ttl\fR is configured, it will take effect +instead. +In that case you can set this to 1 to honor the upstream TTL. +This applies to nxdomain and nodata answers. +.TP +.B infra\-host\-ttl: \fI<seconds> +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> +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> +Number of hosts for which information is cached. Default is 10000. +.TP +.B infra\-cache\-min\-rtt: \fI<msec> +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\-cache\-max\-rtt: \fI<msec> +Upper limit for dynamic retransmit timeout calculation in infrastructure +cache. Default is 2 minutes. +.TP +.B infra\-keep\-probing: \fI<yes or no> +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<yes or no> +Enable or disable whether ip4 queries are answered or issued. Default is yes. +.TP +.B do\-ip6: \fI<yes or no> +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<yes or no> +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<yes or no> +If enabled, prefer IPv6 transport for sending DNS queries to internet +nameservers. Default is no. +.TP +.B do\-udp: \fI<yes or no> +Enable or disable whether UDP queries are answered or issued. Default is yes. +.TP +.B do\-tcp: \fI<yes or no> +Enable or disable whether TCP queries are answered or issued. Default is yes. +.TP +.B tcp\-mss: \fI<number> +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<number> +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<msec>\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. +It will be overridden by \fBedns\-tcp\-keepalive\-timeout\fR if +\fBedns\-tcp\-keepalive\fR is enabled. +.TP +.B tcp-reuse-timeout: \fI<msec>\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<number>\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<number>\fR +Timeout in milliseconds for TCP queries to auth servers. +This option defaults to 3000 milliseconds. +.TP +.B edns-tcp-keepalive: \fI<yes or no>\fR +Enable or disable EDNS TCP Keepalive. Default is no. +.TP +.B edns-tcp-keepalive-timeout: \fI<msec>\fR +Overrides \fBtcp\-idle\-timeout\fR when \fBedns\-tcp\-keepalive\fR is enabled. +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. +.TP +.B sock\-queue\-timeout: \fI<sec>\fR +UDP queries that have waited in the socket buffer for a long time can be +dropped. Default is 0, disabled. The time is set in seconds, 3 could be a +good value to ignore old queries that likely the client does not need a reply +for any more. This could happen if the host has not been able to service +the queries for a while, i.e. Unbound is not running, and then is enabled +again. It uses timestamp socket options. +.TP +.B tcp\-upstream: \fI<yes or no> +Enable or disable whether the upstream queries use TCP only for transport. +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<yes or no> +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<yes or no> +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 or +tls\-system\-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. +If the tls\-upstream option is enabled, it is for all the forwards and stubs, +where the forward\-tls\-upstream and stub\-tls\-upstream options are ignored, +as if they had been set to yes. +.TP +.B ssl\-upstream: \fI<yes or no> +Alternate syntax for \fBtls\-upstream\fR. If both are present in the config +file the last is used. +.TP +.B tls\-service\-key: \fI<file> +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<file> +Alternate syntax for \fBtls\-service\-key\fR. +.TP +.B tls\-service\-pem: \fI<file> +The public key certificate pem file for the tls service. Default is "", +turned off. +.TP +.B ssl\-service\-pem: \fI<file> +Alternate syntax for \fBtls\-service\-pem\fR. +.TP +.B tls\-port: \fI<number> +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<number> +Alternate syntax for \fBtls\-port\fR. +.TP +.B tls\-cert\-bundle: \fI<file> +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. It is read at start up before +permission drop and chroot. +.TP +.B ssl\-cert\-bundle: \fI<file> +Alternate syntax for \fBtls\-cert\-bundle\fR. +.TP +.B tls\-win\-cert: \fI<yes or no> +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. On other systems, this option +enables the system certificates. +.TP +.B tls\-system\-cert: \fI<yes or no> +This the same setting as the tls\-win\-cert setting, under a different name. +Because it is not windows specific. +.TP +.B tls\-additional\-port: \fI<portnr> +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<file> +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<string with cipher list> +Set the list of ciphers to allow when serving TLS. Use "" for defaults, +and that is the default. +.TP +.B tls\-ciphersuites: \fI<string with ciphersuites list> +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<yes or no> +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<number> +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<yes or no> +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<number> +The block size with which to pad queries sent over TLS upstreams. +Default is 128. +.TP +.B tls\-use\-sni: \fI<yes or no> +Enable or disable sending the SNI extension on TLS connections. +Default is yes. +Changing the value requires a reload. +.TP +.B https\-port: \fI<number> +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<endpoint string> +The HTTP endpoint to provide DNS-over-HTTPS service on. Default "/dns-query". +.TP +.B http\-max\-streams: \fI<number of streams> +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<size in bytes> +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<size in bytes> +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<yes or no> +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<yes or no> +Disable use of TLS for the downstream DNS-over-HTTP connections. Useful for +local back end servers. Default is no. +.TP +.B proxy\-protocol\-port: \fI<portnr> +List port numbers as proxy\-protocol\-port, and when interfaces are defined, +eg. with the @port suffix, as this port number, they support and expect PROXYv2. +In this case the proxy address will only be used for the network communication +and initial ACL (check if the proxy itself is denied/refused by configuration). +The proxied address (if any) will then be used as the true client address and +will be used where applicable for logging, ACL, DNSTAP, RPZ and IP ratelimiting. +PROXYv2 is supported for UDP and TCP/TLS listening interfaces. +There is no support for PROXYv2 on a DoH, DoQ or DNSCrypt listening interface. +Can list multiple, each on a new statement. +.TP +.B quic\-port: \fI<number> +The port number on which to provide DNS-over-QUIC service, default 853, only +interfaces configured with that port number as @number get the QUIC service. +The interface uses QUIC for the UDP traffic on that port number. +.TP +.B quic\-size: \fI<size in bytes> +Maximum number of bytes for all QUIC buffers and data combined. Default is 8 +megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, +megabytes or gigabytes (1024*1024 bytes in a megabyte). New connections receive +connection refused when the limit is exceeded. New streams are reset when the +limit is exceeded. +.TP +.B use\-systemd: \fI<yes or no> +Enable or disable systemd socket activation. +Default is no. +.TP +.B do\-daemonize: \fI<yes or no> +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<IP netblock> <limit> +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<IP netblock> <action> +Specify treatment of incoming queries from their originating IP address. +Queries can be allowed to have access to this server that gives DNS +answers, or refused, with other actions possible. The IP address range +can be specified as a netblock, it is possible to give the statement +several times in order to specify the treatment of different netblocks. +.IP +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, \fIallow_cookie\fR, +\fIdeny_non_local\fR or \fIrefuse_non_local\fR. +The most specific netblock match is used, if none match \fIrefuse\fR is used. +The order of the access\-control statements therefore does not matter. +.IP +The \fIdeny\fR action stops queries from hosts from that netblock. +.IP +The \fIrefuse\fR action stops queries too, but sends a DNS rcode REFUSED +error message back. +.IP +The \fIallow\fR action 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 \fIallow_snoop\fR action 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 +The \fIallow_cookie\fR action allows access only to UDP queries that contain a +valid DNS Cookie as specified in RFC 7873 and RFC 9018, when the +\fBanswer\-cookie\fR option is enabled. +UDP queries containing only a DNS Client Cookie and no Server Cookie, or an +invalid DNS Cookie, will receive a BADCOOKIE response including a newly +generated DNS Cookie, allowing clients to retry with that DNS Cookie. +The \fIallow_cookie\fR action will also accept requests over stateful +transports, regardless of the presence of an DNS Cookie and regardless of the +\fBanswer\-cookie\fR setting. +UDP queries without a DNS Cookie receive REFUSED responses with the TC flag set, +that may trigger fall back to TCP for those clients. +.IP +By default only localhost (the 127.0.0.0/8 IP netblock, not the loopback +interface) is implicitly \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<IP netblock> <"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<IP netblock> <tag> <action> +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<IP netblock> <tag> <"resource record string"> +Set redirect data for particular tag for given access control element. +.TP +.B access\-control\-view: \fI<IP netblock> <view name> +Set view for given access control element. +.TP +.B interface\-action: \fI<ip address or interface name [@port]> <action> +Similar to \fBaccess\-control:\fR but for interfaces. +.IP +The action is the same as the ones defined under \fBaccess\-control:\fR. +Interfaces are \fIrefuse\fRd by default. +By default only localhost (the 127.0.0.0/8 IP netblock, not the loopback +interface) is implicitly \fIallow\fRed through the default +\fBaccess\-control:\fR behavior. +This also means that any attempt to use the \fBinterface-*:\fR options for the +loopback interface will not work as they will be overridden by the implicit +default "\fBaccess\-control:\fR 127.0.0.0/8 allow" option. +.IP +Note that the interface needs to be already specified with \fBinterface:\fR +and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR +settings for targeted clients. +.TP +.B interface\-tag: \fI<ip address or interface name [@port]> <"list of tags"> +Similar to \fBaccess\-control-tag:\fR but for interfaces. +.IP +Note that the interface needs to be already specified with \fBinterface:\fR +and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR +settings for targeted clients. +.TP +.B interface\-tag\-action: \fI<ip address or interface name [@port]> <tag> <action> +Similar to \fBaccess\-control-tag-action:\fR but for interfaces. +.IP +Note that the interface needs to be already specified with \fBinterface:\fR +and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR +settings for targeted clients. +.TP +.B interface\-tag\-data: \fI<ip address or interface name [@port]> <tag> <"resource record string"> +Similar to \fBaccess\-control-tag-data:\fR but for interfaces. +.IP +Note that the interface needs to be already specified with \fBinterface:\fR +and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR +settings for targeted clients. +.TP +.B interface\-view: \fI<ip address or interface name [@port]> <view name> +Similar to \fBaccess\-control-view:\fR but for interfaces. +.IP +Note that the interface needs to be already specified with \fBinterface:\fR +and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR +settings for targeted clients. +.TP +.B chroot: \fI<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. +.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. 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/urandom (for entropy) +from inside the chroot. +.IP +If given a chroot is done to the given directory. The chroot is by default +set to "/var/unbound". If you give "" no chroot is performed. +.TP +.B username: \fI<name> +If given, after binding the port the user privileges are dropped. Default is +"unbound". 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<directory> +Sets the working directory for the program. Default is "/var/unbound". +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<filename> +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<yes or no> +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<string> +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<yes or no> +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\-time\-iso:\fR <yes or no> +Log time in ISO8601 format, if \fBlog\-time\-ascii:\fR yes is also set. +Default is no. +.TP +.B log\-queries: \fI<yes or no> +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<yes or no> +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<yes or no> +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\-destaddr: \fI<yes or no> +Prints the destination address, port and type in the log\-replies output. +This disambiguates what type of traffic, eg. udp or tcp, and to what local +port the traffic was sent to. +.TP +.B log\-local\-actions: \fI<yes or no> +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<yes or no> +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<filename> +The process id is written to the file. Default is "/var/unbound/unbound.pid". +So, +.nf +kill \-HUP `cat /var/unbound/unbound.pid` +.fi +triggers a reload, +.nf +kill \-TERM `cat /var/unbound/unbound.pid` +.fi +gracefully terminates. +.TP +.B root\-hints: \fI<filename> +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<yes or no> +If enabled id.server and hostname.bind queries are refused. +.TP +.B identity: \fI<string> +Set the identity to report. If set to "", the default, then the hostname +of the server is returned. +.TP +.B hide\-version: \fI<yes or no> +If enabled version.server and version.bind queries are refused. +.TP +.B version: \fI<string> +Set the version to report. If set to "", the default, then the package +version is returned. +.TP +.B hide\-http\-user\-agent: \fI<yes or no> +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<string> +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 <string> +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<yes or no> +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<yes or no> +Very small EDNS buffer sizes from queries are ignored. Default is yes, as +described in the standard. +.TP +.B harden\-large\-queries: \fI<yes or no> +Very large queries are ignored. Default is no, 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<yes or no> +Will trust glue only if it is within the servers authority. Default is yes. +.TP +.B harden\-unverified\-glue: \fI<yes or no> +Will trust only in-zone glue. Will try to resolve all out of zone +(\fI<unverfied>) glue. Will fallback to the original glue if unable to resolve. +Default is no. +.TP +.B harden\-dnssec\-stripped: \fI<yes or no> +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 yes. +.TP +.B harden\-below\-nxdomain: \fI<yes or no> +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 yes. +The nxdomain must be secure, this means nsec3 with optout is insufficient. +.TP +.B harden\-referral\-path: \fI<yes or no> +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<yes or no> +Harden against algorithm downgrade when multiple algorithms are +advertised in the DS record. +This works by first choosing only the strongest DS digest type as per RFC 4509 +(Unbound treats the highest algorithm as the strongest) and then +expecting signatures from all the advertised signing algorithms from the chosen +DS(es) to be present. +If no, allows any one supported algorithm to validate the zone, even if other advertised algorithms are broken. +Default is no. +RFC 6840 mandates that zone signers must produce zones signed with all +advertised algorithms, but sometimes they do not. +RFC 6840 also clarifies that this requirement is not for validators and +validators should accept any single valid path. +It should thus be explicitly noted that this option violates RFC 6840 for +DNSSEC validation and should only be used to perform a signature +completeness test to support troubleshooting. +Using this option may break DNSSEC resolution with non-RFC6840-conforming +signers and/or in multi-signer configurations that don't send all the +advertised signatures. +.TP +.B harden\-unknown\-additional: \fI<yes or no> +Harden against unknown records in the authority section and additional +section. Default is no. If no, such records are copied from the upstream +and presented to the client together with the answer. If yes, it could +hamper future protocol developments that want to add records. +.TP +.B use\-caps\-for\-id: \fI<yes or no> +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\-exempt: \fI<domain> +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<domain> +Alternate syntax for \fBcaps\-exempt\fR. +.TP +.B qname\-minimisation: \fI<yes or no> +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<yes or no> +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 no. +.TP +.B aggressive\-nsec: \fI<yes or no> +Aggressive NSEC uses the DNSSEC NSEC chain to synthesize NXDOMAIN +and other denials, using information from previous NXDOMAINs answers. +Default is yes. It helps to reduce the query rate towards targets that get +a very high nonexistent name lookup rate. +.TP +.B private\-address: \fI<IP address or subnet> +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<domain name> +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<number> +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<IP address> +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<yes or no> +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<yes or no> +If yes, cache hits on message cache elements that are on their last 10 percent +of their TTL value trigger a prefetch 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<yes or no> +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<yes or no> +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<yes or no> +If yes, Unbound rotates RRSet order in response (the random number is taken +from the query ID, for speed and thread safety). Default is yes. +.TP +.B minimal-responses: \fI<yes or no> +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 which may +cause a slight speedup. The default is yes, even though the DNS +protocol RFCs mandate these sections, and the additional content could +save roundtrips for clients that use the additional content. +However these sections are hardly used by clients. +Enabling prefetch can benefit clients that need the additional content +by trying to keep that content fresh in the cache. +.TP +.B disable-dnssec-lame-check: \fI<yes or no> +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 \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 +Most modules that need to be listed here have to be listed at the beginning +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. 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<filename> +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<filename> +File with trust anchor for one zone, which is tracked with RFC5011 probes. +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<filename> +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<yes or no> +Send RFC8145 key tag query after trust anchor priming. Default is yes. +.TP +.B root\-key\-sentinel: \fI<yes or no> +Root key trust anchor sentinel. Default is yes. +.TP +.B domain\-insecure: \fI<domain name> +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. +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<rrsig\-style date spec> +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<seconds> +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<seconds> +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<number> +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<number> +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<yes or no> +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<number> +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<yes or no> +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<yes or no> +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 disable\-edns\-do: \fI<yes or no> +Disable the EDNS DO flag in upstream requests. +It breaks DNSSEC validation for Unbound's clients. +This results in the upstream name servers to not include DNSSEC records in +their replies and could be helpful for devices that cannot handle DNSSEC +information. +When the option is enabled, clients that set the DO flag receive no EDNS +record in the response to indicate the lack of support to them. +If this option is enabled but Unbound is already configured for DNSSEC +validation (i.e., the validator module is enabled; default) this option is +implicitly turned off with a warning as to not break DNSSEC validation in +Unbound. +Default is no. +.TP +.B serve\-expired: \fI<yes or no> +If enabled, Unbound attempts to serve old responses from cache with a +TTL of \fBserve\-expired\-reply\-ttl\fR in the response. +By default the expired answer will be used after a resolution attempt errored +out or is taking more than serve\-expired\-client\-timeout to resolve. +Default is "no". +.TP +.B serve\-expired\-ttl: \fI<seconds> +Limit serving of expired responses to configured seconds after expiration. +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 86400. +.TP +.B serve\-expired\-ttl\-reset: \fI<yes or no> +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 +"no". +.TP +.B serve\-expired\-reply\-ttl: \fI<seconds> +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<msec> +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. +Setting this to 0 will disable this behavior and instead serve the expired +record immediately from the cache before attempting to refresh it via +resolution. +Default is 1800. +.TP +.B serve\-original\-ttl: \fI<yes or no> +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 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<yes or no> +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<seconds> +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<seconds> +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<seconds> +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<yes or no> +Debug option that allows the autotrust 5011 rollover timers to assume +very small values. Default is no. +.TP +.B key\-cache\-size: \fI<number> +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> +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> +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<yes or no> +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<yes or no> +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<zone> <type> +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, block_a, 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. A stub\-zone can be used to +have unbound send queries to another server, an authoritative server, to +fetch the information. With a forward\-zone, unbound sends queries to a server +that is a recursive server to fetch the information. With an auth\-zone a +zone can be loaded from file and used, it can be used like a local\-zone +for users downstream, or the auth\-zone information can be used to fetch +information from when resolving like it is an upstream server. The +forward\-zone and auth\-zone options are described in their sections below. +If you want to perform filtering of the information that the users can fetch, +the local\-zone and local\-data statements allow for this, but also the +rpz functionality can be used, described in the RPZ section. +.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'\fIblock_a\fR +Like transparent, but ignores local data and resolves normally all query +types excluding A. For A queries it unconditionally returns NODATA. +Useful in cases when there is a need to explicitly force all apps to use +IPv6 protocol and avoid any queries to IPv4. +.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 home.arpa, +the resolver.arpa, the service.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'\fIresolver.arpa (RFC 9462)\fR +Default content: +.nf +local\-zone: "resolver.arpa." static +local\-data: "resolver.arpa. 10800 IN NS localhost." +local\-data: "resolver.arpa. 10800 IN + SOA localhost. nobody.invalid. 1 3600 1200 604800 10800" +.fi +.TP 10 +\h'5'\fIservice.arpa (draft-ietf-dnssd-srp-25)\fR +Default content: +.nf +local\-zone: "service.arpa." static +local\-data: "service.arpa. 10800 IN NS localhost." +local\-data: "service.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 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 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"<resource record string>" +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<zone> <"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<zone> <IP netblock> <type> +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<IP-netblock> <action> +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<action>\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<IP-netblock> <"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<IP-netblock> <"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<number or 0> +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. Configured forwarders are excluded from +ratelimiting. +.TP 5 +.B ratelimit\-size: \fI<memory size> +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<number> +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<number> +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\-backoff: \fI<yes or no> +If enabled, the ratelimit is treated as a hard failure instead of the default +maximum allowed constant rate. When the limit is reached, traffic is +ratelimited and demand continues to be kept track of for a 2 second rate +window. No traffic is allowed, except for ratelimit\-factor, until demand +decreases below the configured ratelimit for a 2 second rate window. Useful to +set ratelimit to a suspicious rate to aggressively limit unusually high +traffic. Default is off. +.TP 5 +.B ratelimit\-for\-domain: \fI<domain> <number qps or 0> +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<domain> <number qps or 0> +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<number or 0> +Enable global ratelimiting of queries accepted per IP address. +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. +Clients with a valid DNS Cookie will bypass the ratelimit. +If a ratelimit for such clients is still needed, \fBip\-ratelimit\-cookie\fR +can be used instead. +Default is 0 (disabled). +.TP 5 +.B ip\-ratelimit\-cookie: \fI<number or 0> +Enable global ratelimiting of queries accepted per IP address with a valid DNS +Cookie. +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 option could be useful in combination with \fIallow_cookie\fR in an +attempt to mitigate other amplification attacks than UDP reflections (e.g., +attacks targeting Unbound itself) which are already handled with DNS Cookies. +If used, the value is suggested to be higher than \fBip\-ratelimit\fR e.g., +tenfold. +Default is 0 (disabled). +.TP 5 +.B ip\-ratelimit\-size: \fI<memory size> +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<number> +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<number> +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 ip\-ratelimit\-backoff: \fI<yes or no> +If enabled, the ratelimit is treated as a hard failure instead of the default +maximum allowed constant rate. When the limit is reached, traffic is +ratelimited and demand continues to be kept track of for a 2 second rate +window. No traffic is allowed, except for ip\-ratelimit\-factor, until demand +decreases below the configured ratelimit for a 2 second rate window. Useful to +set ip\-ratelimit to a suspicious rate to aggressively limit unusually high +traffic. Default is off. +.TP 5 +.B outbound\-msg\-retry: \fI<number> +The number of retries, per upstream nameserver in a delegation, that Unbound +will attempt in case a throwaway response is received. +No response (timeout) contributes to the retry counter. +If a forward/stub zone is used, this is the number of retries per nameserver in +the zone. +Default is 5. +.TP 5 +.B max\-sent\-count: \fI<number> +Hard limit on the number of outgoing queries Unbound will make while resolving +a name, making sure large NS sets do not loop. +Results in SERVFAIL when reached. +It resets on query restarts (e.g., CNAME) and referrals. +Default is 32. +.TP 5 +.B max\-query\-restarts: \fI<number> +Hard limit on the number of times Unbound is allowed to restart a query upon +encountering a CNAME record. +Results in SERVFAIL when reached. +Changing this value needs caution as it can allow long CNAME chains to be +accepted, where Unbound needs to verify (resolve) each link individually. +Default is 11. +.TP 5 +.B iter\-scrub\-ns: \fI<number> +Limit on the number of NS records allowed in an rrset of type NS, from the +iterator scrubber. This protects the internals of the resolver from overly +large NS sets. Default is 20. +.TP 5 +.B iter\-scrub\-cname: \fI<number> +Limit on the number of CNAME, DNAME records in an answer, from the iterator +scrubber. This protects the internals of the resolver from overly long +indirection chains. Clips off the remainder of the reply packet at that point. +Default is 11. +.TP 5 +.B max\-global\-quota: \fI<number> +Limit on the number of upstream queries sent out for an incoming query and +its subqueries from recursion. It is not reset during the resolution. When +it is exceeded the query is failed and the lookup process stops. +Default is 200. +.TP 5 +.B fast\-server\-permil: \fI<number> +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<number> +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 answer\-cookie: \fI<yes or no> +If enabled, Unbound will answer to requests containing DNS Cookies as +specified in RFC 7873 and RFC 9018. +Default is no. +.TP 5 +.B cookie\-secret: \fI<128 bit hex string> +Server's secret for DNS Cookie generation. +Useful to explicitly set for servers in an anycast deployment that need to +share the secret in order to verify each other's Server Cookies. +An example hex string would be "000102030405060708090a0b0c0d0e0f". +Default is a 128 bits random secret generated at startup time. +This option is ignored if a \fBcookie\-secret\-file\fR is +present. In that case the secrets from that file are used in DNS Cookie +calculations. +.TP 5 +.B cookie\-secret\-file: \fI<filename> +File from which the secrets are read used in DNS Cookie calculations. When this +file exists, the secrets in this file are used and the secret specified by the +\fBcookie-secret\fR option is ignored. +Enable it by setting a filename, like "/usr/local/etc/unbound_cookiesecrets.txt". +The content of this file must be manipulated with the \fBadd_cookie_secret\fR, +\fBdrop_cookie_secret\fR and \fBactivate_cookie_secret\fR commands to the +\fIunbound\-control\fR(8) tool. Please see that manpage on how to perform a +safe cookie secret rollover. +Default is "" (disabled). +.TP 5 +.B edns\-client\-string: \fI<IP netblock> <string> +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<opcode> +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. +.TP 5 +.B ede: \fI<yes or no> +If enabled, Unbound will respond with Extended DNS Error codes (RFC8914). +These EDEs provide additional information with a response mainly for, but not +limited to, DNS and DNSSEC errors. + +When the \fBval-log-level\fR option is also set to \fB2\fR, responses with +Extended DNS Errors concerning DNSSEC failures will also contain a descriptive +text message about the reason for the failure. +Default is "no". +.TP 5 +.B ede\-serve\-expired: \fI<yes or no> +If enabled, Unbound will attach an Extended DNS Error (RFC8914) Code 3 - Stale +Answer as EDNS0 option to the expired response. +The \fBede\fR option needs to be enabled as well for this to work. +Default is "no". +.TP 5 +.B dns\-error\-reporting: \fI<yes or no> +If enabled, Unbound will send DNS Error Reports (RFC9567). +The name servers need to express support by attaching the Report-Channel EDNS0 +option on their replies specifying the reporting agent for the zone. +Any errors encountered during resolution that would result in Unbound +generating an Extended DNS Error (RFC8914) will be reported to the zone's +reporting agent. +The \fBede\fR option does not need to be enabled for this to work. +It is advised that the \fBqname\-minimisation\fR option is also enabled to +increase privacy on the outgoing reports. +Default is "no". +.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<yes or no> +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<ip address or interface name or path> +Give IPv4 or IPv6 addresses or local socket path to listen on for +control commands. +If an interface name is used instead of an ip address, the list of ip addresses +on that interface are used. +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 unix domain socket is used. This 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<port number> +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<yes or no> +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<private key file> +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<certificate file.pem> +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<private key file> +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<certificate file.pem> +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: +<ip address of host[@port]>. +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<domain name> +Name of the stub zone. This is the full domain name of the zone. +.TP +.B stub\-host: \fI<domain name> +Name of stub zone nameserver. Is itself resolved before it is used. +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. If only '#' is used the default port is the +configured tls\-port. +.TP +.B stub\-addr: \fI<IP address> +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. If only '#' is used the default port is the +configured tls\-port. +.TP +.B stub\-prime: \fI<yes or no> +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<yes or no> +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<yes or no> +Enabled or disable whether the queries to this stub use TLS for transport. +Default is no. +.TP +.B stub\-ssl\-upstream: \fI<yes or no> +Alternate syntax for \fBstub\-tls\-upstream\fR. +.TP +.B stub\-tcp\-upstream: \fI<yes or no> +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<yes or no> +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<domain name> +Name of the forward zone. This is the full domain name of the zone. +.TP +.B forward\-host: \fI<domain name> +Name of server to forward to. Is itself resolved before it is used. +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. If only '#' is used the default port is the +configured tls\-port. +.TP +.B forward\-addr: \fI<IP address> +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. If only '#' is used the default port is the +configured tls\-port. +.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<yes or no> +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<yes or no> +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<yes or no> +Alternate syntax for \fBforward\-tls\-upstream\fR. +.TP +.B forward\-tcp\-upstream: \fI<yes or no> +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<yes or no> +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 can be processed on two distinct, non-exclusive, configurable +stages. +.LP +With \fBfor\-downstream:\fR \fIyes\fR (default), authority zones are processed +after \fBlocal\-zones\fR and before cache. +When used in this manner, Unbound responds like an authority server with no +further processing other than returning an answer from the zone contents. +A notable example, in this case, is CNAME records which are returned verbatim +to downstream clients without further resolution. +.LP +With \fBfor\-upstream:\fR \fIyes\fR (default), authority zones are processed +after the cache lookup, just before going to the network to fetch +information for recursion. +When used in this manner they provide a local copy of an authority server +that speeds up lookups for that data during resolving. +.LP +If both options are enabled (default), client queries for an authority zone are +answered authoritatively from Unbound, while internal queries that require data +from the authority zone consult the local zone data instead of going to the +network. +.LP +An interesting configuration is \fBfor\-downstream:\fR \fIno\fR, +\fBfor\-upstream:\fR \fIyes\fR that allows for hyperlocal behavior where both +client and internal queries consult the local zone data while resolving. +In this case, the aforementioned CNAME example will result in a thoroughly +resolved answer. +.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 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<zone name> +Name of the authority zone. +.TP +.B primary: \fI<IP address or host name> +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<IP address or host name> +Alternate syntax for \fBprimary\fR. +.TP +.B url: \fI<url to zonefile> +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. +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<IP address or host name or netblockIP/prefix> +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: and url: +statements are allowed notify by default. +.TP +.B fallback\-enabled: \fI<yes or no> +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<yes or no> +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<yes or no> +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<yes or no> +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<yes or no> +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<filename> +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). +.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<view name> +Name of the view. Must be unique. This name is used in access\-control\-view +elements. +.TP +.B local\-zone: \fI<zone> <type> +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"<resource record string>" +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<yes or no> +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). 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<python file>\fR +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<dynlib file>\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 directive +e.g., "dns64 validator iterator" and be compiled into the daemon to be +enabled. These settings go in the \fBserver:\fR section. +.TP +.B dns64\-prefix: \fI<IPv6 prefix>\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<yes or no>\fR +Debug option, default no. If enabled, synthesize all AAAA records +despite the presence of actual AAAA records. +.TP +.B dns64\-ignore\-aaaa: \fI<name>\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 "NAT64 Operation" +.LP +NAT64 operation allows using a NAT64 prefix for outbound requests to IPv4-only +servers. It is controlled by two options in the \fBserver:\fR section: +.TP +.B do\-nat64: \fI<yes or no>\fR +Use NAT64 to reach IPv4-only servers. +Consider also enabling \fBprefer\-ip6\fR to prefer native IPv6 connections to +nameservers. +Default no. +.TP +.B nat64\-prefix: \fI<IPv6 prefix>\fR +Use a specific NAT64 prefix to reach IPv4-only servers. Defaults to using +the prefix configured in \fBdns64\-prefix\fR, which in turn defaults to +64:ff9b::/96. The prefix length must be one of /32, /40, /48, /56, /64 or /96. +.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<yes or no>\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<port number> +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<provider name>\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<path to secret key file>\fR +Path to the time limited secret key file. This option may be specified multiple +times. +.TP +.B dnscrypt\-provider\-cert: \fI<path to cert file>\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<path to cert file>\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<memory size> +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<number> +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<memory size> +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<number> +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 directive e.g., +"subnetcache validator iterator" and be compiled into the daemon to be +enabled. These settings go in the \fBserver:\fR section. +.LP +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 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. +.LP +Note that due to the nature of how EDNS Client Subnet works, by segregating the +client IP space in order to try and have tailored responses for prefixes of +unknown sizes, resolution and cache response performance are impacted as a +result. +Usage of the subnetcache module should only be enabled in installations that +require such functionality where the resolver and the clients belong to +different networks. +An example of that is an open resolver installation. +.LP +This module does not interact with the \fBserve\-expired*\fR and +\fBprefetch:\fR options. +.TP +.B send\-client\-subnet: \fI<IP address>\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<domain>\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<yes or no>\fR +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 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<number>\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<number>\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<number>\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<number>\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<number>\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<number>\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 directive +e.g., "ipsecmod validator iterator" and be compiled into Unbound by using +\fB\-\-enable\-ipsecmod\fR 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<yes or no>\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<filename>\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<yes or no>\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<seconds>\fR +Time to live maximum for A/AAAA cached records after calling the external hook. +Defaults to 3600. +.TP +.B ipsecmod-ignore-bogus: \fI<yes or no>\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\-allow: \fI<domain>\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<domain> +Alternate syntax for \fBipsecmod\-allow\fR. +.SS "Cache DB Module Options" +.LP +The Cache DB module must be configured in the \fBmodule\-config:\fR directive +e.g., "validator cachedb iterator" 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. +.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<backend name>\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". +.TP +.B cachedb-no-store: \fI<yes or no>\fR +If the backend should be read from, but not written to. This makes this +instance not store dns messages in the backend. But if data is available it +is retrieved. The default is no. +.TP +.B cachedb-check-when-serve-expired: \fI<yes or no>\fR +If enabled, the cachedb is checked before an expired response is returned. +When \fBserve\-expired\fR is enabled, without \fBserve\-expired\-client\-timeout\fR, it then +does not immediately respond with an expired response from cache, but instead +first checks the cachedb for valid contents, and if so returns it. If the +cachedb also has no valid contents, the serve expired response is sent. +If also \fBserve\-expired\-client\-timeout\fR is enabled, the expired response +is delayed until the timeout expires. Unless the lookup succeeds within the +timeout. The default is yes. +.P +The following +.B cachedb +options are specific to the redis backend. +.TP +.B redis-server-host: \fI<server address or name>\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<port number>\fR +The TCP port number of the Redis server. +This option defaults to 6379. +.TP +.B redis-server-path: \fI<unix socket path>\fR +The unix socket path to connect to the Redis server. Off by default, and it +can be set to "" to turn this off. Unix sockets may have better throughput +than the IP address option. +.TP +.B redis-server-password: \fI"<password>"\fR +The Redis AUTH password to use for the Redis server. +Only relevant if Redis is configured for client password authorisation. +Off by default, and it can be set to "" to turn this off. +.TP +.B redis-timeout: \fI<msec>\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-command-timeout: \fI<msec>\fR +The timeout to use for Redis commands, in milliseconds. +If 0, it uses the \fBredis\-timeout\fR value. +The default is 0. +.TP +.B redis-connect-timeout: \fI<msec>\fR +The timeout to use for Redis connection set up, in milliseconds. +If 0, it uses the \fBredis\-timeout\fR value. +The default is 0. +.TP +.B redis-expire-records: \fI<yes or no> +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. +.TP +.B redis-logical-db: \fI<logical database index> +The logical database in Redis to use. +These are databases in the same Redis instance sharing the same configuration +and persisted in the same RDB/AOF file. +If unsure about using this option, Redis documentation +(https://redis.io/commands/select/) suggests not to use a single Redis instance +for multiple unrelated applications. +The default database in Redis is 0 while other logical databases need to be +explicitly SELECT'ed upon connecting. +This option defaults to 0. +.TP +.B redis-replica-server-host: \fI<server address or name>\fR +The IP (either v6 or v4) address or domain name of the Redis replica 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 server is treated as a read-only replica server +(https://redis.io/docs/management/replication/#read-only-replica). +If specified, all Redis read commands will go to this replica server, while +the write commands will go to the \fBredis-server-host\fR. +This option defaults to "" (disabled). +.TP +.B redis-replica-server-port: \fI<port number>\fR +The TCP port number of the Redis replica server. +This option defaults to 6379. +.TP +.B redis-replica-server-path: \fI<unix socket path>\fR +The unix socket path to connect to the Redis server. Off by default, and it +can be set to "" to turn this off. Unix sockets may have better throughput +than the IP address option. +.TP +.B redis-replica-server-password: \fI"<password>"\fR +The Redis AUTH password to use for the Redis replica server. +Only relevant if Redis is configured for client password authorisation. +Off by default, and it can be set to "" to turn this off. +.TP +.B redis-replica-timeout: \fI<msec>\fR +The period until when Unbound waits for a response from the Redis replica sever. +If this timeout expires Unbound closes the connection, treats it as +if the Redis replica 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-replica-command-timeout: \fI<msec>\fR +The timeout to use for Redis replica commands, in milliseconds. +If 0, it uses the \fBredis\-replica\-timeout\fR value. +The default is 0. +.TP +.B redis-replica-connect-timeout: \fI<msec>\fR +The timeout to use for Redis replica connection set up, in milliseconds. +If 0, it uses the \fBredis\-replica\-timeout\fR value. +The default is 0. +.TP +.B redis-replica-logical-db: \fI<logical database index> +Same as \fBredis-logical-db\fR but for the Redis replica server. +This option defaults to 0. +.SS DNSTAP Logging Options +DNSTAP support, when compiled in by using \fB\-\-enable\-dnstap\fR, 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<yes or no> +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<yes or no> +Use frame streams in bidirectional mode to transfer DNSTAP messages. Default is +yes. +.TP +.B dnstap-socket-path: \fI<file name> +Sets the unix socket file name for connecting to the server that is +listening on that socket. Default is "". +.TP +.B dnstap-ip: \fI<IPaddress[@port]> +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<yes or no> +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<name of TLS authentication> +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<file name of cert bundle> +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<file name> +The client key file for TLS client authentication. If "" client +authentication is not used. Default is "". +.TP +.B dnstap-tls-client-cert-file: \fI<file name> +The client cert file for TLS client authentication. Default is "". +.TP +.B dnstap-send-identity: \fI<yes or no> +If enabled, the server identity is included in the log messages. +Default is no. +.TP +.B dnstap-send-version: \fI<yes or no> +If enabled, the server version if included in the log messages. +Default is no. +.TP +.B dnstap-identity: \fI<string> +The identity to send with messages, if "" the hostname is used. +Default is "". +.TP +.B dnstap-version: \fI<string> +The version to send with messages, if "" the package version is used. +Default is "". +.TP +.B dnstap-sample-rate: \fI<number> +The sample rate for log of messages, it logs only 1/N messages. With 0 it +is disabled. Default is 0. This is useful in a high volume environment, +where log functionality would otherwise not be reliable. For example 10 +would spend only 1/10th time on logging, and 100 would only spend a +hundredth of the time on logging. +.TP +.B dnstap-log-resolver-query-messages: \fI<yes or no> +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<yes or no> +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<yes or no> +Enable to log client query messages. Default is no. +These are client queries to Unbound. +.TP +.B dnstap-log-client-response-messages: \fI<yes or no> +Enable to log client response messages. Default is no. +These are responses from Unbound to clients. +.TP +.B dnstap-log-forwarder-query-messages: \fI<yes or no> +Enable to log forwarder query messages. Default is no. +.TP +.B dnstap-log-forwarder-response-messages: \fI<yes or no> +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 and +any match from an earlier RPZ zone will terminate the RPZ lookup. Note that a +PASSTHRU action is still considered a match. +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 a regular DNS zone 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 <netblocklen>.<ip address in reverse>. +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<zone name> +Name of the authority zone. +.TP +.B primary: \fI<IP address or host name> +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<IP address or host name> +Alternate syntax for \fBprimary\fR. +.TP +.B url: \fI<url to zonefile> +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<IP address or host name or netblockIP/prefix> +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: and url: +statements are allowed notify by default. +.TP +.B zonefile: \fI<filename> +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<action> +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<domain> +The CNAME target domain to use if the cname action is configured for +\fBrpz\-action\-override\fR. +.TP +.B rpz\-log: \fI<yes or no> +Log all applied RPZ actions for this RPZ zone. Default is no. +.TP +.B rpz\-log\-name: \fI<name> +Specify a string to be part of the log line, for easy referencing. +.TP +.B rpz\-signal\-nxdomain\-ra: \fI<yes or no> +Signal when a query is blocked by the RPZ with NXDOMAIN with an unset RA flag. +This allows certain clients, like dnsmasq, to infer that the domain is +externally blocked. Default is no. +.TP +.B for\-downstream: \fI<yes or no> +If enabled the zone is authoritatively answered for and queries for the RPZ +zone information are answered to downstream clients. This is useful for +monitoring scripts, that can then access the SOA information to check if +the RPZ information is up to date. Default is no. +.TP +.B tags: \fI<list of tags> +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 +default Unbound working directory. +.TP +.I /var/unbound +default +\fIchroot\fR(2) +location. +.TP +.I /var/unbound/unbound.conf +Unbound configuration file. +.TP +.I /var/unbound/unbound.pid +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. |