diff options
Diffstat (limited to 'external/unbound/doc/unbound.conf.5.in')
| -rw-r--r-- | external/unbound/doc/unbound.conf.5.in | 1578 |
1 files changed, 0 insertions, 1578 deletions
diff --git a/external/unbound/doc/unbound.conf.5.in b/external/unbound/doc/unbound.conf.5.in deleted file mode 100644 index b2c76ac95..000000000 --- a/external/unbound/doc/unbound.conf.5.in +++ /dev/null @@ -1,1578 +0,0 @@ -.TH "unbound.conf" "5" "Jun 13, 2017" "NLnet Labs" "unbound 1.6.3" -.\" -.\" unbound.conf.5 -- unbound.conf manual -.\" -.\" Copyright (c) 2007, NLnet Labs. All rights reserved. -.\" -.\" See LICENSE for the license. -.\" -.\" -.SH "NAME" -.B unbound.conf -\- Unbound configuration file. -.SH "SYNOPSIS" -.B unbound.conf -.SH "DESCRIPTION" -.B unbound.conf -is used to configure -\fIunbound\fR(8). -The file format has attributes and values. Some attributes have attributes inside them. -The notation is: attribute: value. -.P -Comments start with # and last to the end of line. Empty lines are -ignored as is whitespace at the beginning of a line. -.P -The utility -\fIunbound\-checkconf\fR(8) -can be used to check unbound.conf prior to usage. -.SH "EXAMPLE" -An example config file is shown below. Copy this to /etc/unbound/unbound.conf -and start the server with: -.P -.nf - $ unbound \-c /etc/unbound/unbound.conf -.fi -.P -Most settings are the defaults. Stop the server with: -.P -.nf - $ kill `cat /etc/unbound/unbound.pid` -.fi -.P -Below is a minimal config file. The source distribution contains an extensive -example.conf file with all the options. -.P -.nf -# unbound.conf(5) config file for unbound(8). -server: - directory: "/etc/unbound" - username: unbound - # make sure unbound can access entropy from inside the chroot. - # e.g. on linux the use these commands (on BSD, devfs(8) is used): - # mount \-\-bind \-n /dev/random /etc/unbound/dev/random - # and mount \-\-bind \-n /dev/log /etc/unbound/dev/log - chroot: "/etc/unbound" - # logfile: "/etc/unbound/unbound.log" #uncomment to use logfile. - pidfile: "/etc/unbound/unbound.pid" - # verbosity: 1 # uncomment and increase to get more logging. - # listen on all interfaces, answer queries from the local subnet. - interface: 0.0.0.0 - interface: ::0 - access\-control: 10.0.0.0/8 allow - access\-control: 2001:DB8::/64 allow -.fi -.SH "FILE FORMAT" -There must be whitespace between keywords. Attribute keywords end with a colon ':'. An attribute -is followed by its containing attributes, or a value. -.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). -.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. 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 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[@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. -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[@port]> -Same as interface: (for easy of compatibility with nsd.conf). -.TP -.B interface\-automatic: \fI<yes or no> -Detect source interface on UDP queries and copy them to replies. This -feature is experimental, and needs support in your OS for particular socket -options. Default value is no. -.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 4096 which is RFC recommended. -If you have fragmentation reassembly problems, usually seen as timeouts, -then a value of 1480 can fix it. Setting to 512 bypasses even the most -stringent path MTU problems, but is seen as extreme, since the amount -of TCP fallback generated is excessive (probably also for this resolver, -consider tuning the outgoing tcp number). -.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 4096. -.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 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 no. 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. -.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\-existant 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. -.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 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). If the maximum kicks in, responses to clients -still get decrementing TTLs based on the original (larger) values. -When the internal 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. -.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. -.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 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\-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\-upstream: \fI<yes or no> -Enable or disable whether the upstream queries use TCP only for transport. -Default is no. Useful in tunneling scenarios. -.TP -.B ssl\-upstream: \fI<yes or no> -Enabled or disable whether the upstream queries use SSL only for transport. -Default is no. Useful in tunneling scenarios. The SSL contains plain DNS in -TCP wireformat. The other server must support this (see \fBssl\-service\-key\fR). -.TP -.B ssl\-service-key: \fI<file> -If enabled, the server provider SSL service on its TCP sockets. The clients -have to use ssl\-upstream: yes. The file is the private key for the TLS -session. The public certificate is in the ssl\-service\-pem file. Default -is "", turned off. Requires a restart (a reload is not enough) if changed, -because the private key is read while root permissions are held and before -chroot (if any). Normal DNS TCP service is not provided and gives errors, -this service is best run with a different \fBport:\fR config or \fI@port\fR -suffixes in the \fBinterface\fR config. -.TP -.B ssl\-service\-pem: \fI<file> -The public key certificate pem file for the ssl service. Default is "", -turned off. -.TP -.B ssl\-port: \fI<number> -The port number on which to provide TCP SSL service, default 853, only -interfaces configured with that port number as @number get the SSL service. -.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 access\-control: \fI<IP netblock> <action> -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_snoop\fR, \fIdeny_non_local\fR or \fIrefuse_non_local\fR. -The most specific netblock match is used, if none match \fIdeny\fR is used. -.IP -The action \fIdeny\fR stops queries from hosts from that netblock. -.IP -The action \fIrefuse\fR stops queries too, but sends a DNS rcode REFUSED -error message back. -.IP -The action \fIallow\fR gives access to clients from that netblock. -It gives only access for recursion clients (which is -what almost all clients need). Nonrecursive queries are refused. -.IP -The \fIallow\fR action does allow nonrecursive queries to access the -local\-data that is configured. The reason is that this does not involve -the unbound server recursive lookup algorithm, and static data is served -in the reply. This supports normal operations where nonrecursive queries -are made for the authoritative data. For nonrecursive queries any replies -from the dynamic cache are refused. -.IP -The action \fIallow_snoop\fR gives nonrecursive access too. This give -both recursive and non recursive access. The name \fIallow_snoop\fR refers -to cache snooping, a technique to use nonrecursive queries to examine -the cache contents (for malicious acts). However, nonrecursive queries can -also be a valuable debugging tool (when you want to examine the cache -contents). In that case use \fIallow_snoop\fR for your administration host. -.IP -By default only localhost is \fIallow\fRed, the rest is \fIrefuse\fRd. -The default is \fIrefuse\fRd, because that is protocol\-friendly. The DNS -protocol is not designed to handle dropped packets due to policy, and -dropping may result in (possibly excessive) retried queries. -.IP -The deny_non_local and refuse_non_local settings are for hosts that are -only allowed to query for the authoritative local\-data, they are not -allowed full recursion but only the static data. With deny_non_local, -messages that are disallowed are dropped, with refuse_non_local they -receive error code REFUSED. -.TP -.B access\-control\-tag: \fI<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 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. -.IP -Additionally, unbound may need to access /dev/random (for entropy) -from inside the chroot. -.IP -If given a chroot is done to the given directory. The default is -"@UNBOUND_CHROOT_DIR@". 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_USERNAME@". If you give username: "" no user change is performed. -.IP -If this user is not capable of binding the -port, reloads (by signal HUP) will still retain the opened ports. -If you change the port number in the config file, and that new port number -requires privileges, then a reload will fail; a restart is needed. -.TP -.B directory: \fI<directory> -Sets the working directory for the program. Default is "@UNBOUND_RUN_DIR@". -On Windows the string "%EXECUTABLE%" tries to change to the directory -that unbound.exe resides in. -If you give a server: directory: dir before include: file statements -then those includes can be relative to the working directory. -.TP -.B logfile: \fI<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\-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 pidfile: \fI<filename> -The process id is written to the file. Default is "@UNBOUND_PIDFILE@". -So, -.nf -kill \-HUP `cat @UNBOUND_PIDFILE@` -.fi -triggers a reload, -.nf -kill \-TERM `cat @UNBOUND_PIDFILE@` -.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\-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 off, since -it is legal protocol wise to send these, and unbound tries to give very -small answers to these queries, where possible. -.TP -.B harden\-large\-queries: \fI<yes or no> -Very large queries are ignored. Default is off, since it is legal protocol -wise to send these, and could be necessary for operation if TSIG or EDNS -payload is very large. -.TP -.B harden\-glue: \fI<yes or no> -Will trust glue only if it is within the servers authority. Default is on. -.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 on. -.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 off. -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 off, 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. If no, allows the weakest algorithm to -validate the zone. Default is no. Zone signers must produce zones -that allow this feature to work, but sometimes they do not, and turning -this option off avoids that validation failure. -.TP -.B use\-caps\-for\-id: \fI<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\-whitelist: \fI<domain> -Whitelist 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 qname\-minimisation: \fI<yes or no> -Send minimum amount of information to upstream servers to enhance privacy. -Only sent minimum required labels of the QNAME and set QTYPE to NS 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 off. -.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 off. -.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, message cache elements are prefetched before they expire to -keep the cache up to date. Default is no. Turning it on gives about -10 percent more traffic and load on the machine, but popular items do -not expire from the cache. -.TP -.B prefetch-key: \fI<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 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 no. -.TP -.B minimal-responses: \fI<yes or no> -If yes, Unbound doesn't insert authority/additional sections into response -messages when those sections are not required. This reduces response -size significantly, and may avoid TCP fallback for some responses. -This may cause a slight speedup. The default is no, because the DNS -protocol RFCs mandate these sections, and the additional content could -be of use and save roundtrips for clients. -.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 validator, iterator. -Setting this to "iterator" will result in a non\-validating server. -Setting this to "validator iterator" will turn on DNSSEC validation. -The ordering of the modules is important. -You must also set trust\-anchors for validation to be useful. -.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 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 dlv\-anchor\-file: \fI<filename> -This option was used during early days DNSSEC deployment when no parent-side -DS record registrations were easily available. Nowadays, it is best to have -DS records registered with the parent zone (many top level zones are signed). -File with trusted keys for DLV (DNSSEC Lookaside Validation). Both DS and -DNSKEY entries can be used in the file, in the same format as for -\fItrust\-anchor\-file:\fR statements. Only one DLV can be configured, more -would be slow. The DLV configured is used as a root trusted DLV, this -means that it is a lookaside for the root. Default is "", or no dlv anchor file. -DLV is going to be decommissioned. Please do not use it any more. -.TP -.B dlv\-anchor: \fI<"Resource Record"> -Much like trust\-anchor, this is a DLV anchor with the DS or DNSKEY inline. -DLV is going to be decommissioned. Please do not use it any more. -.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. -Also keys from DLV are ignored for the domain. 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\-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 serve\-expired: \fI<yes or no> -If enabled, unbound attempts to serve old responses from cache with a -TTL of 0 in the response without waiting for the actual resolution to finish. -The actual resolution answer ends up in the cache later on. Default is "no". -.TP -.B val\-nsec3\-keysize\-iterations: \fI<"list of values"> -List of keysize and iteration count values, separated by spaces, surrounded -by quotes. Default is "1024 150 2048 500 4096 2500". This determines the -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 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<yesno> -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<yesno> -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, -always_transparent, always_refuse, always_nxdomain, -and are explained below. After that the default settings are listed. Use -local\-data: to enter data into the local zone. Answers for local zones -are authoritative DNS answers. By default the zones are class IN. -.IP -If you need more complicated authoritative data, with referrals, wildcards, -CNAME/DNAME support, or DNSSEC authoritative service, setup a stub\-zone for -it as detailed in the stub zone section below. -.TP 10 -\h'5'\fIdeny\fR -Do not send an answer, drop the query. -If there is a match from local data, the query is answered. -.TP 10 -\h'5'\fIrefuse\fR -Send an error message reply, with rcode REFUSED. -If there is a match from local data, the query is answered. -.TP 10 -\h'5'\fIstatic\fR -If there is a match from local data, the query is answered. -Otherwise, the query is answered with nodata or nxdomain. -For a negative answer a SOA is included in the answer if present -as local\-data for the zone apex domain. -.TP 10 -\h'5'\fItransparent\fR -If there is a match from local data, the query is answered. -Otherwise if the query has a different name, the query is resolved normally. -If the query is for a name given in localdata but no such type of data is -given in localdata, then a noerror nodata answer is returned. -If no local\-zone is given local\-data causes a transparent zone -to be created by default. -.TP 10 -\h'5'\fItypetransparent\fR -If there is a match from local data, the query is answered. If the query -is for a different name, or for the same name but for a different type, -the query is resolved normally. So, similar to transparent but types -that are not listed in local data are resolved normally, so if an A record -is in the local data that does not cause a nodata reply for AAAA queries. -.TP 10 -\h'5'\fIredirect\fR -The query is answered from the local data for the zone name. -There may be no local data beneath the zone name. -This answers queries for the zone, and all subdomains of the zone -with the local data for the zone. -It can be used to redirect a domain to return a different address record -to the end user, with -local\-zone: "example.com." redirect and -local\-data: "example.com. A 127.0.0.1" -queries for www.example.com and www.foo.example.com are redirected, so -that users with web browsers cannot access sites with suffix example.com. -.TP 10 -\h'5'\fIinform\fR -The query is answered normally, same as transparent. The client IP -address (@portnumber) is printed to the logfile. The log message is: -timestamp, unbound-pid, info: zonename inform IP@port queryname type -class. This option can be used for normal resolution, but machines -looking up infected names are logged, eg. to run antivirus on them. -.TP 10 -\h'5'\fIinform_deny\fR -The query is dropped, like 'deny', and logged, like 'inform'. Ie. find -infected machines without answering the queries. -.TP 10 -\h'5'\fIalways_transparent\fR -Like transparent, but ignores local data and resolves normally. -.TP 10 -\h'5'\fIalways_refuse\fR -Like refuse, but ignores local data and refuses the query. -.TP 10 -\h'5'\fIalways_nxdomain\fR -Like static, but ignores local data and returns nxdomain for the query. -.TP 10 -\h'5'\fInodefault\fR -Used to turn off default contents for AS112 zones. The other types -also turn off default contents for the zone. The 'nodefault' option -has no other effect than turning off default contents for the -given zone. Use \fInodefault\fR if you use exactly that zone, if you want to -use a subzone, use \fItransparent\fR. -.P -The default zones are localhost, reverse 127.0.0.1 and ::1, the onion 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." static -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'\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'\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. -.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 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. -.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\-for\-domain: \fI<domain> <number qps> -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. -.TP 5 -.B ratelimit\-below\-domain: \fI<domain> <number qps> -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. -.TP 5 -.B ip\-ratelimit: \fI<number or 0> -Enable global ratelimiting of queries accepted per ip address. -If 0, the default, it is disabled. This option is experimental at this time. -The ratelimit is in queries per second that are allowed. More queries are -completely dropped and will not receive a reply, SERVFAIL or otherwise. -IP ratelimiting happens before looking in the cache. This may be useful for -mitigating amplification attacks. -.TP 5 -.B ip\-ratelimit\-size: \fI<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. -.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 SSLv3 / 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 path> -Give IPv4 or IPv6 addresses or local socket path to listen on for -control commands. -By default localhost (127.0.0.1 and ::1) is listened to. -Use 0.0.0.0 and ::0 to listen to all interfaces. -If you change this and permissions have been dropped, you must restart -the server for the change to take effect. -.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> -Whether to require certificate authentication of control connections. -The default is "yes". -This should not be changed unless there are other mechanisms in place -to prevent untrusted users from accessing the remote control -interface. -.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. -.TP -.B stub\-host: \fI<domain name> -Name of stub zone nameserver. Is itself resolved before it is used. -.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. -.TP -.B stub\-prime: \fI<yes or no> -This option is by default off. 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\-ssl\-upstream: \fI<yes or no> -Enabled or disable whether the queries to this stub use SSL for transport. -Default is no. -.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. -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. -.TP -.B forward\-host: \fI<domain name> -Name of server to forward to. Is itself resolved before it is used. -.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. -.TP -.B forward\-first: \fI<yes or no> -If enabled, a query is attempted without the forward 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 forward\-ssl\-upstream: \fI<yes or no> -Enabled or disable whether the queries to this forwarder use SSL for transport. -Default is no. -.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. 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. -.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. -.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). -.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. -.SS "DNS64 Module Options" -.LP -The dns64 module must be configured in the \fBmodule\-config:\fR "dns64 -validator iterator" directive and be compiled into the daemon to be -enabled. These settings go in the \fBserver:\fR section. -.TP -.B dns64\-prefix: \fI<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. -.SS "DNSCrypt Options" -.LP -The -.B dnscrypt: -clause give 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. -.SS "EDNS Client Subnet Module Options" -.LP -The ECS module must be configured in the \fBmodule\-config:\fR "subnetcache -validator iterator" directive and be compiled into the daemon to be -enabled. These settings go in the \fBserver:\fR section. -.LP -If the destination address is whitelisted with Unbound will add the EDNS0 option -to the query containing the relevant part of the client's address. When an -answer contains the ECS option the response and the option are placed in a -specialized cache. If the authority indicated no support, the response is stored -in the regular cache. -.LP -Additionally, when a client includes the option in its queries, Unbound will -forward the option to the authority regardless of the authorities presence in -the whitelist. In this case the lookup in the regular cache is skipped. -.LP -The maximum size of the ECS cache is controlled by 'msg-cache-size' in the -configuration file. On top of that, for each query only 100 different subnets -are allowed to be stored for each address family. Exceeding that number, older -entries will be purged from cache. -.TP -.B send\-client\-subnet: \fI<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. -.TP -.B client\-subnet\-always\-forward: \fI<yes or no>\fR -Specify whether the ECS whitelist check (configured using -\fBsend\-client\-subnet\fR) is applied for all queries, even if the triggering -query contains an ECS record, or only for queries for which the ECS record is -generated using the querier address (and therefore did not contain ECS data in -the client query). If enabled, the whitelist check is skipped when the client -query contains an ECS record. Default is no. -.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. -.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 @UNBOUND_RUN_DIR@ -default unbound working directory. -.TP -.I @UNBOUND_CHROOT_DIR@ -default -\fIchroot\fR(2) -location. -.TP -.I @ub_conf_file@ -unbound configuration file. -.TP -.I @UNBOUND_PIDFILE@ -default unbound pidfile with process ID of the running daemon. -.TP -.I unbound.log -unbound log file. default is to log to -\fIsyslog\fR(3). -.SH "SEE ALSO" -\fIunbound\fR(8), -\fIunbound\-checkconf\fR(8). -.SH "AUTHORS" -.B Unbound -was written by NLnet Labs. Please see CREDITS file -in the distribution for further details. |