From 9602973c863d506cfce88d632919136627901bb4 Mon Sep 17 00:00:00 2001 From: Yorgos Thessalonikefs Date: Fri, 24 Oct 2025 14:23:53 +0200 Subject: [PATCH] - unbound.conf man page updates to include a preview of the section clauses and some reformatting around the use of "clause", "option" and "attributes". --- doc/Changelog | 5 + doc/example.conf.in | 27 +++- doc/unbound.conf.5.in | 344 ++++++++++++++++++++++++++++-------------- doc/unbound.conf.rst | 329 ++++++++++++++++++++++++++-------------- 4 files changed, 469 insertions(+), 236 deletions(-) diff --git a/doc/Changelog b/doc/Changelog index 07c0831ad..aa3222c25 100644 --- a/doc/Changelog +++ b/doc/Changelog @@ -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. diff --git a/doc/example.conf.in b/doc/example.conf.in index 75821d7ea..296dabbd2 100644 --- a/doc/example.conf.in +++ b/doc/example.conf.in @@ -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" diff --git a/doc/unbound.conf.5.in b/doc/unbound.conf.5.in index f15cf9bad..f4b71bd14 100644 --- a/doc/unbound.conf.5.in +++ b/doc/unbound.conf.5.in @@ -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 +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 -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. +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\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\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\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\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\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 +These options are part of the \fBstub\-zone:\fP section. .sp -There may be multiple \fBstub\-zone:\fP clauses. +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: 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\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 +These options are part of the \fBforward\-zone:\fP section. .sp -There may be multiple \fBforward\-zone:\fP clauses. +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 +These options are part of the \fBview:\fP section. .sp -There may be multiple \fBview:\fP clauses. +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 \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 <\(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\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 +These options are part of the \fBpython:\fP section. .sp -The \fBpython:\fP clause gives the settings for the \fIpython(1)\fP script module. +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\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 +These options are part of the \fBdnscrypt:\fP section. .sp -The \fBdnscrypt:\fP clause gives the settings of the dnscrypt channel. +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\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\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\fP @@ -5686,7 +5796,7 @@ Default: no .INDENT 0.0 .TP .B tags: \fI\(dq\(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 diff --git a/doc/unbound.conf.rst b/doc/unbound.conf.rst index e4c29dfcf..ba908fb23 100644 --- a/doc/unbound.conf.rst +++ b/doc/unbound.conf.rst @@ -46,34 +46,41 @@ Description ----------- **unbound.conf** is used to configure :doc:`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 :doc:`unbound-checkconf(8)` 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`. + 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: + +Section Clauses +--------------- + +The recognized section clauses are: + + :ref:`server:` + Most of the configuration is found in this section. + + :ref:`remote-control:` + Configuration for the facility used by + :doc:`unbound-control(8)`. + + :ref:`stub-zone:` + 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:` + Configuration for a zone that forwards to specific DNS resolvers. -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. + :ref:`auth-zone:` + Configuration for local authoritative zones. + + :ref:`view:` + Overriding a small subset of configuration for incoming requests. + Requests are mapped to views with + :ref:`access-control-view` and + :ref:`interface-view`. + + :ref:`python:` + Configuration for the optional ``python`` script module. + + :ref:`dynlib:` + Configuration for the optional ``dynlib`` module that loads dynamic + libraries into Unbound. + + :ref:`dnscrypt:` + Configuration for the optional DNSCrypt feature. + + :ref:`cachedb:` + Configuration for the optional ``cachedb`` module that can interface + with second level caches, currently Redis or Redis-complatible + databases. + + :ref:`dnstap:` + Configuration of the optional dnstap logging feature; a flexible, + structured binary log format for DNS software. + + :ref:`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@@: ** @@ -1056,8 +1115,8 @@ These options are part of the **server:** clause. @@UAHL@unbound.conf@tls-system-cert@@: ** - This the same attribute as the - :ref:`tls-win-cert` attribute, under a + This the same as the + :ref:`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` 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@@: * <"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` 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@@: * * @@ -1467,8 +1526,8 @@ These options are part of the **server:** clause. .. note:: The interface needs to be already specified with :ref:`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@@: * <"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` 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@@: * * @@ -1490,8 +1549,8 @@ These options are part of the **server:** clause. .. note:: The interface needs to be already specified with :ref:`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@@: ** @@ -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` - 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` with action being to redirect as specified by *<"resource record string">*. *<"Resource record string">* is similar to that of - :ref:`access-control-tag-action`, + :ref:`access-control-tag-data`, but it must be of either AAAA, A or CNAME types. If the ** 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)` 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)` 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)` 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@@: ** @@ -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` 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` statements for :ref:`domain-insecure` and for :ref:`local-zone: \ nodefault` for the zone if it is a locally served zone. -The insecure clause stops DNSSEC from invalidating the zone. +The :ref:`domain-insecure` option stops DNSSEC +from invalidating the zone. The :ref:`local-zone: nodefault` (or -:ref:`transparent`) clause makes the +:ref:`transparent`) option makes the (reverse-) zone bypass Unbound's filtering of :rfc:`1918` zones. @@ -3508,9 +3571,9 @@ The :ref:`local-zone: nodefault` (or @@UAHL@unbound.conf.stub@stub-first@@: ** - 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` (or .. _unbound.conf.forward: Forward Zone Options -^^^^^^^^^^^^^^^^^^^^ +-------------------- + +These options are part of the ``forward-zone:`` section. -There may be multiple **forward-zone:** clauses. +There may be multiple ``forward-zone:`` sections. Each with a :ref:`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 -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- + +These options are part of the ``auth-zone:`` section. -Authority zones are configured with **auth-zone:**, and each one must have a +Authority zones are configured with ``auth-zone:``, and each one must have a :ref:`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` and zero or more :ref:`local-zone` and -:ref:`local-data` attributes. +:ref:`local-data` options. Views can also contain :ref:`view-first`, :ref:`response-ip`, :ref:`response-ip-data` and -:ref:`local-data-ptr` attributes. +:ref:`local-data-ptr` options. View can be mapped to requests by specifying the view name in an -:ref:`access-control-view` attribute. +:ref:`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` attribute. + :ref:`access-control-view` option. @@UAHL@unbound.conf.view@local-zone@@: * * @@ -3902,6 +3971,20 @@ view does not have the option specified. :ref:`local-data-ptr` elements. +@@UAHL@unbound.conf.view@response-ip@@: * * + This requires use of the ``respip`` module. + + Similar to :ref:`response-ip` but + only applies to this view. + + +@@UAHL@unbound.conf.view@response-ip-data@@: * <"resource record string">* + This requires use of the ``respip`` module. + + Similar to :ref:`response-ip-data` but + only applies to this view. + + @@UAHL@unbound.conf.view@view-first@@: ** If enabled, it attempts to use the global :ref:`local-zone` and @@ -3910,10 +3993,14 @@ view does not have the option specified. Default: no +.. _unbound.conf.python: + Python Module Options -^^^^^^^^^^^^^^^^^^^^^ +--------------------- -The **python:** clause gives the settings for the *python(1)* script module. +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` option. +.. _unbound.conf.dynlib: + Dynamic Library Module Options -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------ -The **dynlib:** clause gives the settings for the ``dynlib`` module. +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` attribute. +:ref:`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` option. DNS64 Module Options -^^^^^^^^^^^^^^^^^^^^ +-------------------- + +These options are part of the ``server:`` section. The ``dns64`` module must be configured in the :ref:`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:` 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:` section: @@UAHL@unbound.conf.nat64@do-nat64@@: ** @@ -4028,10 +4118,14 @@ It is controlled by two options in the Default: 64:ff9b::/96 (same as :ref:`dns64-prefix`) +.. _unbound.conf.dnscrypt: + DNSCrypt Options -^^^^^^^^^^^^^^^^ +---------------- -The **dnscrypt:** clause gives the settings of the dnscrypt channel. +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` 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:` 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` 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:` 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@@: ** Alternate syntax for :ref:`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` 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@@: ** @@ -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@@: ** @@ -4629,11 +4725,14 @@ The following **cachedb:** options are specific to the ``redis`` backend. .. _unbound.conf.dnstap: -DNSTAP Logging Options -^^^^^^^^^^^^^^^^^^^^^^ +DNSTAP Options +-------------- + +These options are part of the ``dnstap:`` section. -DNSTAP support, when compiled in by using ``--enable-dnstap``, is enabled in -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` 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` 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`, 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@@: ** 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@@: *""* - 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` 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`. 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 -- 2.47.3