upstream/unbound
1
0
Fork 0
mirror of https://github.com/NLnetLabs/unbound.git synced 2026-02-03 04:09:28 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

- unbound.conf man page updates to include a preview of the section

Browse source 
clauses and some reformatting around the use of "clause", "option"
  and "attributes".
This commit is contained in:
Yorgos Thessalonikefs 2025-10-24 14:23:53 +02:00
parent 713b1783d4
commit 9602973c86
4 changed files with 471 additions and 238 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
doc/Changelog
View file

@ -1,3 +1,8 @@
24 October 2025: Yorgos
- unbound.conf man page updates to include a preview of the section
clauses and some reformatting around the use of "clause", "option"
and "attributes".
22 October 2025: Yorgos
- Tag for 1.24.1 release.
The repository continues with version 1.24.2.

27
doc/example.conf.in
View file

@ -926,6 +926,22 @@ server:
# add a netblock specific override to a localzone, with zone type
# local-zone-override: "example.com" 192.0.2.0/24 refuse
# Action to apply when the IP address in an AAAA or A RR in the answer
# section of a response matches the specified IP netblock.
# Requires use of the respip module.
# response-ip: 192.0.2.0/24 redirect
# Redirect as specified by the "resource record string" when the IP
# address in an AAAA or A RR in the answer section of a response
# matches the specified IP netblock.
# Requires use of the respip module.
# response-ip-data: 192.0.2.0/24 "example. A 192.0.2.1"
# Apply tag(s) when the IP address in an AAAA or A RR in the answer
# section of a response matches the specified IP netblock.
# Requires use of the respip module.
# response-ip-tag: 192.0.2.0/24 "tag1 tag2"
# service clients over TLS (on the TCP sockets) with plain DNS inside
# the TLS stream, and over HTTPS using HTTP/2 as specified in RFC8484.
# Give the certificate to use and private key.
@ -1270,10 +1286,11 @@ remote-control:
# zonefile: "example.org.zone"
# Views
# Create named views. Name must be unique. Map views to requests using
# the access-control-view option. Views can contain zero or more local-zone
# and local-data options. Options from matching views will override global
# options. Global options will be used if no matching view is found.
# Create named views. Name must be unique.
# Map views to requests using the access-control-view/interface-view options.
# Views can contain zero or more local-zone and local-data options.
# Options from matching views will override global options.
# Global options will be used if no matching view is found.
# With view-first yes, it will try to answer using the global local-zone and
# local-data elements if there is no view specific match.
# view:
@ -1281,6 +1298,8 @@ remote-control:
# local-zone: "example.com" redirect
# local-data: "example.com A 192.0.2.3"
# local-data-ptr: "192.0.2.3 www.example.com"
# response-ip: 192.0.2.0/24 redirect
# response-ip-data: 192.0.2.0/24 "example. A 192.0.2.1"
# view-first: no
# view:
# name: "anotherview"

344
doc/unbound.conf.5.in
View file

@ -36,44 +36,49 @@ unbound.conf \- Unbound @version@ configuration file.
.SH DESCRIPTION
.sp
\fBunbound.conf\fP is used to configure \fI\%unbound(8)\fP\&.
The file format has attributes and values.
Some attributes have attributes inside them.
The notation is: \fBattribute: value\fP\&.
.sp
Comments start with \fB#\fP and last to the end of line.
Empty lines are ignored as is whitespace at the beginning of a line.
.sp
The utility \fI\%unbound\-checkconf(8)\fP can be
used to check \fBunbound.conf\fP prior to usage.
.SH FILE FORMAT
.sp
Whitespace is used to separate keywords.
Whitespace indentation is insignificant, but is still recommended for visual
clarity.
Comments start with \fB#\fP and last to the end of line.
Empty lines are ignored, as is whitespace at the beginning of a line.
.sp
Attribute keywords end with a colon (\fB:\fP) and they are either options or
section clauses (group options together).
.sp
The configuration file is logically divided into \fBsections\fP where each section
is introduced by a \fI\%section clause\fP\&.
.SH EXAMPLE
.sp
An example config file is shown below.
Copy this to \fB/etc/unbound/unbound.conf\fP and start the server with:
An example minimal config file is shown below; most settings are the defaults.
Copy this to \fB@ub_conf_file@\fP and start the server with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ unbound \-c /etc/unbound/unbound.conf
$ unbound \-c @ub_conf_file@
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Most settings are the defaults.
Stop the server with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ kill \(gacat /etc/unbound/unbound.pid\(ga
$ kill \(gacat @UNBOUND_PIDFILE@\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Below is a minimal config file.
The source distribution contains an extensive \fBexample.conf\fP file with
all the options.
.INDENT 0.0
@ -83,15 +88,15 @@ all the options.
.ft C
# unbound.conf(5) config file for unbound(8).
server:
directory: \(dq/etc/unbound\(dq
directory: \(dq@UNBOUND_RUN_DIR@\(dq
username: unbound
# make sure unbound can access entropy from inside the chroot.
# e.g. on linux the use these commands (on BSD, devfs(8) is used):
# mount \-\-bind \-n /dev/urandom /etc/unbound/dev/urandom
# and mount \-\-bind \-n /dev/log /etc/unbound/dev/log
chroot: \(dq/etc/unbound\(dq
# logfile: \(dq/etc/unbound/unbound.log\(dq #uncomment to use logfile.
pidfile: \(dq/etc/unbound/unbound.pid\(dq
# mount \-\-bind \-n /dev/urandom @UNBOUND_RUN_DIR@/dev/urandom
# and mount \-\-bind \-n /dev/log @UNBOUND_RUN_DIR@/dev/log
chroot: \(dq@UNBOUND_CHROOT_DIR@\(dq
# logfile: \(dq@UNBOUND_RUN_DIR@/unbound.log\(dq #uncomment to use logfile.
pidfile: \(dq@UNBOUND_PIDFILE@\(dq
# verbosity: 1 # uncomment and increase to get more logging.
# listen on all interfaces, answer queries from the local subnet.
interface: 0.0.0.0
@ -102,14 +107,68 @@ server:
.fi
.UNINDENT
.UNINDENT
.SH FILE FORMAT
.SH SECTION CLAUSES
.sp
There must be whitespace between keywords.
Attribute keywords end with a colon \fB\(aq:\(aq\fP\&.
An attribute is followed by a value, or its containing attributes in which case
it is referred to as a clause.
Clauses can be repeated throughout the file (or included files) to group
attributes under the same clause.
The recognized section clauses are:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fI\%server:\fP
Most of the configuration is found in this section.
.TP
.B \fI\%remote\-control:\fP
Configuration for the facility used by
\fI\%unbound\-control(8)\fP\&.
.TP
.B \fI\%stub\-zone:\fP
Configuration for a zone that redirects to specific authoritative name
servers, e.g. for zones not generally available on the greater
Internet.
.TP
.B \fI\%forward\-zone:\fP
Configuration for a zone that forwards to specific DNS resolvers.
.TP
.B \fI\%auth\-zone:\fP
Configuration for local authoritative zones.
.TP
.B \fI\%view:\fP
Overriding a small subset of configuration for incoming requests.
Requests are mapped to views with
\fI\%access\-control\-view\fP and
\fI\%interface\-view\fP\&.
.TP
.B \fI\%python:\fP
Configuration for the optional \fBpython\fP script module.
.TP
.B \fI\%dynlib:\fP
Configuration for the optional \fBdynlib\fP module that loads dynamic
libraries into Unbound.
.TP
.B \fI\%dnscrypt:\fP
Configuration for the optional DNSCrypt feature.
.TP
.B \fI\%cachedb:\fP
Configuration for the optional \fBcachedb\fP module that can interface
with second level caches, currently Redis or Redis\-complatible
databases.
.TP
.B \fI\%dnstap:\fP
Configuration of the optional dnstap logging feature; a flexible,
structured binary log format for DNS software.
.TP
.B \fI\%rpz:\fP
Configuration for Response Policy Zones that allows for DNS filtering.
Requires the \fBrespip\fP module.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Section clauses can be repeated throughout the file (or included files) to
logically group options in one visually cohesive group.
This may be particularly useful for the \fBserver:\fP clause with its myriad of
options.
.SH INCLUDING FILES
.sp
Files can be included using the \fBinclude:\fP directive.
It can appear anywhere, it accepts a single file name as argument.
@ -124,11 +183,11 @@ Wildcards can be used to include multiple files, see \fIglob(7)\fP\&.
.sp
For a more structural include option, the \fBinclude\-toplevel:\fP directive can
be used.
This closes whatever clause is currently active (if any) and forces the use of
clauses in the included files and right after this directive.
.SS Server Options
This closes whatever section clause is currently active (if any) and forces the
use of section clauses in the included files and right after this directive.
.SH SERVER OPTIONS
.sp
These options are part of the \fBserver:\fP clause.
These options are part of the \fBserver:\fP section.
.INDENT 0.0
.TP
.B verbosity: \fI<number>\fP
@ -539,6 +598,9 @@ Default: 376
The wait time in msec where recursion requests are dropped.
This is to stop a large number of replies from accumulating.
They receive no reply, the work item continues to recurse.
For UDP the replies are dropped, for stream connections the reply
is not dropped if the stream connection is still open ready to receive
answers.
It is nice to be a bit larger than
\fI\%serve\-expired\-client\-timeout\fP
if that is enabled.
@ -554,7 +616,7 @@ The number of replies that can wait for recursion, for an IP address.
This makes a ratelimit per IP address of waiting replies for recursion.
It stops very large amounts of queries waiting to be returned to one
destination.
The value \fB0\fP disables wait limits.
The value \fB0\fP disables all wait limits.
.sp
Default: 1000
.UNINDENT
@ -563,7 +625,11 @@ Default: 1000
.B wait\-limit\-cookie: \fI<number>\fP
The number of replies that can wait for recursion, for an IP address
that sent the query with a valid DNS Cookie.
Since the cookie validates the client address, this limit can be higher.
Since the cookie already validates the client address, this option allows
to override a configured
\fI\%wait\-limit\fP value usually with a higher one
for cookie validated queries.
The value \fB0\fP disables wait limits for cookie validated queries.
.sp
Default: 10000
.UNINDENT
@ -1153,8 +1219,8 @@ Default: no
.INDENT 0.0
.TP
.B tls\-system\-cert: \fI<yes or no>\fP
This the same attribute as the
\fI\%tls\-win\-cert\fP attribute, under a
This the same as the
\fI\%tls\-win\-cert\fP option, under a
different name.
Because it is not windows specific.
.UNINDENT
@ -1607,8 +1673,8 @@ implicit default \(dqaccess\-control: 127.0.0.0/8 allow\(dq option.
.INDENT 3.5
The interface needs to be already specified with
\fI\%interface\fP and that any
\fBaccess\-control*:\fP attribute overrides all \fBinterface\-*:\fP
attributes for targeted clients.
\fBaccess\-control*:\fP option overrides all \fBinterface\-*:\fP
options for targeted clients.
.UNINDENT
.UNINDENT
.UNINDENT
@ -1623,8 +1689,8 @@ for interfaces.
.INDENT 3.5
The interface needs to be already specified with
\fI\%interface\fP and that any
\fBaccess\-control*:\fP attribute overrides all \fBinterface\-*:\fP
attributes for targeted clients.
\fBaccess\-control*:\fP option overrides all \fBinterface\-*:\fP
options for targeted clients.
.UNINDENT
.UNINDENT
.UNINDENT
@ -1640,8 +1706,8 @@ but for interfaces.
.INDENT 3.5
The interface needs to be already specified with
\fI\%interface\fP and that any
\fBaccess\-control*:\fP attribute overrides all \fBinterface\-*:\fP
attributes for targeted clients.
\fBaccess\-control*:\fP option overrides all \fBinterface\-*:\fP
options for targeted clients.
.UNINDENT
.UNINDENT
.UNINDENT
@ -1657,8 +1723,8 @@ for interfaces.
.INDENT 3.5
The interface needs to be already specified with
\fI\%interface\fP and that any
\fBaccess\-control*:\fP attribute overrides all \fBinterface\-*:\fP
attributes for targeted clients.
\fBaccess\-control*:\fP option overrides all \fBinterface\-*:\fP
options for targeted clients.
.UNINDENT
.UNINDENT
.UNINDENT
@ -1673,8 +1739,8 @@ but for interfaces.
.INDENT 3.5
The interface needs to be already specified with
\fI\%interface\fP and that any
\fBaccess\-control*:\fP attribute overrides all \fBinterface\-*:\fP
attributes for targeted clients.
\fBaccess\-control*:\fP option overrides all \fBinterface\-*:\fP
options for targeted clients.
.UNINDENT
.UNINDENT
.UNINDENT
@ -1751,7 +1817,7 @@ The logfile is appended to, in the following format:
.UNINDENT
.sp
If this option is given, the \fI\%use\-syslog\fP
attribute is internally set to \fBno\fP\&.
option is internally set to \fBno\fP\&.
.sp
The logfile is reopened (for append) when the config file is reread, on
SIGHUP.
@ -1899,8 +1965,8 @@ 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.
The default may become outdated, when servers change, and then it is
possible to use a root hints file with specific servers.
.sp
Default: \(dq\(dq
.UNINDENT
@ -3368,7 +3434,7 @@ This specifies the action data for
\fI\%response\-ip\fP with action being to redirect
as specified by \fI<\(dqresource record string\(dq>\fP\&.
\fI<\(dqResource record string\(dq>\fP is similar to that of
\fI\%access\-control\-tag\-action\fP,
\fI\%access\-control\-tag\-data\fP,
but it must be of either AAAA, A or CNAME types.
If the \fI<IP\-netblock>\fP is an IPv6/IPv4 prefix, the record must be AAAA/A
respectively, unless it is a CNAME (which can be used for both versions of
@ -3838,17 +3904,18 @@ enabled to increase privacy on the outgoing reports.
.sp
Default: no
.UNINDENT
.SS Remote Control Options
.SH REMOTE CONTROL OPTIONS
.sp
These options are part of the \fBremote\-control:\fP section and are the
declarations for the remote control facility.
.sp
In the \fBremote\-control:\fP clause are the declarations for the remote control
facility.
If this is enabled, the \fI\%unbound\-control(8)\fP
utility can be used to send commands to the running Unbound server.
The server uses these clauses to setup TLSv1 security for the connection.
The \fI\%unbound\-control(8)\fP utility also reads the
\fBremote\-control:\fP section for options.
The server uses these options to setup TLS security for the connection.
The \fI\%unbound\-control(8)\fP utility also reads
this \fBremote\-control:\fP section for options.
To setup the correct self\-signed certificates use the
\fIunbound\-control\-setup(8)\fP utility.
\fBunbound\-control\-setup(8)\fP utility.
.INDENT 0.0
.TP
.B control\-enable: \fI<yes or no>\fP
@ -3948,9 +4015,11 @@ This file is used by \fI\%unbound\-control(8)\fP\&.
.sp
Default: unbound_control.pem
.UNINDENT
.SS Stub Zone Options
.SH STUB ZONE OPTIONS
.sp
There may be multiple \fBstub\-zone:\fP clauses.
These options are part of the \fBstub\-zone:\fP section.
.sp
There may be multiple \fBstub\-zone:\fP sections.
Each with a \fI\%name\fP and zero or more hostnames or
IP addresses.
For the stub zone this list of nameservers is used.
@ -3989,9 +4058,10 @@ Consider adding \fI\%server\fP statements for
\fI\%domain\-insecure\fP and for
\fI\%local\-zone: <name> nodefault\fP
for the zone if it is a locally served zone.
The insecure clause stops DNSSEC from invalidating the zone.
The \fI\%domain\-insecure\fP option stops DNSSEC
from invalidating the zone.
The \fI\%local\-zone: nodefault\fP (or
\fI\%transparent\fP) clause makes the
\fI\%transparent\fP) option makes the
(reverse\-) zone bypass Unbound\(aqs filtering of \fI\%RFC 1918\fP zones.
.INDENT 0.0
.TP
@ -4045,9 +4115,9 @@ Default: no
.INDENT 0.0
.TP
.B stub\-first: \fI<yes or no>\fP
If enabled, a query is attempted without the stub clause if it fails.
If enabled, a query is attempted without this stub section 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.
servers are unreachable, instead it is tried without this stub section.
.sp
Default: no
.UNINDENT
@ -4080,9 +4150,11 @@ This is useful when you want immediate changes to be visible.
.sp
Default: no
.UNINDENT
.SS Forward Zone Options
.SH FORWARD ZONE OPTIONS
.sp
There may be multiple \fBforward\-zone:\fP clauses.
These options are part of the \fBforward\-zone:\fP section.
.sp
There may be multiple \fBforward\-zone:\fP sections.
Each with a \fI\%name\fP and zero or more hostnames
or IP addresses.
For the forward zone this list of nameservers is used to forward the queries
@ -4189,12 +4261,14 @@ This is useful when you want immediate changes to be visible.
.sp
Default: no
.UNINDENT
.SS Authority Zone Options
.SH AUTHORITY ZONE OPTIONS
.sp
These options are part of the \fBauth\-zone:\fP section.
.sp
Authority zones are configured with \fBauth\-zone:\fP, and each one must have a
\fI\%name\fP\&.
There can be multiple ones, by listing multiple auth\-zone clauses, each with a
different name, pertaining to that part of the namespace.
There can be multiple ones, by listing multiple \fBauth\-zone\fP section clauses,
each with a different name, pertaining to that part of the namespace.
The authority zone with the name closest to the name looked up is used.
Authority zones can be processed on two distinct, non\-exclusive, configurable
stages.
@ -4225,7 +4299,7 @@ consult the local zone data while resolving.
In this case, the aforementioned CNAME example will result in a thoroughly
resolved answer.
.sp
Authority zones can be read from zonefile.
Authority zones can be read from a zonefile.
And can be kept updated via AXFR and IXFR.
After update the zonefile is rewritten.
The update mechanism uses the SOA timer values and performs SOA UDP queries to
@ -4410,18 +4484,20 @@ If not given then no zonefile is used.
If the file does not exist or is empty, Unbound will attempt to fetch zone
data (eg. from the primary servers).
.UNINDENT
.SS View Options
.SH VIEW OPTIONS
.sp
There may be multiple \fBview:\fP clauses.
These options are part of the \fBview:\fP section.
.sp
There may be multiple \fBview:\fP sections.
Each with a \fI\%name\fP and zero or more
\fI\%local\-zone\fP and
\fI\%local\-data\fP attributes.
\fI\%local\-data\fP options.
Views can also contain \fI\%view\-first\fP,
\fI\%response\-ip\fP,
\fI\%response\-ip\-data\fP and
\fI\%local\-data\-ptr\fP attributes.
\fI\%local\-data\-ptr\fP options.
View can be mapped to requests by specifying the view name in an
\fI\%access\-control\-view\fP attribute.
\fI\%access\-control\-view\fP option.
Options from matching views will override global options.
Global options will be used if no matching view is found, or when the matching
view does not have the option specified.
@ -4431,7 +4507,7 @@ view does not have the option specified.
Name of the view.
Must be unique.
This name is used in the
\fI\%access\-control\-view\fP attribute.
\fI\%access\-control\-view\fP option.
.UNINDENT
.INDENT 0.0
.TP
@ -4464,6 +4540,22 @@ Has the same behaviour as the global
.UNINDENT
.INDENT 0.0
.TP
.B response\-ip: \fI<IP\-netblock> <action>\fP
This requires use of the \fBrespip\fP module.
.sp
Similar to \fI\%response\-ip\fP but
only applies to this view.
.UNINDENT
.INDENT 0.0
.TP
.B response\-ip\-data: \fI<IP\-netblock> <\(dqresource record string\(dq>\fP
This requires use of the \fBrespip\fP module.
.sp
Similar to \fI\%response\-ip\-data\fP but
only applies to this view.
.UNINDENT
.INDENT 0.0
.TP
.B view\-first: \fI<yes or no>\fP
If enabled, it attempts to use the global
\fI\%local\-zone\fP and
@ -4472,9 +4564,11 @@ view specific options.
.sp
Default: no
.UNINDENT
.SS Python Module Options
.SH PYTHON MODULE OPTIONS
.sp
The \fBpython:\fP clause gives the settings for the \fIpython(1)\fP script module.
These options are part of the \fBpython:\fP section.
.sp
The \fBpython:\fP section gives the settings for the \fIpython(1)\fP 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
@ -4497,14 +4591,16 @@ The script file to load.
Repeat this option for every python module instance added to the
\fI\%module\-config\fP option.
.UNINDENT
.SS Dynamic Library Module Options
.SH DYNAMIC LIBRARY MODULE OPTIONS
.sp
The \fBdynlib:\fP clause gives the settings for the \fBdynlib\fP module.
These options are part of the \fBdynlib:\fP section.
.sp
The \fBdynlib:\fP section gives the settings for the \fBdynlib\fP module.
This module is only a very small wrapper that allows dynamic modules to be
loaded on runtime instead of being compiled into the application.
To enable the dynlib module it has to be compiled into the daemon, and the word
\fBdynlib\fP has to be put in the
\fI\%module\-config\fP attribute.
\fI\%module\-config\fP option.
Multiple instances of dynamic libraries are supported by adding the word
\fBdynlib\fP more than once.
.sp
@ -4519,7 +4615,9 @@ The dynamic library file to load.
Repeat this option for every dynlib module instance added to the
\fI\%module\-config\fP option.
.UNINDENT
.SS DNS64 Module Options
.SH DNS64 MODULE OPTIONS
.sp
These options are part of the \fBserver:\fP section.
.sp
The \fBdns64\fP module must be configured in the
\fI\%module\-config\fP directive, e.g.:
@ -4539,7 +4637,11 @@ and be compiled into the daemon to be enabled.
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
These settings go in the \fI\%server:\fP section.
If combining the \fBrespip\fP and \fBdns64\fP modules, the \fBrespip\fP module
needs to appear before the \fBdns64\fP module in the
\fI\%module\-config\fP
configuration option so that response IP and/or RPZ feeds can properly
filter responses regardless of DNS64 synthesis.
.UNINDENT
.UNINDENT
.INDENT 0.0
@ -4575,12 +4677,12 @@ Can be entered multiple times, list a new domain for which it applies, one
per line.
Applies also to names underneath the name given.
.UNINDENT
.SS NAT64 Operation
.SH NAT64 OPTIONS
.sp
These options are part of the \fBserver:\fP section.
.sp
NAT64 operation allows using a NAT64 prefix for outbound requests to IPv4\-only
servers.
It is controlled by two options in the
\fI\%server:\fP section:
.INDENT 0.0
.TP
.B do\-nat64: \fI<yes or no>\fP
@ -4598,9 +4700,11 @@ The prefix length must be one of /32, /40, /48, /56, /64 or /96.
.sp
Default: 64:ff9b::/96 (same as \fI\%dns64\-prefix\fP)
.UNINDENT
.SS DNSCrypt Options
.SH DNSCRYPT OPTIONS
.sp
The \fBdnscrypt:\fP clause gives the settings of the dnscrypt channel.
These options are part of the \fBdnscrypt:\fP section.
.sp
The \fBdnscrypt:\fP section gives the settings of the dnscrypt channel.
While those options are available, they are only meaningful if Unbound was
compiled with \fB\-\-enable\-dnscrypt\fP\&.
Currently certificate and secret/public keys cannot be generated by Unbound.
@ -4730,7 +4834,9 @@ If left unconfigured, it will be configured automatically to be a power of
.sp
Default: (unconfigured)
.UNINDENT
.SS EDNS Client Subnet Module Options
.SH EDNS CLIENT SUBNET MODULE OPTIONS
.sp
These options are part of the \fBserver:\fP section.
.sp
The ECS module must be configured in the
\fI\%module\-config\fP directive, e.g.:
@ -4747,13 +4853,6 @@ module\-config: \(dqsubnetcache validator iterator\(dq
.sp
and be compiled into the daemon to be enabled.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
These settings go in the \fI\%server:\fP section.
.UNINDENT
.UNINDENT
.sp
If the destination address is allowed in the configuration Unbound will add the
EDNS0 option to the query containing the relevant part of the client\(aqs address.
When an answer contains the ECS option the response and the option are placed
@ -4875,7 +4974,9 @@ This number applies for each qname/qclass/qtype tuple.
.sp
Default: 100
.UNINDENT
.SS Opportunistic IPsec Support Module Options
.SH OPPORTUNISTIC IPSEC SUPPORT MODULE OPTIONS
.sp
These options are part of the \fBserver:\fP section.
.sp
The IPsec module must be configured in the
\fI\%module\-config\fP directive, e.g.:
@ -4892,13 +4993,6 @@ module\-config: \(dqipsecmod validator iterator\(dq
.sp
and be compiled into Unbound by using \fB\-\-enable\-ipsecmod\fP to be enabled.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
These settings go in the \fI\%server:\fP section.
.UNINDENT
.UNINDENT
.sp
When Unbound receives an A/AAAA query that is not in the cache and finds a
valid answer, it will withhold returning the answer and instead will generate
an IPSECKEY subquery for the same domain name.
@ -4996,7 +5090,9 @@ If the option is not specified, all domains are treated as being allowed
.B ipsecmod\-whitelist: \fI<domain>\fP
Alternate syntax for \fI\%ipsecmod\-allow\fP\&.
.UNINDENT
.SS Cache DB Module Options
.SH CACHE DB MODULE OPTIONS
.sp
These options are part of the \fBcachedb:\fP section.
.sp
The Cache DB module must be configured in the
\fI\%module\-config\fP directive, e.g.:
@ -5058,7 +5154,7 @@ If connection close or timeout happens too often, Unbound will be effectively
unusable with this backend.
It\(aqs the administrator\(aqs responsibility to make the assumption hold.
.sp
The \fBcachedb:\fP clause gives custom settings of the cache DB module.
The \fBcachedb:\fP section gives custom settings of the cache DB module.
.INDENT 0.0
.TP
.B backend: \fI<backend name>\fP
@ -5286,10 +5382,13 @@ for the Redis replica server.
.sp
Default: 0
.UNINDENT
.SS DNSTAP Logging Options
.SH DNSTAP OPTIONS
.sp
DNSTAP support, when compiled in by using \fB\-\-enable\-dnstap\fP, is enabled in
the \fBdnstap:\fP section.
These options are part of the \fBdnstap:\fP section.
.sp
DNSTAP is a flexible, structured binary log format for DNS software.
When compiled in by using \fB\-\-enable\-dnstap\fP, it can be enabled in the
\fBdnstap:\fP section.
This starts an extra thread (when compiled with threading) that writes the log
information to the destination.
If Unbound is compiled without threading it does not spawn a thread, but
@ -5455,15 +5554,18 @@ Enable to log forwarder response messages.
.sp
Default: no
.UNINDENT
.SS Response Policy Zone Options
.SH RESPONSE POLICY ZONE OPTIONS
.sp
Response Policy Zones are configured with \fBrpz:\fP, and each one must have a
\fI\%name\fP attribute.
There can be multiple ones, by listing multiple RPZ clauses, each with a
different name.
RPZ clauses are applied in order of configuration and any match from an earlier
RPZ zone will terminate the RPZ lookup.
These options are part of the \fBrpz:\fP section.
.sp
Response Policy Zones are configured with \fBrpz:\fP section clauses, and each
one must have a \fI\%name\fP option.
There can be multiple ones, by listing multiple \fBrpz:\fP section clauses, each
with a different name.
RPZ sections are applied in order of configuration and any match from an
earlier RPZ zone will terminate the RPZ lookup.
Note that a PASSTHRU action is still considered a match.
.sp
The respip module needs to be added to the
\fI\%module\-config\fP, e.g.:
.INDENT 0.0
@ -5477,6 +5579,17 @@ module\-config: \(dqrespip validator iterator\(dq
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If combining the \fBrespip\fP and \fBdns64\fP modules, the \fBrespip\fP module
needs to appear before the \fBdns64\fP module in the
\fI\%module\-config\fP
configuration option so that response IP and/or RPZ feeds can properly
filter responses regardless of DNS64 synthesis.
.UNINDENT
.UNINDENT
.sp
QNAME, Response IP Address, nsdname, nsip and clientip triggers are supported.
Supported actions are: NXDOMAIN, NODATA, PASSTHRU, DROP, Local Data, tcp\-only
and drop.
@ -5545,9 +5658,6 @@ A 192.0.2.1 answer with this IP address
.sp
Other records like AAAA, TXT and other CNAMEs (not rpz\-..) can also be used to
answer queries with that content.
.sp
The RPZ zones can be configured in the config file with these settings in the
\fBrpz:\fP block.
.INDENT 0.0
.TP
.B name: \fI<zone name>\fP
@ -5686,7 +5796,7 @@ Default: no
.INDENT 0.0
.TP
.B tags: \fI\(dq<list of tags>\(dq\fP
Limit the policies from this RPZ clause to clients with a matching tag.
Limit the policies from this RPZ section to clients with a matching tag.
.sp
Tags need to be defined in \fI\%define\-tag\fP and
can be assigned to client addresses using
@ -5694,7 +5804,7 @@ can be assigned to client addresses using
\fI\%interface\-tag\fP\&.
Enclose list of tags in quotes (\fB\(dq\(dq\fP) and put spaces between tags.
.sp
If no tags are specified the policies from this clause will be applied for
If no tags are specified the policies from this section will be applied for
all clients.
.UNINDENT
.SH MEMORY CONTROL EXAMPLE

333
doc/unbound.conf.rst
View file

@ -46,34 +46,41 @@ Description
-----------
**unbound.conf** is used to configure :doc:`unbound(8)</manpages/unbound>`.
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 :doc:`unbound-checkconf(8)</manpages/unbound-checkconf>` can be
used to check ``unbound.conf`` prior to usage.
File Format
-----------
Whitespace is used to separate keywords.
Whitespace indentation is insignificant, but is still recommended for visual
clarity.
Comments start with ``#`` and last to the end of line.
Empty lines are ignored, as is whitespace at the beginning of a line.
Attribute keywords end with a colon (``:``) and they are either options or
section clauses (group options together).
The configuration file is logically divided into **sections** where each section
is introduced by a :ref:`section clause<unbound.conf.clauses>`.
Example
-------
An example config file is shown below.
Copy this to :file:`/etc/unbound/unbound.conf` and start the server with:
An example minimal config file is shown below; most settings are the defaults.
Copy this to ``@ub_conf_file@`` and start the server with:
.. code-block:: text
$ unbound -c /etc/unbound/unbound.conf
$ unbound -c @ub_conf_file@
Most settings are the defaults.
Stop the server with:
.. code-block:: text
$ kill `cat /etc/unbound/unbound.pid`
$ kill `cat @UNBOUND_PIDFILE@`
Below is a minimal config file.
The source distribution contains an extensive :file:`example.conf` file with
all the options.
@ -81,15 +88,15 @@ all the options.
# unbound.conf(5) config file for unbound(8).
server:
directory: "/etc/unbound"
directory: "@UNBOUND_RUN_DIR@"
username: unbound
# make sure unbound can access entropy from inside the chroot.
# e.g. on linux the use these commands (on BSD, devfs(8) is used):
# mount --bind -n /dev/urandom /etc/unbound/dev/urandom
# and mount --bind -n /dev/log /etc/unbound/dev/log
chroot: "/etc/unbound"
# logfile: "/etc/unbound/unbound.log" #uncomment to use logfile.
pidfile: "/etc/unbound/unbound.pid"
# mount --bind -n /dev/urandom @UNBOUND_RUN_DIR@/dev/urandom
# and mount --bind -n /dev/log @UNBOUND_RUN_DIR@/dev/log
chroot: "@UNBOUND_CHROOT_DIR@"
# logfile: "@UNBOUND_RUN_DIR@/unbound.log" #uncomment to use logfile.
pidfile: "@UNBOUND_PIDFILE@"
# verbosity: 1 # uncomment and increase to get more logging.
# listen on all interfaces, answer queries from the local subnet.
interface: 0.0.0.0
@ -97,19 +104,71 @@ all the options.
access-control: 10.0.0.0/8 allow
access-control: 2001:DB8::/64 allow
File Format
-----------
.. _unbound.conf.clauses:
There must be whitespace between keywords.
Attribute keywords end with a colon ``':'``.
An attribute is followed by a value, or its containing attributes in which case
it is referred to as a clause.
Clauses can be repeated throughout the file (or included files) to group
attributes under the same clause.
Section Clauses
---------------
The recognized section clauses are:
:ref:`server:<unbound.conf.server>`
Most of the configuration is found in this section.
:ref:`remote-control:<unbound.conf.remote>`
Configuration for the facility used by
:doc:`unbound-control(8)</manpages/unbound-control>`.
:ref:`stub-zone:<unbound.conf.stub>`
Configuration for a zone that redirects to specific authoritative name
servers, e.g. for zones not generally available on the greater
Internet.
:ref:`forward-zone:<unbound.conf.forward>`
Configuration for a zone that forwards to specific DNS resolvers.
:ref:`auth-zone:<unbound.conf.auth>`
Configuration for local authoritative zones.
:ref:`view:<unbound.conf.view>`
Overriding a small subset of configuration for incoming requests.
Requests are mapped to views with
:ref:`access-control-view<unbound.conf.access-control-view>` and
:ref:`interface-view<unbound.conf.interface-view>`.
:ref:`python:<unbound.conf.python>`
Configuration for the optional ``python`` script module.
:ref:`dynlib:<unbound.conf.dynlib>`
Configuration for the optional ``dynlib`` module that loads dynamic
libraries into Unbound.
:ref:`dnscrypt:<unbound.conf.dnscrypt>`
Configuration for the optional DNSCrypt feature.
:ref:`cachedb:<unbound.conf.cachedb>`
Configuration for the optional ``cachedb`` module that can interface
with second level caches, currently Redis or Redis-complatible
databases.
:ref:`dnstap:<unbound.conf.dnstap>`
Configuration of the optional dnstap logging feature; a flexible,
structured binary log format for DNS software.
:ref:`rpz:<unbound.conf.rpz>`
Configuration for Response Policy Zones that allows for DNS filtering.
Requires the ``respip`` module.
Section clauses can be repeated throughout the file (or included files) to
logically group options in one visually cohesive group.
This may be particularly useful for the ``server:`` clause with its myriad of
options.
.. _unbound.conf.include:
Files can be included using the **include:** directive.
Including Files
---------------
Files can be included using the ``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.
@ -122,17 +181,17 @@ Wildcards can be used to include multiple files, see *glob(7)*.
.. _unbound.conf.include-toplevel:
For a more structural include option, the **include-toplevel:** directive can
For a more structural include option, the ``include-toplevel:`` directive can
be used.
This closes whatever clause is currently active (if any) and forces the use of
clauses in the included files and right after this directive.
This closes whatever section clause is currently active (if any) and forces the
use of section clauses in the included files and right after this directive.
.. _unbound.conf.server:
Server Options
^^^^^^^^^^^^^^
--------------
These options are part of the **server:** clause.
These options are part of the ``server:`` section.
@@UAHL@unbound.conf@verbosity@@: *<number>*
@ -1056,8 +1115,8 @@ These options are part of the **server:** clause.
@@UAHL@unbound.conf@tls-system-cert@@: *<yes or no>*
This the same attribute as the
:ref:`tls-win-cert<unbound.conf.tls-win-cert>` attribute, under a
This the same as the
:ref:`tls-win-cert<unbound.conf.tls-win-cert>` option, under a
different name.
Because it is not windows specific.
@ -1444,8 +1503,8 @@ These options are part of the **server:** clause.
.. note::
The interface needs to be already specified with
:ref:`interface<unbound.conf.interface>` and that any
**access-control\*:** attribute overrides all **interface-\*:**
attributes for targeted clients.
**access-control\*:** option overrides all **interface-\*:**
options for targeted clients.
@@UAHL@unbound.conf@interface-tag@@: *<ip address or interface name [@port]> <"list of tags">*
@ -1455,8 +1514,8 @@ These options are part of the **server:** clause.
.. note::
The interface needs to be already specified with
:ref:`interface<unbound.conf.interface>` and that any
**access-control\*:** attribute overrides all **interface-\*:**
attributes for targeted clients.
**access-control\*:** option overrides all **interface-\*:**
options for targeted clients.
@@UAHL@unbound.conf@interface-tag-action@@: *<ip address or interface name [@port]> <tag> <action>*
@ -1467,8 +1526,8 @@ These options are part of the **server:** clause.
.. note::
The interface needs to be already specified with
:ref:`interface<unbound.conf.interface>` and that any
**access-control\*:** attribute overrides all **interface-\*:**
attributes for targeted clients.
**access-control\*:** option overrides all **interface-\*:**
options for targeted clients.
@@UAHL@unbound.conf@interface-tag-data@@: *<ip address or interface name [@port]> <tag> <"resource record string">*
@ -1479,8 +1538,8 @@ These options are part of the **server:** clause.
.. note::
The interface needs to be already specified with
:ref:`interface<unbound.conf.interface>` and that any
**access-control\*:** attribute overrides all **interface-\*:**
attributes for targeted clients.
**access-control\*:** option overrides all **interface-\*:**
options for targeted clients.
@@UAHL@unbound.conf@interface-view@@: *<ip address or interface name [@port]> <view name>*
@ -1490,8 +1549,8 @@ These options are part of the **server:** clause.
.. note::
The interface needs to be already specified with
:ref:`interface<unbound.conf.interface>` and that any
**access-control\*:** attribute overrides all **interface-\*:**
attributes for targeted clients.
**access-control\*:** option overrides all **interface-\*:**
options for targeted clients.
@@UAHL@unbound.conf@chroot@@: *<directory>*
@ -1556,7 +1615,7 @@ These options are part of the **server:** clause.
[seconds since 1970] unbound[pid:tid]: type: message.
If this option is given, the :ref:`use-syslog<unbound.conf.use-syslog>`
attribute is internally set to ``no``.
option is internally set to ``no``.
The logfile is reopened (for append) when the config file is reread, on
SIGHUP.
@ -2890,7 +2949,7 @@ These options are part of the **server:** clause.
:ref:`response-ip<unbound.conf.response-ip>` with action being to redirect
as specified by *<"resource record string">*.
*<"Resource record string">* is similar to that of
:ref:`access-control-tag-action<unbound.conf.access-control-tag-action>`,
:ref:`access-control-tag-data<unbound.conf.access-control-tag-data>`,
but it must be of either AAAA, A or CNAME types.
If the *<IP-netblock>* is an IPv6/IPv4 prefix, the record must be AAAA/A
respectively, unless it is a CNAME (which can be used for both versions of
@ -3319,17 +3378,18 @@ These options are part of the **server:** clause.
.. _unbound.conf.remote:
Remote Control Options
^^^^^^^^^^^^^^^^^^^^^^
----------------------
These options are part of the ``remote-control:`` section and are the
declarations for the remote control facility.
In the **remote-control:** clause are the declarations for the remote control
facility.
If this is enabled, the :doc:`unbound-control(8)</manpages/unbound-control>`
utility can be used to send commands to the running Unbound server.
The server uses these clauses to setup TLSv1 security for the connection.
The :doc:`unbound-control(8)</manpages/unbound-control>` utility also reads the
**remote-control:** section for options.
The server uses these options to setup TLS security for the connection.
The :doc:`unbound-control(8)</manpages/unbound-control>` utility also reads
this ``remote-control:`` section for options.
To setup the correct self-signed certificates use the
*unbound-control-setup(8)* utility.
``unbound-control-setup(8)`` utility.
@@UAHL@unbound.conf.remote@control-enable@@: *<yes or no>*
@ -3421,9 +3481,11 @@ To setup the correct self-signed certificates use the
.. _unbound.conf.stub:
Stub Zone Options
^^^^^^^^^^^^^^^^^
-----------------
There may be multiple **stub-zone:** clauses.
These options are part of the ``stub-zone:`` section.
There may be multiple ``stub-zone:`` sections.
Each with a :ref:`name<unbound.conf.stub.name>` and zero or more hostnames or
IP addresses.
For the stub zone this list of nameservers is used.
@ -3456,9 +3518,10 @@ Consider adding :ref:`server<unbound.conf.server>` statements for
:ref:`domain-insecure<unbound.conf.domain-insecure>` and for
:ref:`local-zone: \<name\> nodefault<unbound.conf.local-zone.type.nodefault>`
for the zone if it is a locally served zone.
The insecure clause stops DNSSEC from invalidating the zone.
The :ref:`domain-insecure<unbound.conf.domain-insecure>` option stops DNSSEC
from invalidating the zone.
The :ref:`local-zone: nodefault<unbound.conf.local-zone.type.nodefault>` (or
:ref:`transparent<unbound.conf.local-zone.type.transparent>`) clause makes the
:ref:`transparent<unbound.conf.local-zone.type.transparent>`) option makes the
(reverse-) zone bypass Unbound's filtering of :rfc:`1918` zones.
@ -3508,9 +3571,9 @@ The :ref:`local-zone: nodefault<unbound.conf.local-zone.type.nodefault>` (or
@@UAHL@unbound.conf.stub@stub-first@@: *<yes or no>*
If enabled, a query is attempted without the stub clause if it fails.
If enabled, a query is attempted without this stub section 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.
servers are unreachable, instead it is tried without this stub section.
Default: no
@ -3542,9 +3605,11 @@ The :ref:`local-zone: nodefault<unbound.conf.local-zone.type.nodefault>` (or
.. _unbound.conf.forward:
Forward Zone Options
^^^^^^^^^^^^^^^^^^^^
--------------------
There may be multiple **forward-zone:** clauses.
These options are part of the ``forward-zone:`` section.
There may be multiple ``forward-zone:`` sections.
Each with a :ref:`name<unbound.conf.forward.name>` and zero or more hostnames
or IP addresses.
For the forward zone this list of nameservers is used to forward the queries
@ -3647,12 +3712,14 @@ cache).
.. _unbound.conf.auth:
Authority Zone Options
^^^^^^^^^^^^^^^^^^^^^^
----------------------
Authority zones are configured with **auth-zone:**, and each one must have a
These options are part of the ``auth-zone:`` section.
Authority zones are configured with ``auth-zone:``, and each one must have a
:ref:`name<unbound.conf.auth.name>`.
There can be multiple ones, by listing multiple auth-zone clauses, each with a
different name, pertaining to that part of the namespace.
There can be multiple ones, by listing multiple ``auth-zone`` section clauses,
each with a different name, pertaining to that part of the namespace.
The authority zone with the name closest to the name looked up is used.
Authority zones can be processed on two distinct, non-exclusive, configurable
stages.
@ -3683,7 +3750,7 @@ consult the local zone data while resolving.
In this case, the aforementioned CNAME example will result in a thoroughly
resolved answer.
Authority zones can be read from zonefile.
Authority zones can be read from a zonefile.
And can be kept updated via AXFR and IXFR.
After update the zonefile is rewritten.
The update mechanism uses the SOA timer values and performs SOA UDP queries to
@ -3852,18 +3919,20 @@ fallback activates to fetch from the upstream instead of the SERVFAIL.
.. _unbound.conf.view:
View Options
^^^^^^^^^^^^
------------
There may be multiple **view:** clauses.
These options are part of the ``view:`` section.
There may be multiple ``view:`` sections.
Each with a :ref:`name<unbound.conf.view.name>` and zero or more
:ref:`local-zone<unbound.conf.view.local-zone>` and
:ref:`local-data<unbound.conf.view.local-data>` attributes.
:ref:`local-data<unbound.conf.view.local-data>` options.
Views can also contain :ref:`view-first<unbound.conf.view.view-first>`,
:ref:`response-ip<unbound.conf.response-ip>`,
:ref:`response-ip-data<unbound.conf.response-ip-data>` and
:ref:`local-data-ptr<unbound.conf.view.local-data-ptr>` attributes.
:ref:`local-data-ptr<unbound.conf.view.local-data-ptr>` options.
View can be mapped to requests by specifying the view name in an
:ref:`access-control-view<unbound.conf.access-control-view>` attribute.
:ref:`access-control-view<unbound.conf.access-control-view>` option.
Options from matching views will override global options.
Global options will be used if no matching view is found, or when the matching
view does not have the option specified.
@ -3873,7 +3942,7 @@ view does not have the option specified.
Name of the view.
Must be unique.
This name is used in the
:ref:`access-control-view<unbound.conf.access-control-view>` attribute.
:ref:`access-control-view<unbound.conf.access-control-view>` option.
@@UAHL@unbound.conf.view@local-zone@@: *<zone> <type>*
@ -3902,6 +3971,20 @@ view does not have the option specified.
:ref:`local-data-ptr<unbound.conf.local-data-ptr>` elements.
@@UAHL@unbound.conf.view@response-ip@@: *<IP-netblock> <action>*
This requires use of the ``respip`` module.
Similar to :ref:`response-ip<unbound.conf.response-ip>` but
only applies to this view.
@@UAHL@unbound.conf.view@response-ip-data@@: *<IP-netblock> <"resource record string">*
This requires use of the ``respip`` module.
Similar to :ref:`response-ip-data<unbound.conf.response-ip-data>` but
only applies to this view.
@@UAHL@unbound.conf.view@view-first@@: *<yes or no>*
If enabled, it attempts to use the global
:ref:`local-zone<unbound.conf.local-zone>` and
@ -3910,10 +3993,14 @@ view does not have the option specified.
Default: no
Python Module Options
^^^^^^^^^^^^^^^^^^^^^
.. _unbound.conf.python:
The **python:** clause gives the settings for the *python(1)* script module.
Python Module Options
---------------------
These options are part of the ``python:`` section.
The ``python:`` section gives the settings for the *python(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
@ -3936,15 +4023,19 @@ path to the working directory.
Repeat this option for every python module instance added to the
:ref:`module-config<unbound.conf.module-config>` option.
Dynamic Library Module Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _unbound.conf.dynlib:
The **dynlib:** clause gives the settings for the ``dynlib`` module.
Dynamic Library Module Options
------------------------------
These options are part of the ``dynlib:`` section.
The ``dynlib:`` section gives the settings for the ``dynlib`` module.
This module is only a very small wrapper that allows dynamic modules to be
loaded on runtime instead of being compiled into the application.
To enable the dynlib module it has to be compiled into the daemon, and the word
``dynlib`` has to be put in the
:ref:`module-config<unbound.conf.module-config>` attribute.
:ref:`module-config<unbound.conf.module-config>` option.
Multiple instances of dynamic libraries are supported by adding the word
``dynlib`` more than once.
@ -3960,7 +4051,9 @@ directory.
:ref:`module-config<unbound.conf.module-config>` option.
DNS64 Module Options
^^^^^^^^^^^^^^^^^^^^
--------------------
These options are part of the ``server:`` section.
The ``dns64`` module must be configured in the
:ref:`module-config<unbound.conf.module-config>` directive, e.g.:
@ -3971,9 +4064,6 @@ The ``dns64`` module must be configured in the
and be compiled into the daemon to be enabled.
.. note::
These settings go in the :ref:`server:<unbound.conf.server>` section.
.. note::
If combining the ``respip`` and ``dns64`` modules, the ``respip`` module
needs to appear before the ``dns64`` module in the
@ -4005,13 +4095,13 @@ and be compiled into the daemon to be enabled.
per line.
Applies also to names underneath the name given.
NAT64 Operation
^^^^^^^^^^^^^^^
NAT64 Options
-------------
These options are part of the ``server:`` section.
NAT64 operation allows using a NAT64 prefix for outbound requests to IPv4-only
servers.
It is controlled by two options in the
:ref:`server:<unbound.conf.server>` section:
@@UAHL@unbound.conf.nat64@do-nat64@@: *<yes or no>*
@ -4028,10 +4118,14 @@ It is controlled by two options in the
Default: 64:ff9b::/96 (same as :ref:`dns64-prefix<unbound.conf.dns64.dns64-prefix>`)
DNSCrypt Options
^^^^^^^^^^^^^^^^
.. _unbound.conf.dnscrypt:
The **dnscrypt:** clause gives the settings of the dnscrypt channel.
DNSCrypt Options
----------------
These options are part of the ``dnscrypt:`` section.
The ``dnscrypt:`` section gives the settings of the dnscrypt channel.
While those options are available, they are only meaningful if Unbound was
compiled with ``--enable-dnscrypt``.
Currently certificate and secret/public keys cannot be generated by Unbound.
@ -4138,7 +4232,9 @@ https://github.com/cofyc/dnscrypt-wrapper/blob/master/README.md#usage
Default: (unconfigured)
EDNS Client Subnet Module Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
---------------------------------
These options are part of the ``server:`` section.
The ECS module must be configured in the
:ref:`module-config<unbound.conf.module-config>` directive, e.g.:
@ -4149,9 +4245,6 @@ The ECS module must be configured in the
and be compiled into the daemon to be enabled.
.. note::
These settings go in the :ref:`server:<unbound.conf.server>` section.
If the destination address is allowed in the configuration Unbound will add the
EDNS0 option to the query containing the relevant part of the client's address.
When an answer contains the ECS option the response and the option are placed
@ -4266,7 +4359,9 @@ This module does not interact with the
Default: 100
Opportunistic IPsec Support Module Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------------
These options are part of the ``server:`` section.
The IPsec module must be configured in the
:ref:`module-config<unbound.conf.module-config>` directive, e.g.:
@ -4277,9 +4372,6 @@ The IPsec module must be configured in the
and be compiled into Unbound by using ``--enable-ipsecmod`` to be enabled.
.. note::
These settings go in the :ref:`server:<unbound.conf.server>` section.
When Unbound receives an A/AAAA query that is not in the cache and finds a
valid answer, it will withhold returning the answer and instead will generate
an IPSECKEY subquery for the same domain name.
@ -4369,8 +4461,12 @@ answer given from cache is still relevant for opportunistic IPsec.
@@UAHL@unbound.conf@ipsecmod-whitelist@@: *<domain>*
Alternate syntax for :ref:`ipsecmod-allow<unbound.conf.ipsecmod-allow>`.
.. _unbound.conf.cachedb:
Cache DB Module Options
^^^^^^^^^^^^^^^^^^^^^^^
-----------------------
These options are part of the ``cachedb:`` section.
The Cache DB module must be configured in the
:ref:`module-config<unbound.conf.module-config>` directive, e.g.:
@ -4422,7 +4518,7 @@ If connection close or timeout happens too often, Unbound will be effectively
unusable with this backend.
It's the administrator's responsibility to make the assumption hold.
The **cachedb:** clause gives custom settings of the cache DB module.
The ``cachedb:`` section gives custom settings of the cache DB module.
@@UAHL@unbound.conf.cachedb@backend@@: *<backend name>*
@ -4470,7 +4566,7 @@ The **cachedb:** clause gives custom settings of the cache DB module.
Default: yes
The following **cachedb:** options are specific to the ``redis`` backend.
The following ``cachedb:`` options are specific to the ``redis`` backend.
@@UAHL@unbound.conf.cachedb@redis-server-host@@: *<server address or name>*
@ -4629,11 +4725,14 @@ The following **cachedb:** options are specific to the ``redis`` backend.
.. _unbound.conf.dnstap:
DNSTAP Logging Options
^^^^^^^^^^^^^^^^^^^^^^
DNSTAP Options
--------------
DNSTAP support, when compiled in by using ``--enable-dnstap``, is enabled in
the **dnstap:** section.
These options are part of the ``dnstap:`` section.
DNSTAP is a flexible, structured binary log format for DNS software.
When compiled in by using ``--enable-dnstap``, it can be enabled in the
``dnstap:`` section.
This starts an extra thread (when compiled with threading) that writes the log
information to the destination.
If Unbound is compiled without threading it does not spawn a thread, but
@ -4783,15 +4882,18 @@ connects per-process to the destination.
.. _unbound.conf.rpz:
Response Policy Zone Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
----------------------------
Response Policy Zones are configured with **rpz:**, and each one must have a
:ref:`name<unbound.conf.rpz.name>` attribute.
There can be multiple ones, by listing multiple RPZ clauses, each with a
different name.
RPZ clauses are applied in order of configuration and any match from an earlier
RPZ zone will terminate the RPZ lookup.
These options are part of the ``rpz:`` section.
Response Policy Zones are configured with ``rpz:`` section clauses, and each
one must have a :ref:`name<unbound.conf.rpz.name>` option.
There can be multiple ones, by listing multiple ``rpz:`` section clauses, each
with a different name.
RPZ sections are applied in order of configuration and any match from an
earlier RPZ zone will terminate the RPZ lookup.
Note that a PASSTHRU action is still considered a match.
The respip module needs to be added to the
:ref:`module-config<unbound.conf.module-config>`, e.g.:
@ -4857,9 +4959,6 @@ The actions are specified with the record on the right
Other records like AAAA, TXT and other CNAMEs (not rpz-..) can also be used to
answer queries with that content.
The RPZ zones can be configured in the config file with these settings in the
**rpz:** block.
@@UAHL@unbound.conf.rpz@name@@: *<zone name>*
Name of the authority zone.
@ -4975,7 +5074,7 @@ The RPZ zones can be configured in the config file with these settings in the
@@UAHL@unbound.conf.rpz@tags@@: *"<list of tags>"*
Limit the policies from this RPZ clause to clients with a matching tag.
Limit the policies from this RPZ section to clients with a matching tag.
Tags need to be defined in :ref:`define-tag<unbound.conf.define-tag>` and
can be assigned to client addresses using
@ -4983,7 +5082,7 @@ The RPZ zones can be configured in the config file with these settings in the
:ref:`interface-tag<unbound.conf.interface-tag>`.
Enclose list of tags in quotes (``""``) and put spaces between tags.
If no tags are specified the policies from this clause will be applied for
If no tags are specified the policies from this section will be applied for
all clients.
Memory Control Example