Provided by:
unbound_1.0.0-3_i386 
NAME
unbound.conf - Unbound configuration file.
SYNOPSIS
unbound.conf
DESCRIPTION
unbound.conf is used to configure unbound(8). The file format has
attributes and values. Some attributes have attributes inside them.
The notation is: attribute: value.
Comments start with # and last to the end of line. Empty lines are
ignored as is whitespace at the beginning of a line.
The utility unbound-checkconf(8) can be used to check unbound.conf
prior to usage.
EXAMPLE
An example config file is shown below. Copy this to
/etc/unbound/unbound.conf and start the server with:
$ unbound -c /etc/unbound/unbound.conf
Most settings are the defaults. Stop the server with:
$ kill ‘cat /etc/unbound/unbound.pid‘
Below is a minimal config file. The source distribution contains an
extensive example.conf file with all the options.
# unbound.conf(5) config file for unbound(8).
server:
directory: "/etc/unbound"
username: unbound # make sure it can write to pidfile.
chroot: "/var/lib/unbound"
# logfile: "/etc/unbound/unbound.log" #uncomment to use logfile.
pidfile: "/var/lib/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
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.
Files can be included using the include: directive. It can appear
anywhere, and takes a single filename as an argument. Processing
continues as if the text from the included file was copied into the
config file at that point.
Server Options
These options are part of the server: clause.
verbosity: <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.
Default is level 1. The verbosity can also be increased from the
commandline, see unbound(8).
statistics-interval: <seconds>
The number of seconds between printing statistics to the log for
every thread. Disable with value 0 or "". Default is disabled.
statistics-cumulative: <yes or no>
If enabled, statistics are cumulative since starting unbound,
without clearing the statistics counters after logging the
statistics. Default is no.
num-threads: <number>
The number of threads to create to serve clients. Use 1 for no
threading.
port: <port number>
The port number, default 53, on which the server responds to
queries.
interface: <ip address>
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.
interface-automatic: <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
IPv6 (and its socket options) and IPv4 (and have source-
interface socket options). Default value is no.
outgoing-interface: <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 interface: and
outgoing-interface: lines, the interfaces are then used for both
purposes. Outgoing queries are sent via a random outgoing
interface to counter spoofing.
outgoing-range: <number>
Number of ports to open. This number of file descriptors can be
opened per thread. Must be at least 1. Default is 256. Larger
numbers need extra resources from the operating system.
outgoing-port-permit: <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.
outgoing-port-avoid: <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.
outgoing-num-tcp: <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.
incoming-num-tcp: <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.
msg-buffer-size: <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.
msg-cache-size: <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).
msg-cache-slabs: <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.
num-queries-per-thread: <number>
The number of queries that every thread will service
simultaneously. If more queries arrive that need servicing,
they are dropped. This forces the client to resend after a
timeout; allowing the server time to work on the existing
queries. Default 1024.
rrset-cache-size: <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).
rrset-cache-slabs: <number>
Number of slabs in the RRset cache. Slabs reduce lock contention
by threads. Must be set to a power of 2.
cache-max-ttl: <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.
infra-host-ttl: <seconds>
Time to live for entries in the host cache. The host cache
contains roundtrip timing and EDNS support information. Default
is 900.
infra-lame-ttl: <seconds>
The time to live when a delegation is discovered to be lame.
Default is 900.
infra-cache-slabs: <number>
Number of slabs in the infrastructure cache. Slabs reduce lock
contention by threads. Must be set to a power of 2.
infra-cache-numhosts: <number>
Number of hosts for which information is cached. Default is
10000.
infra-cache-lame-size: <number>
Number of bytes that the lameness cache per host is allowed to
use. Default is 10 kb, which gives maximum storage for a couple
score zones, depending on the lame zone name lengths.
do-ip4: <yes or no>
Enable or disable whether ip4 queries are answered or issued.
Default is yes.
do-ip6: <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.
do-udp: <yes or no>
Enable or disable whether UDP queries are answered or issued.
Default is yes.
do-tcp: <yes or no>
Enable or disable whether TCP queries are answered or issued.
Default is yes.
do-daemonize: <yes or no>
Enable or disable whether the unbound server forks into the
background as a daemon. Default is yes.
access-control: <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 deny,
refuse or allow. Deny stops queries from hosts from that
netblock. Refuse stops queries too, but sends a DNS rcode
REFUSED error message back. Allow gives access to clients from
that netblock. By default only localhost is allowed, the rest
is refused. The default is refused, 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.
chroot: <directory>
If chroot is enabled, you should pass the configfile (from the
commandline) as a full path from the original root. After the
chroot has been performed the now defunct portion of the config
file path is removed to be able to reread the config after a
reload.
All other file paths (working dir, pidfile, logfile, roothints,
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.
Additionally, unbound may need to access /dev/random (for
entropy) and to /dev/log (if you use syslog) from inside the
chroot.
If given a chroot is done to the given directory. The default is
"/var/lib/unbound". If you give "" no chroot is performed.
username: <name>
If given, after binding the port the user privileges are
dropped. Default is "unbound". If you give username: "" no user
change is performed.
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.
directory: <directory>
Sets the working directory for the program.
logfile: <filename>
If "" is given, logging goes to stderr, or nowhere once
daemonized. The logfile is appended to, in the following
format:
[seconds since 1970] unbound[pid:tid]: type: message.
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.
use-syslog: <yes or no>
Sets unbound to send log messages to the syslogd, using
syslog(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.
pidfile: <filename>
The process id is written to the file. Default is
"/var/lib/unbound/unbound.pid". So,
kill -HUP ‘cat /var/lib/unbound/unbound.pid‘
triggers a reload,
kill -QUIT ‘cat /var/lib/unbound/unbound.pid‘
gracefully terminates.
root-hints: <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.
hide-identity: <yes or no>
If enabled id.server and hostname.bind queries are refused.
identity: <string>
Set the identity to report. If set to "", the default, then the
hostname of the server is returned.
hide-version: <yes or no>
If enabled version.server and version.bind queries are refused.
version: <string>
Set the version to report. If set to "", the default, then the
package version is returned.
target-fetch-policy: <"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.
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.
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.
harden-short-bufsize: <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.
harden-large-queries: <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.
harden-glue: <yes or no>
Will trust glue only if it is within the servers authority.
Default is on.
harden-dnssec-stripped: <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.
use-caps-for-id: <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, because some
caching forwarders may not support this. It is known that some
authority servers do not support 0x20, and resolution will fail
for them. A solution is on the TODO list. This feature is an
experimental implementation of draft dns-0x20.
do-not-query-address: <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.
do-not-query-localhost: <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.
module-config: <"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. You must also set trust-anchors
for validation to be useful.
trust-anchor-file: <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.
trust-anchor: <"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.
trusted-keys-file: <filename>
File with trusted keys for validation. Specify more than one
file with several entries, one file per entry. Like
trust-anchor-file but has a different file format. Format is
BIND-9 style format, the trusted-keys { name flag proto algo
"key"; }; clauses are read.
val-override-date: <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.
val-bogus-ttl: <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 900. The time
interval prevents repeated revalidation of bogus data.
val-clean-additional: <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
protentially bad data in the additional section.
val-permissive-mode: <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".
val-nsec3-keysize-iterations: <"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.
key-cache-size: <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).
key-cache-slabs: <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.
local-zone: <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, 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.
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.
deny Do not send an answer, drop the query. If there is a match
from local data, the query is answered.
refuse
Send an error message reply, with rcode REFUSED. If there is
a match from local data, the query is answered.
static
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.
transparent
If there is a match from local data, the query is answered.
Otherwise, the query is resolved normally. If no local-zone
is given local-data causes a transparent zone to be created
by default.
redirect
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 a different address, 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.
nodefault
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.
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.
localhost
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:
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"
reverse IPv4 loopback
Default content:
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."
reverse IPv6 loopback
Default content:
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."
reverse RFC1918 local use zones
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
local-zone: is set static and as local-data: SOA and NS
records are provided.
reverse RFC3330 IP4 this, link-local, testnet and broadcast
Reverse data for zones 0.in-addr.arpa, 254.169.in-addr.arpa,
2.0.192.in-addr.arpa, 255.255.255.255.in-addr.arpa.
reverse RFC4291 IP6 unspecified
Reverse data for zone
0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa.
reverse RFC4193 IPv6 Locally Assigned Local Addresses
Reverse data for zone D.F.ip6.arpa.
reverse RFC4291 IPv6 Link Local Addresses
Reverse data for zones 8.E.F.ip6.arpa to B.E.F.ip6.arpa.
local-data: "<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"’.
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.
Stub Zone Options
There may be multiple 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 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 stub-addr: <ip address of host[@port]>.
The unbound resolver can then access the data, without referring to the
public internet for it.
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.
name: <domain name>
Name of the stub zone.
stub-host: <domain name>
Name of stub zone nameserver. Is itself resolved before it is
used.
stub-addr: <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.
Forward Zone Options
There may be multiple forward-zone: clauses. Each with a name: 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 have to
handle further recursion for the query. 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).
name: <domain name>
Name of the forward zone.
forward-host: <domain name>
Name of server to forward to. Is itself resolved before it is
used.
forward-addr: <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.
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.
# 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: 16 # 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
infra-cache-lame-size: 1k
key-cache-size: 100k
key-cache-slabs: 1
num-queries-per-thread: 30
target-fetch-policy: "2 1 0 0 0 0"
harden-large-queries: "yes"
harden-short-bufsize: "yes"
FILES
/etc/unbound
default unbound working directory.
/var/lib/unbound
default chroot(2) location.
unbound.conf
unbound configuration file.
unbound.pid
default unbound pidfile with process ID of the running daemon.
unbound.log
unbound log file. default is to log to syslog(3).
SEE ALSO
unbound(8), unbound-checkconf(8).
AUTHORS
Unbound was written by NLnet Labs. Please see CREDITS file in the
distribution for further details.