1282 lines
59 KiB
Groff
1282 lines
59 KiB
Groff
.TH "unbound.conf" "5" "@date@" "NLnet Labs" "unbound @version@"
|
|
.\"
|
|
.\" 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. 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>
|
|
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.
|
|
.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
|
|
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.
|
|
.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 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 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\-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 do\-daemonize: \fI<yes or no>
|
|
Enable or disable whether the unbound server forks into the background as
|
|
a daemon. 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 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.
|
|
.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\-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 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 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 draft\-vixie\-dnsext\-resimprove, 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.
|
|
.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. 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 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.
|
|
.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 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 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,
|
|
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. 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'\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, 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'\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 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.
|
|
.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.
|
|
.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.
|
|
.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).
|
|
.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.
|
|
.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.
|