mirror of
https://github.com/NLnetLabs/unbound.git
synced 2024-09-21 22:57:08 +00:00
144d35120c
git-svn-id: file:///svn/unbound/trunk@1176 be551aaa-1e26-0410-a405-d3ace91eadb9
708 lines
29 KiB
Groff
708 lines
29 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"
|
|
.LP
|
|
.B unbound.conf
|
|
\- Unbound configuration file.
|
|
.SH "SYNOPSIS"
|
|
.LP
|
|
.B unbound.conf
|
|
.SH "DESCRIPTION"
|
|
.LP
|
|
.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 it can write to pidfile.
|
|
# 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"
|
|
.LP
|
|
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, 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.
|
|
.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.
|
|
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.
|
|
.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 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>
|
|
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.
|
|
.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 IPv6
|
|
(and its socket options) and IPv4 (and have source-interface 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 is 256. Larger numbers need extra
|
|
resources from the operating system.
|
|
.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.
|
|
.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.
|
|
.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, they are dropped. This forces
|
|
the client to resend after a timeout; allowing the server time to work on
|
|
the existing queries. Default 1024.
|
|
.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 infra\-host\-ttl: \fI<seconds>
|
|
Time to live for entries in the host cache. The host cache contains
|
|
roundtrip timing and EDNS support information. Default is 900.
|
|
.TP
|
|
.B infra\-lame\-ttl: \fI<seconds>
|
|
The time to live when a delegation is discovered to be lame. 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\-lame\-size: \fI<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.
|
|
.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.
|
|
.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 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 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.
|
|
.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, 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.
|
|
.IP
|
|
Additionally, unbound may need to access /dev/random (for entropy)
|
|
and to /dev/log (if you use syslog) 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@".
|
|
.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 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 \-QUIT `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 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, 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.
|
|
.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 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.
|
|
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 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.
|
|
.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.
|
|
.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 900.
|
|
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
|
|
protentially bad data in the additional section.
|
|
.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 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 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 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, 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, the query is resolved normally.
|
|
If no local\-zone is given local\-data causes a transparent zone
|
|
to be created by default.
|
|
.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 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.
|
|
.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.
|
|
.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, 255.255.255.255.in\-addr.arpa.
|
|
.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
|
|
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.
|
|
.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.
|
|
.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.
|
|
.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.
|
|
.SS "Forward Zone Options"
|
|
.LP
|
|
There may be multiple
|
|
.B 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).
|
|
.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.
|
|
.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: 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"
|
|
.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.
|