Introduce restructuredText man pages to sync the online and source code man page documentation.
The templated man pages (*.in) are still part of the repo but generated with docutils from their .rst counterpart.
Documentation on how to generate those (mainly for core developers) are in README.man.
--- /dev/null
+After Unbound 1.23.0, the source of the man pages is in reStructuredText format.
+
+This helps with the online documentation at https://unbound.docs.nlnetlabs.nl
+and makes it easier to maintain and contribute to the documentation.
+
+The templated man pages (*.in) are still part of the code repository as to not
+alter current procedures that could be in place by users/packagers.
+
+The templated man pages (*.in) are generated by Sphinx (used for the online
+documentation).
+The online documentation has its own repository at
+https://github.com/NLnetLabs/unbound-manual.
+
+In the README.md there (branch test-auto for now), there are further simple
+instructions on how to generate the templated man pages there and update them
+in this repository.
-.TH "libunbound" "3" "@date@" "NLnet Labs" "unbound @version@"
-.\"
-.\" libunbound.3 -- unbound library functions manual
-.\"
-.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
-.\"
-.\" See LICENSE for the license.
-.\"
-.\"
-.SH "NAME"
-.B libunbound,
-.B unbound.h,
-.B ub_ctx,
-.B ub_result,
-.B ub_callback_type,
-.B ub_ctx_create,
-.B ub_ctx_delete,
-.B ub_ctx_set_option,
-.B ub_ctx_get_option,
-.B ub_ctx_config,
-.B ub_ctx_set_fwd,
-.B ub_ctx_set_stub,
-.B ub_ctx_set_tls,
-.B ub_ctx_resolvconf,
-.B ub_ctx_hosts,
-.B ub_ctx_add_ta,
-.B ub_ctx_add_ta_autr,
-.B ub_ctx_add_ta_file,
-.B ub_ctx_trustedkeys,
-.B ub_ctx_debugout,
-.B ub_ctx_debuglevel,
-.B ub_ctx_async,
-.B ub_poll,
-.B ub_wait,
-.B ub_fd,
-.B ub_process,
-.B ub_resolve,
-.B ub_resolve_async,
-.B ub_cancel,
-.B ub_resolve_free,
-.B ub_strerror,
-.B ub_ctx_print_local_zones,
-.B ub_ctx_zone_add,
-.B ub_ctx_zone_remove,
-.B ub_ctx_data_add,
-.B ub_ctx_data_remove
-\- Unbound DNS validating resolver @version@ functions.
-.SH "SYNOPSIS"
-.B #include <unbound.h>
-.LP
-\fIstruct ub_ctx *\fR
-\fBub_ctx_create\fR(\fIvoid\fR);
-.LP
-\fIvoid\fR
-\fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx);
-.LP
-\fIint\fR
-\fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val);
-.LP
-\fIint\fR
-\fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val);
-.LP
-\fIint\fR
-\fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
-.LP
-\fIint\fR
-\fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr);
-.LP
-\fIint\fR
-\fBub_ctx_set_stub\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone,
-\fIchar*\fR addr,
-.br
- \fIint\fR isprime);
-.LP
-\fIint\fR
-\fBub_ctx_set_tls\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR tls);
-.LP
-\fIint\fR
-\fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
-.LP
-\fIint\fR
-\fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
-.LP
-\fIint\fR
-\fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta);
-.LP
-\fIint\fR
-\fBub_ctx_add_ta_autr\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
-.LP
-\fIint\fR
-\fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
-.LP
-\fIint\fR
-\fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
-.LP
-\fIint\fR
-\fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out);
-.LP
-\fIint\fR
-\fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d);
-.LP
-\fIint\fR
-\fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread);
-.LP
-\fIint\fR
-\fBub_poll\fR(\fIstruct ub_ctx*\fR ctx);
-.LP
-\fIint\fR
-\fBub_wait\fR(\fIstruct ub_ctx*\fR ctx);
-.LP
-\fIint\fR
-\fBub_fd\fR(\fIstruct ub_ctx*\fR ctx);
-.LP
-\fIint\fR
-\fBub_process\fR(\fIstruct ub_ctx*\fR ctx);
-.LP
-\fIint\fR
-\fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
-.br
- \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result);
-.LP
-\fIint\fR
-\fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
-.br
- \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata,
-.br
- \fIub_callback_type\fR callback, \fIint*\fR async_id);
-.LP
-\fIint\fR
-\fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id);
-.LP
-\fIvoid\fR
-\fBub_resolve_free\fR(\fIstruct ub_result*\fR result);
-.LP
-\fIconst char *\fR
-\fBub_strerror\fR(\fIint\fR err);
-.LP
-\fIint\fR
-\fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx);
-.LP
-\fIint\fR
-\fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type);
-.LP
-\fIint\fR
-\fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name);
-.LP
-\fIint\fR
-\fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
-.LP
-\fIint\fR
-\fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
-.SH "DESCRIPTION"
-.B Unbound
-is an implementation of a DNS resolver, that does caching and
-DNSSEC validation. This is the library API, for using the \-lunbound library.
-The server daemon is described in \fIunbound\fR(8).
-The library works independent from a running unbound server, and
-can be used to convert hostnames to ip addresses, and back,
-and obtain other information from the DNS. The library performs public\-key
-validation of results with DNSSEC.
-.P
-The library uses a variable of type \fIstruct ub_ctx\fR to keep context
-between calls. The user must maintain it, creating it with
-.B ub_ctx_create
-and deleting it with
-.B ub_ctx_delete\fR.
-It can be created and deleted at any time. Creating it anew removes any
-previous configuration (such as trusted keys) and clears any cached results.
-.P
-The functions are thread\-safe, and a context can be used in a threaded (as
-well as in a non\-threaded) environment. Also resolution (and validation)
-can be performed blocking and non\-blocking (also called asynchronous).
-The async method returns from the call immediately, so that processing
-can go on, while the results become available later.
-.P
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "LIBUNBOUND" "3" "@date@" "@version@" "Unbound"
+.SH NAME
+libunbound \- Unbound DNS validating resolver @version@ functions.
+.SH SYNOPSIS
+.sp
+\fB#include <unbound.h>\fP
+.sp
+struct ub_ctx * \fBub_ctx_create\fP(void);
+.sp
+void \fBub_ctx_delete\fP(struct ub_ctx* ctx);
+.sp
+int \fBub_ctx_set_option\fP(struct ub_ctx* ctx, char* opt, char* val);
+.sp
+int \fBub_ctx_get_option\fP(struct ub_ctx* ctx, char* opt, char** val);
+.sp
+int \fBub_ctx_config\fP(struct ub_ctx* ctx, char* fname);
+.sp
+int \fBub_ctx_set_fwd\fP(struct ub_ctx* ctx, char* addr);
+.INDENT 0.0
+.TP
+int \fBub_ctx_set_stub\fP(struct ub_ctx* ctx, char* zone, char* addr,
+int isprime);
+.UNINDENT
+.sp
+int \fBub_ctx_set_tls\fP(struct ub_ctx* ctx, int tls);
+.sp
+int \fBub_ctx_resolvconf\fP(struct ub_ctx* ctx, char* fname);
+.sp
+int \fBub_ctx_hosts\fP(struct ub_ctx* ctx, char* fname);
+.sp
+int \fBub_ctx_add_ta\fP(struct ub_ctx* ctx, char* ta);
+.sp
+int \fBub_ctx_add_ta_autr\fP(struct ub_ctx* ctx, char* fname);
+.sp
+int \fBub_ctx_add_ta_file\fP(struct ub_ctx* ctx, char* fname);
+.sp
+int \fBub_ctx_trustedkeys\fP(struct ub_ctx* ctx, char* fname);
+.sp
+int \fBub_ctx_debugout\fP(struct ub_ctx* ctx, FILE* out);
+.sp
+int \fBub_ctx_debuglevel\fP(struct ub_ctx* ctx, int d);
+.sp
+int \fBub_ctx_async\fP(struct ub_ctx* ctx, int dothread);
+.sp
+int \fBub_poll\fP(struct ub_ctx* ctx);
+.sp
+int \fBub_wait\fP(struct ub_ctx* ctx);
+.sp
+int \fBub_fd\fP(struct ub_ctx* ctx);
+.sp
+int \fBub_process\fP(struct ub_ctx* ctx);
+.INDENT 0.0
+.TP
+int \fBub_resolve\fP(struct ub_ctx* ctx, char* name,
+int rrtype, int rrclass, struct ub_result** result);
+.TP
+int \fBub_resolve_async\fP(struct ub_ctx* ctx, char* name,
+int rrtype, int rrclass, void* mydata,
+ub_callback_type* callback, int* async_id);
+.UNINDENT
+.sp
+int \fBub_cancel\fP(struct ub_ctx* ctx, int async_id);
+.sp
+void \fBub_resolve_free\fP(struct ub_result* result);
+.sp
+const char * \fBub_strerror\fP(int err);
+.sp
+int \fBub_ctx_print_local_zones\fP(struct ub_ctx* ctx);
+.sp
+int \fBub_ctx_zone_add\fP(struct ub_ctx* ctx, char* zone_name, char* zone_type);
+.sp
+int \fBub_ctx_zone_remove\fP(struct ub_ctx* ctx, char* zone_name);
+.sp
+int \fBub_ctx_data_add\fP(struct ub_ctx* ctx, char* data);
+.sp
+int \fBub_ctx_data_remove\fP(struct ub_ctx* ctx, char* data);
+.SH DESCRIPTION
+.sp
+Unbound is an implementation of a DNS resolver, that does caching and DNSSEC
+validation.
+This is the library API, for using the \fB\-lunbound\fP library.
+The server daemon is described in \fI\%unbound(8)\fP\&.
+The library works independent from a running unbound server, and can be used to
+convert hostnames to ip addresses, and back, and obtain other information from
+the DNS.
+The library performs public\-key validation of results with DNSSEC.
+.sp
+The library uses a variable of type \fIstruct ub_ctx\fP to keep context between
+calls.
+The user must maintain it, creating it with \fBub_ctx_create\fP and deleting it
+with \fBub_ctx_delete\fP\&.
+It can be created and deleted at any time.
+Creating it anew removes any previous configuration (such as trusted keys) and
+clears any cached results.
+.sp
+The functions are thread\-safe, and a context can be used in a threaded (as well
+as in a non\-threaded) environment.
+Also resolution (and validation) can be performed blocking and non\-blocking
+(also called asynchronous).
+The async method returns from the call immediately, so that processing can go
+on, while the results become available later.
+.sp
The functions are discussed in turn below.
-.SH "FUNCTIONS"
-.TP
+.SH FUNCTIONS
+.INDENT 0.0
+.TP
.B ub_ctx_create
Create a new context, initialised with defaults.
-The information from /etc/resolv.conf and /etc/hosts is not utilised
-by default. Use
-.B ub_ctx_resolvconf
-and
-.B ub_ctx_hosts
-to read them.
-Before you call this, use the openssl functions CRYPTO_set_id_callback and
-CRYPTO_set_locking_callback to set up asynchronous operation if you use
-lib openssl (the application calls these functions once for initialisation).
-Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function.
+The information from \fB/etc/resolv.conf\fP and \fB/etc/hosts\fP is
+not utilised by default.
+Use \fBub_ctx_resolvconf\fP and \fBub_ctx_hosts\fP to read them.
+Before you call this, use the openssl functions
+\fBCRYPTO_set_id_callback\fP and \fBCRYPTO_set_locking_callback\fP to set
+up asynchronous operation if you use lib openssl (the application calls
+these functions once for initialisation).
+Openssl 1.0.0 or later uses the \fBCRYPTO_THREADID_set_callback\fP
+function.
.TP
.B ub_ctx_delete
Delete validation context and free associated resources.
-Outstanding async queries are killed and callbacks are not called for them.
+Outstanding async queries are killed and callbacks are not called for
+them.
.TP
.B ub_ctx_set_option
-A power\-user interface that lets you specify one of the options from the
-config file format, see \fIunbound.conf\fR(5). Not all options are
-relevant. For some specific options, such as adding trust anchors, special
-routines exist. Pass the option name with the trailing ':'.
+A power\-user interface that lets you specify one of the options from
+the config file format, see \fI\%unbound.conf(5)\fP\&.
+Not all options are relevant.
+For some specific options, such as adding trust anchors, special
+routines exist.
+Pass the option name with the trailing \fB\(aq:\(aq\fP\&.
.TP
.B ub_ctx_get_option
-A power\-user interface that gets an option value. Some options cannot be
-gotten, and others return a newline separated list. Pass the option name
-without trailing ':'. The returned value must be free(2)d by the caller.
+A power\-user interface that gets an option value.
+Some options cannot be gotten, and others return a newline separated
+list.
+Pass the option name without trailing \fB\(aq:\(aq\fP\&.
+The returned value must be free(2)d by the caller.
.TP
.B ub_ctx_config
-A power\-user interface that lets you specify an unbound config file, see
-\fIunbound.conf\fR(5), which is read for configuration. Not all options are
-relevant. For some specific options, such as adding trust anchors, special
-routines exist. This function is thread\-safe only if a single instance of
-ub_ctx* exists in the application. If several instances exist the
-application has to ensure that ub_ctx_config is not called in parallel by
-the different instances.
+A power\-user interface that lets you specify an unbound config file,
+see \fI\%unbound.conf(5)\fP, which is read for
+configuration.
+Not all options are relevant.
+For some specific options, such as adding trust anchors, special
+routines exist.
+This function is thread\-safe only if a single instance of \fBub_ctx\fP*
+exists in the application.
+If several instances exist the application has to ensure that
+\fBub_ctx_config\fP is not called in parallel by the different instances.
.TP
.B ub_ctx_set_fwd
-Set machine to forward DNS queries to, the caching resolver to use.
-IP4 or IP6 address. Forwards all DNS requests to that machine, which
-is expected to run a recursive resolver. If the proxy is not
-DNSSEC capable, validation may fail. Can be called several times, in
-that case the addresses are used as backup servers.
-At this time it is only possible to set configuration before the
-first resolve is done.
+Set machine to forward DNS queries to, the caching resolver to use.
+IP4 or IP6 address.
+Forwards all DNS requests to that machine, which is expected to run a
+recursive resolver.
+If the proxy is not DNSSEC capable, validation may fail.
+Can be called several times, in that case the addresses are used as
+backup servers.
+At this time it is only possible to set configuration before the first
+resolve is done.
.TP
.B ub_ctx_set_stub
-Set a stub zone, authoritative dns servers to use for a particular zone.
-IP4 or IP6 address. If the address is NULL the stub entry is removed.
-Set isprime true if you configure root hints with it. Otherwise similar to
-the stub zone item from unbound's config file. Can be called several times,
-for different zones, or to add multiple addresses for a particular zone.
-At this time it is only possible to set configuration before the
-first resolve is done.
+Set a stub zone, authoritative dns servers to use for a particular
+zone.
+IP4 or IP6 address.
+If the address is NULL the stub entry is removed.
+Set isprime true if you configure root hints with it.
+Otherwise similar to the stub zone item from unbound\(aqs config file.
+Can be called several times, for different zones, or to add multiple
+addresses for a particular zone.
+At this time it is only possible to set configuration before the first
+resolve is done.
.TP
.B ub_ctx_set_tls
-Enable DNS over TLS (DoT) for machines set with
-.B ub_ctx_set_fwd.
-At this time it is only possible to set configuration before the
-first resolve is done.
+Enable DNS over TLS (DoT) for machines set with \fBub_ctx_set_fwd\fP\&.
+At this time it is only possible to set configuration before the first
+resolve is done.
.TP
.B ub_ctx_resolvconf
-By default the root servers are queried and full resolver mode is used, but
-you can use this call to read the list of nameservers to use from the
-filename given.
-Usually "/etc/resolv.conf". Uses those nameservers as caching proxies.
+By default the root servers are queried and full resolver mode is used,
+but you can use this call to read the list of nameservers to use from
+the filename given.
+Usually \fB\(dq/etc/resolv.conf\(dq\fP\&.
+Uses those nameservers as caching proxies.
If they do not support DNSSEC, validation may fail.
Only nameservers are picked up, the searchdomain, ndots and other
-settings from \fIresolv.conf\fR(5) are ignored.
-If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows,
-the system\-wide configured nameserver is picked instead).
-At this time it is only possible to set configuration before the
-first resolve is done.
+settings from \fIresolv.conf(5)\fP are ignored.
+If fname NULL is passed, \fB\(dq/etc/resolv.conf\(dq\fP is used (if on
+Windows, the system\-wide configured nameserver is picked instead).
+At this time it is only possible to set configuration before the first
+resolve is done.
.TP
.B ub_ctx_hosts
Read list of hosts from the filename given.
-Usually "/etc/hosts". When queried for, these addresses are not marked
-DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used
-(if on Windows, etc/hosts from WINDIR is picked instead).
-At this time it is only possible to set configuration before the
-first resolve is done.
-.TP
-.B
-ub_ctx_add_ta
+Usually \fB\(dq/etc/hosts\(dq\fP\&.
+When queried for, these addresses are not marked DNSSEC secure.
+If fname NULL is passed, \fB\(dq/etc/hosts\(dq\fP is used (if on Windows,
+\fBetc/hosts\fP from WINDIR is picked instead).
+At this time it is only possible to set configuration before the first
+resolve is done.
+.TP
+.B ub_ctx_add_ta
Add a trust anchor to the given context.
-At this time it is only possible to add trusted keys before the
-first resolve is done.
+At this time it is only possible to add trusted keys before the first
+resolve is done.
The format is a string, similar to the zone\-file format,
-[domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted.
+\fB[domainname]\fP \fB[type]\fP \fB[rdata contents]\fP\&.
+Both DS and DNSKEY records are accepted.
.TP
.B ub_ctx_add_ta_autr
-Add filename with automatically tracked trust anchor to the given context.
-Pass name of a file with the managed trust anchor. You can create this
-file with \fIunbound\-anchor\fR(8) for the root anchor. You can also
-create it with an initial file with one line with a DNSKEY or DS record.
+Add filename with automatically tracked trust anchor to the given
+context.
+Pass name of a file with the managed trust anchor.
+You can create this file with
+\fI\%unbound\-anchor(8)\fP for the root anchor.
+You can also create it with an initial file with one line with a DNSKEY
+or DS record.
If the file is writable, it is updated when the trust anchor changes.
-At this time it is only possible to add trusted keys before the
-first resolve is done.
+At this time it is only possible to add trusted keys before the first
+resolve is done.
.TP
.B ub_ctx_add_ta_file
Add trust anchors to the given context.
Pass name of a file with DS and DNSKEY records in zone file format.
-At this time it is only possible to add trusted keys before the
-first resolve is done.
+At this time it is only possible to add trusted keys before the first
+resolve is done.
.TP
.B ub_ctx_trustedkeys
Add trust anchors to the given context.
-Pass the name of a bind\-style config file with trusted\-keys{}.
-At this time it is only possible to add trusted keys before the
-first resolve is done.
+Pass the name of a bind\-style config file with \fBtrusted\-keys{}\fP\&.
+At this time it is only possible to add trusted keys before the first
+resolve is done.
.TP
.B ub_ctx_debugout
-Set debug and error log output to the given stream. Pass NULL to disable
-output. Default is stderr. File\-names or using syslog can be enabled
-using config options, this routine is for using your own stream.
+Set debug and error log output to the given stream.
+Pass NULL to disable output.
+Default is stderr.
+File\-names or using syslog can be enabled using config options, this
+routine is for using your own stream.
.TP
.B ub_ctx_debuglevel
-Set debug verbosity for the context. Output is directed to stderr.
+Set debug verbosity for the context.
+Output is directed to stderr.
Higher debug level gives more output.
.TP
.B ub_ctx_async
Set a context behaviour for asynchronous action.
-if set to true, enables threading and a call to
-.B ub_resolve_async
+if set to true, enables threading and a call to \fBub_resolve_async\fP
creates a thread to handle work in the background.
If false, a process is forked to handle work in the background.
-Changes to this setting after
-.B ub_resolve_async
-calls have been made have no effect (delete and re\-create the context
-to change).
+Changes to this setting after \fBub_resolve_async\fP calls have been made
+have no effect (delete and re\-create the context to change).
.TP
.B ub_poll
Poll a context to see if it has any new results.
-Do not poll in a loop, instead extract the fd below to poll for readiness,
-and then check, or wait using the wait routine.
+Do not poll in a loop, instead extract the \fBfd\fP below to poll for
+readiness, and then check, or wait using the wait routine.
Returns 0 if nothing to read, or nonzero if a result is available.
-If nonzero, call
-.B ub_process
-to do callbacks.
+If nonzero, call \fBub_process\fP to do callbacks.
.TP
.B ub_wait
-Wait for a context to finish with results. Calls
-.B ub_process
-after the wait for you. After the wait, there are no more outstanding
-asynchronous queries.
+Wait for a context to finish with results.
+Calls \fBub_process\fP after the wait for you.
+After the wait, there are no more outstanding asynchronous queries.
.TP
.B ub_fd
-Get file descriptor. Wait for it to become readable, at this point
-answers are returned from the asynchronous validating resolver.
-Then call the \fBub_process\fR to continue processing.
+Get file descriptor.
+Wait for it to become readable, at this point answers are returned from
+the asynchronous validating resolver.
+Then call the \fBub_process\fP to continue processing.
.TP
.B ub_process
Call this routine to continue processing results from the validating
-resolver (when the fd becomes readable).
+resolver (when the \fBfd\fP becomes readable).
Will perform necessary callbacks.
.TP
.B ub_resolve
.TP
.B ub_resolve_async
Perform asynchronous resolution and validation of the target name.
-Arguments mean the same as for \fBub_resolve\fR except no
-data is returned immediately, instead a callback is called later.
-The callback receives a copy of the mydata pointer, that you can use to pass
-information to the callback. The callback type is a function pointer to
-a function declared as
-.IP
-void my_callback_function(void* my_arg, int err,
-.br
- struct ub_result* result);
-.IP
-The async_id is returned so you can (at your option) decide to track it
-and cancel the request if needed. If you pass a NULL pointer the async_id
-is not returned.
+Arguments mean the same as for \fBub_resolve\fP except no data is
+returned immediately, instead a callback is called later.
+The callback receives a copy of the mydata pointer, that you can use to
+pass information to the callback.
+The callback type is a function pointer to a function declared as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+void my_callback_function(void* my_arg, int err,
+ struct ub_result* result);
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBasync_id\fP is returned so you can (at your option) decide to
+track it and cancel the request if needed.
+If you pass a NULL pointer the \fBasync_id\fP is not returned.
.TP
.B ub_cancel
-Cancel an async query in progress. This may return an error if the query
-does not exist, or the query is already being delivered, in that case you
-may still get a callback for the query.
+Cancel an async query in progress.
+This may return an error if the query does not exist, or the query is
+already being delivered, in that case you may still get a callback for
+the query.
.TP
.B ub_resolve_free
-Free struct ub_result contents after use.
+Free struct \fBub_result\fP contents after use.
.TP
.B ub_strerror
-Convert error value from one of the unbound library functions
-to a human readable string.
+Convert error value from one of the unbound library functions to a
+human readable string.
.TP
.B ub_ctx_print_local_zones
Debug printout the local authority information to debug output.
.TP
.B ub_ctx_zone_add
-Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5)
-statement.
+Add new zone to local authority info, like local\-zone
+\fI\%unbound.conf(5)\fP statement.
.TP
.B ub_ctx_zone_remove
Delete zone from local authority info.
.TP
.B ub_ctx_data_add
Add resource record data to local authority info, like local\-data
-\fIunbound.conf\fR(5) statement.
+\fI\%unbound.conf(5)\fP statement.
.TP
.B ub_ctx_data_remove
Delete local authority data from the name given.
-.SH "RESULT DATA STRUCTURE"
-The result of the DNS resolution and validation is returned as
-\fIstruct ub_result\fR. The result structure contains the following entries.
-.P
+.UNINDENT
+.SH RESULT DATA STRUCTURE
+.sp
+The result of the DNS resolution and validation is returned as \fIstruct
+ub_result\fP\&.
+The result structure contains the following entries:
+.INDENT 0.0
+.INDENT 3.5
+.sp
.nf
- struct ub_result {
- char* qname; /* text string, original question */
- int qtype; /* type code asked for */
- int qclass; /* class code asked for */
- char** data; /* array of rdata items, NULL terminated*/
- int* len; /* array with lengths of rdata items */
- char* canonname; /* canonical name of result */
- int rcode; /* additional error code in case of no data */
- void* answer_packet; /* full network format answer packet */
- int answer_len; /* length of packet in octets */
- int havedata; /* true if there is data */
- int nxdomain; /* true if nodata because name does not exist */
- int secure; /* true if result is secure */
- int bogus; /* true if a security failure happened */
- char* why_bogus; /* string with error if bogus */
- int was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */
- int ttl; /* number of seconds the result is valid */
- };
+.ft C
+struct ub_result {
+ char* qname; /* text string, original question */
+ int qtype; /* type code asked for */
+ int qclass; /* class code asked for */
+ char** data; /* array of rdata items, NULL terminated*/
+ int* len; /* array with lengths of rdata items */
+ char* canonname; /* canonical name of result */
+ int rcode; /* additional error code in case of no data */
+ void* answer_packet; /* full network format answer packet */
+ int answer_len; /* length of packet in octets */
+ int havedata; /* true if there is data */
+ int nxdomain; /* true if nodata because name does not exist */
+ int secure; /* true if result is secure */
+ int bogus; /* true if a security failure happened */
+ char* why_bogus; /* string with error if bogus */
+ int was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */
+ int ttl; /* number of seconds the result is valid */
+};
+.ft P
.fi
-.P
-If both secure and bogus are false, security was not enabled for the
-domain of the query. Else, they are not both true, one of them is true.
-.SH "RETURN VALUES"
-Many routines return an error code. The value 0 (zero) denotes no error
-happened. Other values can be passed to
-.B ub_strerror
-to obtain a readable error string.
-.B ub_strerror
-returns a zero terminated string.
-.B ub_ctx_create
-returns NULL on an error (a malloc failure).
-.B ub_poll
-returns true if some information may be available, false otherwise.
-.B ub_fd
-returns a file descriptor or \-1 on error.
-.B ub_ctx_config
-and
-.B ub_ctx_resolvconf
-attempt to leave errno informative on a function return with file read failure.
-.SH "SEE ALSO"
-\fIunbound.conf\fR(5),
-\fIunbound\fR(8).
-.SH "AUTHORS"
-.B Unbound
-developers are mentioned in the CREDITS file in the distribution.
+.UNINDENT
+.UNINDENT
+.sp
+If both secure and bogus are false, security was not enabled for the domain of
+the query.
+Else, they are not both true, one of them is true.
+.SH RETURN VALUES
+.sp
+Many routines return an error code.
+The value 0 (zero) denotes no error happened.
+Other values can be passed to \fBub_strerror\fP to obtain a readable error
+string.
+\fBub_strerror\fP returns a zero terminated string.
+\fBub_ctx_create\fP returns NULL on an error (a malloc failure).
+\fBub_poll\fP returns true if some information may be available, false otherwise.
+\fBub_fd\fP returns a file descriptor or \-1 on error.
+\fBub_ctx_config\fP and \fBub_ctx_resolvconf\fP attempt to leave errno informative
+on a function return with file read failure.
+.SH SEE ALSO
+.sp
+\fI\%unbound.conf(5)\fP, \fI\%unbound(8)\fP\&.
+.SH AUTHOR
+Unbound developers are mentioned in the CREDITS file in the distribution.
+.SH COPYRIGHT
+1999-2025, NLnet Labs
+.\" Generated by docutils manpage writer.
+.
--- /dev/null
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+libunbound(3)
+=============
+
+Synopsis
+--------
+
+.. only:: html
+
+ .. code-block:: c
+
+ #include <unbound.h>
+
+ struct ub_ctx * ub_ctx_create(void);
+
+ void ub_ctx_delete(struct ub_ctx* ctx);
+
+ int ub_ctx_set_option(struct ub_ctx* ctx, char* opt, char* val);
+
+ int ub_ctx_get_option(struct ub_ctx* ctx, char* opt, char** val);
+
+ int ub_ctx_config(struct ub_ctx* ctx, char* fname);
+
+ int ub_ctx_set_fwd(struct ub_ctx* ctx, char* addr);
+
+ int ub_ctx_set_stub(struct ub_ctx* ctx, char* zone, char* addr,
+ int isprime);
+
+ int ub_ctx_set_tls(struct ub_ctx* ctx, int tls);
+
+ int ub_ctx_resolvconf(struct ub_ctx* ctx, char* fname);
+
+ int ub_ctx_hosts(struct ub_ctx* ctx, char* fname);
+
+ int ub_ctx_add_ta(struct ub_ctx* ctx, char* ta);
+
+ int ub_ctx_add_ta_autr(struct ub_ctx* ctx, char* fname);
+
+ int ub_ctx_add_ta_file(struct ub_ctx* ctx, char* fname);
+
+ int ub_ctx_trustedkeys(struct ub_ctx* ctx, char* fname);
+
+ int ub_ctx_debugout(struct ub_ctx* ctx, FILE* out);
+
+ int ub_ctx_debuglevel(struct ub_ctx* ctx, int d);
+
+ int ub_ctx_async(struct ub_ctx* ctx, int dothread);
+
+ int ub_poll(struct ub_ctx* ctx);
+
+ int ub_wait(struct ub_ctx* ctx);
+
+ int ub_fd(struct ub_ctx* ctx);
+
+ int ub_process(struct ub_ctx* ctx);
+
+ int ub_resolve(struct ub_ctx* ctx, char* name, int rrtype,
+ int rrclass, struct ub_result** result);
+
+ int ub_resolve_async(struct ub_ctx* ctx, char* name, int rrtype,
+ int rrclass, void* mydata, ub_callback_type callback,
+ int* async_id);
+
+ int ub_cancel(struct ub_ctx* ctx, int async_id);
+
+ void ub_resolve_free(struct ub_result* result);
+
+ const char * ub_strerror(int err);
+
+ int ub_ctx_print_local_zones(struct ub_ctx* ctx);
+
+ int ub_ctx_zone_add(struct ub_ctx* ctx, char* zone_name, char* zone_type);
+
+ int ub_ctx_zone_remove(struct ub_ctx* ctx, char* zone_name);
+
+ int ub_ctx_data_add(struct ub_ctx* ctx, char* data);
+
+ int ub_ctx_data_remove(struct ub_ctx* ctx, char* data);
+
+.. only:: man
+
+ **#include <unbound.h>**
+
+ struct ub_ctx \* **ub_ctx_create**\ (void);
+
+ void **ub_ctx_delete**\ (struct ub_ctx\* ctx);
+
+ int **ub_ctx_set_option**\ (struct ub_ctx\* ctx, char\* opt, char\* val);
+
+ int **ub_ctx_get_option**\ (struct ub_ctx\* ctx, char\* opt, char\*\* val);
+
+ int **ub_ctx_config**\ (struct ub_ctx\* ctx, char* fname);
+
+ int **ub_ctx_set_fwd**\ (struct ub_ctx\* ctx, char\* addr);
+
+ int **ub_ctx_set_stub**\ (struct ub_ctx\* ctx, char\* zone, char\* addr,
+ int isprime);
+
+ int **ub_ctx_set_tls**\ (struct ub_ctx\* ctx, int tls);
+
+ int **ub_ctx_resolvconf**\ (struct ub_ctx\* ctx, char\* fname);
+
+ int **ub_ctx_hosts**\ (struct ub_ctx\* ctx, char\* fname);
+
+ int **ub_ctx_add_ta**\ (struct ub_ctx\* ctx, char\* ta);
+
+ int **ub_ctx_add_ta_autr**\ (struct ub_ctx\* ctx, char\* fname);
+
+ int **ub_ctx_add_ta_file**\ (struct ub_ctx\* ctx, char\* fname);
+
+ int **ub_ctx_trustedkeys**\ (struct ub_ctx\* ctx, char\* fname);
+
+ int **ub_ctx_debugout**\ (struct ub_ctx\* ctx, FILE\* out);
+
+ int **ub_ctx_debuglevel**\ (struct ub_ctx\* ctx, int d);
+
+ int **ub_ctx_async**\ (struct ub_ctx\* ctx, int dothread);
+
+ int **ub_poll**\ (struct ub_ctx\* ctx);
+
+ int **ub_wait**\ (struct ub_ctx\* ctx);
+
+ int **ub_fd**\ (struct ub_ctx\* ctx);
+
+ int **ub_process**\ (struct ub_ctx\* ctx);
+
+ int **ub_resolve**\ (struct ub_ctx\* ctx, char\* name,
+ int rrtype, int rrclass, struct ub_result\*\* result);
+
+ int **ub_resolve_async**\ (struct ub_ctx\* ctx, char\* name,
+ int rrtype, int rrclass, void\* mydata,
+ ub_callback_type\* callback, int\* async_id);
+
+ int **ub_cancel**\ (struct ub_ctx\* ctx, int async_id);
+
+ void **ub_resolve_free**\ (struct ub_result\* result);
+
+ const char \* **ub_strerror**\ (int err);
+
+ int **ub_ctx_print_local_zones**\ (struct ub_ctx\* ctx);
+
+ int **ub_ctx_zone_add**\ (struct ub_ctx\* ctx, char\* zone_name, char\* zone_type);
+
+ int **ub_ctx_zone_remove**\ (struct ub_ctx\* ctx, char\* zone_name);
+
+ int **ub_ctx_data_add**\ (struct ub_ctx\* ctx, char\* data);
+
+ int **ub_ctx_data_remove**\ (struct ub_ctx\* ctx, char\* data);
+
+Description
+-----------
+
+Unbound is an implementation of a DNS resolver, that does caching and DNSSEC
+validation.
+This is the library API, for using the ``-lunbound`` library.
+The server daemon is described in :doc:`unbound(8)</manpages/unbound>`.
+The library works independent from a running unbound server, and can be used to
+convert hostnames to ip addresses, and back, and obtain other information from
+the DNS.
+The library performs public-key validation of results with DNSSEC.
+
+The library uses a variable of type *struct ub_ctx* to keep context between
+calls.
+The user must maintain it, creating it with **ub_ctx_create** and deleting it
+with **ub_ctx_delete**.
+It can be created and deleted at any time.
+Creating it anew removes any previous configuration (such as trusted keys) and
+clears any cached results.
+
+The functions are thread-safe, and a context can be used in a threaded (as well
+as in a non-threaded) environment.
+Also resolution (and validation) can be performed blocking and non-blocking
+(also called asynchronous).
+The async method returns from the call immediately, so that processing can go
+on, while the results become available later.
+
+The functions are discussed in turn below.
+
+Functions
+---------
+
+.. glossary::
+
+ ub_ctx_create
+ Create a new context, initialised with defaults.
+ The information from :file:`/etc/resolv.conf` and :file:`/etc/hosts` is
+ not utilised by default.
+ Use **ub_ctx_resolvconf** and **ub_ctx_hosts** to read them.
+ Before you call this, use the openssl functions
+ **CRYPTO_set_id_callback** and **CRYPTO_set_locking_callback** to set
+ up asynchronous operation if you use lib openssl (the application calls
+ these functions once for initialisation).
+ Openssl 1.0.0 or later uses the **CRYPTO_THREADID_set_callback**
+ function.
+
+ ub_ctx_delete
+ Delete validation context and free associated resources.
+ Outstanding async queries are killed and callbacks are not called for
+ them.
+
+ ub_ctx_set_option
+ A power-user interface that lets you specify one of the options from
+ the config file format, see :doc:`unbound.conf(5)</manpages/unbound.conf>`.
+ Not all options are relevant.
+ For some specific options, such as adding trust anchors, special
+ routines exist.
+ Pass the option name with the trailing ``':'``.
+
+ ub_ctx_get_option
+ A power-user interface that gets an option value.
+ Some options cannot be gotten, and others return a newline separated
+ list.
+ Pass the option name without trailing ``':'``.
+ The returned value must be free(2)d by the caller.
+
+ ub_ctx_config
+ A power-user interface that lets you specify an unbound config file,
+ see :doc:`unbound.conf(5)</manpages/unbound.conf>`, which is read for
+ configuration.
+ Not all options are relevant.
+ For some specific options, such as adding trust anchors, special
+ routines exist.
+ This function is thread-safe only if a single instance of **ub_ctx**\*
+ exists in the application.
+ If several instances exist the application has to ensure that
+ **ub_ctx_config** is not called in parallel by the different instances.
+
+ ub_ctx_set_fwd
+ Set machine to forward DNS queries to, the caching resolver to use.
+ IP4 or IP6 address.
+ Forwards all DNS requests to that machine, which is expected to run a
+ recursive resolver.
+ If the proxy is not DNSSEC capable, validation may fail.
+ Can be called several times, in that case the addresses are used as
+ backup servers.
+ At this time it is only possible to set configuration before the first
+ resolve is done.
+
+ ub_ctx_set_stub
+ Set a stub zone, authoritative dns servers to use for a particular
+ zone.
+ IP4 or IP6 address.
+ If the address is NULL the stub entry is removed.
+ Set isprime true if you configure root hints with it.
+ Otherwise similar to the stub zone item from unbound's config file.
+ Can be called several times, for different zones, or to add multiple
+ addresses for a particular zone.
+ At this time it is only possible to set configuration before the first
+ resolve is done.
+
+ ub_ctx_set_tls
+ Enable DNS over TLS (DoT) for machines set with **ub_ctx_set_fwd**.
+ At this time it is only possible to set configuration before the first
+ resolve is done.
+
+ ub_ctx_resolvconf
+ By default the root servers are queried and full resolver mode is used,
+ but you can use this call to read the list of nameservers to use from
+ the filename given.
+ Usually :file:`"/etc/resolv.conf"`.
+ Uses those nameservers as caching proxies.
+ If they do not support DNSSEC, validation may fail.
+ Only nameservers are picked up, the searchdomain, ndots and other
+ settings from *resolv.conf(5)* are ignored.
+ If fname NULL is passed, :file:`"/etc/resolv.conf"` is used (if on
+ Windows, the system-wide configured nameserver is picked instead).
+ At this time it is only possible to set configuration before the first
+ resolve is done.
+
+ ub_ctx_hosts
+ Read list of hosts from the filename given.
+ Usually :file:`"/etc/hosts"`.
+ When queried for, these addresses are not marked DNSSEC secure.
+ If fname NULL is passed, :file:`"/etc/hosts"` is used (if on Windows,
+ :file:`etc/hosts` from WINDIR is picked instead).
+ At this time it is only possible to set configuration before the first
+ resolve is done.
+
+ ub_ctx_add_ta
+ Add a trust anchor to the given context.
+ At this time it is only possible to add trusted keys before the first
+ resolve is done.
+ The format is a string, similar to the zone-file format,
+ **[domainname]** **[type]** **[rdata contents]**.
+ Both DS and DNSKEY records are accepted.
+
+ ub_ctx_add_ta_autr
+ Add filename with automatically tracked trust anchor to the given
+ context.
+ Pass name of a file with the managed trust anchor.
+ You can create this file with
+ :doc:`unbound-anchor(8)</manpages/unbound-anchor>` for the root anchor.
+ You can also create it with an initial file with one line with a DNSKEY
+ or DS record.
+ If the file is writable, it is updated when the trust anchor changes.
+ At this time it is only possible to add trusted keys before the first
+ resolve is done.
+
+ ub_ctx_add_ta_file
+ Add trust anchors to the given context.
+ Pass name of a file with DS and DNSKEY records in zone file format.
+ At this time it is only possible to add trusted keys before the first
+ resolve is done.
+
+ ub_ctx_trustedkeys
+ Add trust anchors to the given context.
+ Pass the name of a bind-style config file with ``trusted-keys{}``.
+ At this time it is only possible to add trusted keys before the first
+ resolve is done.
+
+ ub_ctx_debugout
+ Set debug and error log output to the given stream.
+ Pass NULL to disable output.
+ Default is stderr.
+ File-names or using syslog can be enabled using config options, this
+ routine is for using your own stream.
+
+ ub_ctx_debuglevel
+ Set debug verbosity for the context.
+ Output is directed to stderr.
+ Higher debug level gives more output.
+
+ ub_ctx_async
+ Set a context behaviour for asynchronous action.
+ if set to true, enables threading and a call to **ub_resolve_async**
+ creates a thread to handle work in the background.
+ If false, a process is forked to handle work in the background.
+ Changes to this setting after **ub_resolve_async** calls have been made
+ have no effect (delete and re-create the context to change).
+
+ ub_poll
+ Poll a context to see if it has any new results.
+ Do not poll in a loop, instead extract the **fd** below to poll for
+ readiness, and then check, or wait using the wait routine.
+ Returns 0 if nothing to read, or nonzero if a result is available.
+ If nonzero, call **ub_process** to do callbacks.
+
+ ub_wait
+ Wait for a context to finish with results.
+ Calls **ub_process** after the wait for you.
+ After the wait, there are no more outstanding asynchronous queries.
+
+ ub_fd
+ Get file descriptor.
+ Wait for it to become readable, at this point answers are returned from
+ the asynchronous validating resolver.
+ Then call the **ub_process** to continue processing.
+
+ ub_process
+ Call this routine to continue processing results from the validating
+ resolver (when the **fd** becomes readable).
+ Will perform necessary callbacks.
+
+ ub_resolve
+ Perform resolution and validation of the target name.
+ The name is a domain name in a zero terminated text string.
+ The rrtype and rrclass are DNS type and class codes.
+ The result structure is newly allocated with the resulting data.
+
+ ub_resolve_async
+ Perform asynchronous resolution and validation of the target name.
+ Arguments mean the same as for **ub_resolve** except no data is
+ returned immediately, instead a callback is called later.
+ The callback receives a copy of the mydata pointer, that you can use to
+ pass information to the callback.
+ The callback type is a function pointer to a function declared as:
+
+ .. code-block:: c
+
+ void my_callback_function(void* my_arg, int err,
+ struct ub_result* result);
+
+ The **async_id** is returned so you can (at your option) decide to
+ track it and cancel the request if needed.
+ If you pass a NULL pointer the **async_id** is not returned.
+
+ ub_cancel
+ Cancel an async query in progress.
+ This may return an error if the query does not exist, or the query is
+ already being delivered, in that case you may still get a callback for
+ the query.
+
+ ub_resolve_free
+ Free struct **ub_result** contents after use.
+
+ ub_strerror
+ Convert error value from one of the unbound library functions to a
+ human readable string.
+
+ ub_ctx_print_local_zones
+ Debug printout the local authority information to debug output.
+
+ ub_ctx_zone_add
+ Add new zone to local authority info, like local-zone
+ :doc:`unbound.conf(5)</manpages/unbound.conf>` statement.
+
+ ub_ctx_zone_remove
+ Delete zone from local authority info.
+
+ ub_ctx_data_add
+ Add resource record data to local authority info, like local-data
+ :doc:`unbound.conf(5)</manpages/unbound.conf>` statement.
+
+ ub_ctx_data_remove
+ Delete local authority data from the name given.
+
+Result Data structure
+---------------------
+
+The result of the DNS resolution and validation is returned as *struct
+ub_result*.
+The result structure contains the following entries:
+
+.. code-block:: c
+
+ struct ub_result {
+ char* qname; /* text string, original question */
+ int qtype; /* type code asked for */
+ int qclass; /* class code asked for */
+ char** data; /* array of rdata items, NULL terminated*/
+ int* len; /* array with lengths of rdata items */
+ char* canonname; /* canonical name of result */
+ int rcode; /* additional error code in case of no data */
+ void* answer_packet; /* full network format answer packet */
+ int answer_len; /* length of packet in octets */
+ int havedata; /* true if there is data */
+ int nxdomain; /* true if nodata because name does not exist */
+ int secure; /* true if result is secure */
+ int bogus; /* true if a security failure happened */
+ char* why_bogus; /* string with error if bogus */
+ int was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */
+ int ttl; /* number of seconds the result is valid */
+ };
+
+If both secure and bogus are false, security was not enabled for the domain of
+the query.
+Else, they are not both true, one of them is true.
+
+Return Values
+-------------
+
+Many routines return an error code.
+The value 0 (zero) denotes no error happened.
+Other values can be passed to **ub_strerror** to obtain a readable error
+string.
+**ub_strerror** returns a zero terminated string.
+**ub_ctx_create** returns NULL on an error (a malloc failure).
+**ub_poll** returns true if some information may be available, false otherwise.
+**ub_fd** returns a file descriptor or -1 on error.
+**ub_ctx_config** and **ub_ctx_resolvconf** attempt to leave errno informative
+on a function return with file read failure.
+
+See Also
+--------
+
+:doc:`unbound.conf(5)</manpages/unbound.conf>`, :doc:`unbound(8)</manpages/unbound>`.
-.TH "unbound-anchor" "8" "@date@" "NLnet Labs" "unbound @version@"
-.\"
-.\" unbound-anchor.8 -- unbound anchor maintenance utility manual
-.\"
-.\" Copyright (c) 2008, NLnet Labs. All rights reserved.
-.\"
-.\" See LICENSE for the license.
-.\"
-.\"
-.SH "NAME"
-.B unbound\-anchor
-\- Unbound anchor utility.
-.SH "SYNOPSIS"
-.B unbound\-anchor
-.RB [ opts ]
-.SH "DESCRIPTION"
-.B Unbound\-anchor
-performs setup or update of the root trust anchor for DNSSEC validation.
-The program fetches the trust anchor with the method from RFC7958 when
-regular RFC5011 update fails to bring it up to date.
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "UNBOUND-ANCHOR" "8" "@date@" "@version@" "Unbound"
+.SH NAME
+unbound-anchor \- Unbound @version@ anchor utility.
+.SH SYNOPSIS
+.sp
+\fBunbound\-anchor\fP [\fBopts\fP]
+.SH DESCRIPTION
+.sp
+\fBunbound\-anchor\fP performs setup or update of the root trust anchor for DNSSEC
+validation.
+The program fetches the trust anchor with the method from \fI\%RFC 7958\fP when
+regular \fI\%RFC 5011\fP update fails to bring it up to date.
It can be run (as root) from the commandline, or run as part of startup
-scripts. Before you start the \fIunbound\fR(8) DNS server.
-.P
+scripts.
+Before you start the \fI\%unbound(8)\fP DNS server.
+.sp
Suggested usage:
-.P
+.INDENT 0.0
+.INDENT 3.5
+.sp
.nf
- # in the init scripts.
- # provide or update the root anchor (if necessary)
- unbound-anchor \-a "@UNBOUND_ROOTKEY_FILE@"
- # Please note usage of this root anchor is at your own risk
- # and under the terms of our LICENSE (see source).
- #
- # start validating resolver
- # the unbound.conf contains:
- # auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@"
- unbound \-c unbound.conf
+.ft C
+# in the init scripts.
+# provide or update the root anchor (if necessary)
+unbound\-anchor \-a \(dq@UNBOUND_ROOTKEY_FILE@\(dq
+# Please note usage of this root anchor is at your own risk
+# and under the terms of our LICENSE (see source).
+#
+# start validating resolver
+# the unbound.conf contains:
+# auto\-trust\-anchor\-file: \(dq@UNBOUND_ROOTKEY_FILE@\(dq
+unbound \-c unbound.conf
+.ft P
.fi
-.P
-This tool provides builtin default contents for the root anchor and root
-update certificate files.
-.P
+.UNINDENT
+.UNINDENT
+.sp
+This tool provides builtin default contents for the root anchor and root update
+certificate files.
+.sp
It tests if the root anchor file works, and if not, and an update is possible,
attempts to update the root anchor using the root update certificate.
-It performs a https fetch of root-anchors.xml and checks the results (RFC7958),
-if all checks are successful, it updates the root anchor file. Otherwise
-the root anchor file is unchanged. It performs RFC5011 tracking if the
-DNSSEC information available via the DNS makes that possible.
-.P
-It does not perform an update if the certificate is expired, if the network
-is down or other errors occur.
-.P
+It performs a https fetch of
+\fI\%root\-anchors.xml\fP
+and checks the results (\fI\%RFC 7958\fP); if all checks are successful, it updates
+the root anchor file.
+Otherwise the root anchor file is unchanged.
+It performs \fI\%RFC 5011\fP tracking if the DNSSEC information available via the
+DNS makes that possible.
+.sp
+It does not perform an update if the certificate is expired, if the network is
+down or other errors occur.
+.sp
The available options are:
+.INDENT 0.0
.TP
-.B \-a \fIfile
+.B \-a <file>
The root anchor key file, that is read in and written out.
-Default is @UNBOUND_ROOTKEY_FILE@.
-If the file does not exist, or is empty, a builtin root key is written to it.
+Default is \fB@UNBOUND_ROOTKEY_FILE@\fP\&.
+If the file does not exist, or is empty, a builtin root key is written
+to it.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-c \fIfile
+.B \-c <file>
The root update certificate file, that is read in.
-Default is @UNBOUND_ROOTCERT_FILE@.
+Default is \fB@UNBOUND_ROOTCERT_FILE@\fP\&.
If the file does not exist, or is empty, a builtin certificate is used.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-l
List the builtin root key and builtin root update certificate on stdout.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-u \fIname
-The server name, it connects to https://name. Specify without https:// prefix.
-The default is "data.iana.org". It connects to the port specified with \-P.
+.B \-u <name>
+The server name, it connects to \fBhttps://name\fP\&.
+Specify without \fBhttps://\fP prefix.
+The default is \fB\(dqdata.iana.org\(dq\fP\&.
+It connects to the port specified with \fI\%\-P\fP\&.
You can pass an IPv4 address or IPv6 address (no brackets) if you want.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-S
-Do not use SNI for the HTTPS connection. Default is to use SNI.
+Do not use SNI for the HTTPS connection.
+Default is to use SNI.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-b \fIaddress
-The source address to bind to for domain resolution and contacting the server
-on https. May be either an IPv4 address or IPv6 address (no brackets).
+.B \-b <address>
+The source address to bind to for domain resolution and contacting the
+server on https.
+May be either an IPv4 address or IPv6 address (no brackets).
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-x \fIpath
-The pathname to the root\-anchors.xml file on the server. (forms URL with \-u).
-The default is /root\-anchors/root\-anchors.xml.
+.B \-x <path>
+The pathname to the root\-anchors.xml file on the server.
+(forms URL with \fI\%\-u\fP).
+The default is \fB/root\-anchors/root\-anchors.xml\fP\&.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-s \fIpath
-The pathname to the root\-anchors.p7s file on the server. (forms URL with \-u).
-The default is /root\-anchors/root\-anchors.p7s. This file has to be a PKCS7
-signature over the xml file, using the pem file (\-c) as trust anchor.
+.B \-s <path>
+The pathname to the root\-anchors.p7s file on the server.
+(forms URL with \fI\%\-u\fP).
+The default is \fB/root\-anchors/root\-anchors.p7s\fP\&.
+This file has to be a PKCS7 signature over the xml file, using the pem
+file (\fI\%\-c\fP) as trust anchor.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-n \fIname
-The emailAddress for the Subject of the signer's certificate from the p7s
-signature file. Only signatures from this name are allowed. default is
-dnssec@iana.org. If you pass "" then the emailAddress is not checked.
+.B \-n <name>
+The emailAddress for the Subject of the signer\(aqs certificate from the
+p7s signature file.
+Only signatures from this name are allowed.
+The default is \fBdnssec@iana.org\fP\&.
+If you pass \fB\(dq\(dq\fP then the emailAddress is not checked.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-4
-Use IPv4 for domain resolution and contacting the server on https. Default is
-to use IPv4 and IPv6 where appropriate.
+Use IPv4 for domain resolution and contacting the server on
+https.
+Default is to use IPv4 and IPv6 where appropriate.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-6
-Use IPv6 for domain resolution and contacting the server on https. Default is
-to use IPv4 and IPv6 where appropriate.
-.TP
-.B \-f \fIresolv.conf
-Use the given resolv.conf file. Not enabled by default, but you could try to
-pass /etc/resolv.conf on some systems. It contains the IP addresses of the
-recursive nameservers to use. However, since this tool could be used to
-bootstrap that very recursive nameserver, it would not be useful (since
-that server is not up yet, since we are bootstrapping it). It could be
-useful in a situation where you know an upstream cache is deployed (and
-running) and in captive portal situations.
-.TP
-.B \-r \fIroot.hints
-Use the given root.hints file (same syntax as the BIND and Unbound root hints
-file) to bootstrap domain resolution. By default a list of builtin root
-hints is used. Unbound\-anchor goes to the network itself for these roots,
-to resolve the server (\-u option) and to check the root DNSKEY records.
+Use IPv6 for domain resolution and contacting the server on https.
+Default is to use IPv4 and IPv6 where appropriate.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-f <resolv.conf>
+Use the given resolv.conf file.
+Not enabled by default, but you could try to pass
+\fB/etc/resolv.conf\fP on some systems.
+It contains the IP addresses of the recursive nameservers to use.
+However, since this tool could be used to bootstrap that very recursive
+nameserver, it would not be useful (since that server is not up yet,
+since we are bootstrapping it).
+It could be useful in a situation where you know an upstream cache is
+deployed (and running) and in captive portal situations.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-r <root.hints>
+Use the given root.hints file (same syntax as the BIND and Unbound root
+hints file) to bootstrap domain resolution.
+By default a list of builtin root hints is used.
+unbound\-anchor goes to the network itself for these roots, to resolve
+the server (\fI\%\-u\fP option) and to check the root DNSKEY records.
It does so, because the tool when used for bootstrapping the recursive
-resolver, cannot use that recursive resolver itself because it is bootstrapping
-that server.
+resolver, cannot use that recursive resolver itself because it is
+bootstrapping that server.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-R
-Allow fallback from \-f resolv.conf file to direct root servers query.
-It allows you to prefer local resolvers, but fallback automatically
-to direct root query if they do not respond or do not support DNSSEC.
+Allow fallback from \fI\%\-f\fP \fB<resolv.conf>\fP file to direct root
+servers query.
+It allows you to prefer local resolvers, but fallback automatically to
+direct root query if they do not respond or do not support DNSSEC.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-v
-More verbose. Once prints informational messages, multiple times may enable
-large debug amounts (such as full certificates or byte\-dumps of downloaded
-files). By default it prints almost nothing. It also prints nothing on
-errors by default; in that case the original root anchor file is simply
-left undisturbed, so that a recursive server can start right after it.
+More verbose.
+Once prints informational messages, multiple times may enable large
+debug amounts (such as full certificates or byte\-dumps of downloaded
+files).
+By default it prints almost nothing.
+It also prints nothing on errors by default; in that case the original
+root anchor file is simply left undisturbed, so that a recursive server
+can start right after it.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-C \fIunbound.conf
-Debug option to read unbound.conf into the resolver process used.
+.B \-C <unbound.conf>
+Debug option to read \fB<unbound.conf>\fP into the resolver process
+used.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-P \fIport
-Set the port number to use for the https connection. The default is 443.
+.B \-P <port>
+Set the port number to use for the https connection.
+The default is 443.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-F
-Debug option to force update of the root anchor through downloading the xml
-file and verifying it with the certificate. By default it first tries to
-update by contacting the DNS, which uses much less bandwidth, is much
-faster (200 msec not 2 sec), and is nicer to the deployed infrastructure.
-With this option, it still attempts to do so (and may verbosely tell you),
-but then ignores the result and goes on to use the xml fallback method.
+Debug option to force update of the root anchor through downloading the
+xml file and verifying it with the certificate.
+By default it first tries to update by contacting the DNS, which uses
+much less bandwidth, is much faster (200 msec not 2 sec), and is nicer
+to the deployed infrastructure.
+With this option, it still attempts to do so (and may verbosely tell
+you), but then ignores the result and goes on to use the xml fallback
+method.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-h
Show the version and commandline option help.
-.SH "EXIT CODE"
+.UNINDENT
+.SH EXIT CODE
+.sp
This tool exits with value 1 if the root anchor was updated using the
-certificate or if the builtin root-anchor was used. It exits with code
-0 if no update was necessary, if the update was possible with RFC5011
-tracking, or if an error occurred.
-.P
+certificate or if the builtin root\-anchor was used.
+It exits with code 0 if no update was necessary, if the update was possible
+with \fI\%RFC 5011\fP tracking, or if an error occurred.
+.sp
You can check the exit value in this manner:
+.INDENT 0.0
+.INDENT 3.5
+.sp
.nf
- unbound-anchor \-a "root.key" || logger "Please check root.key"
+.ft C
+unbound\-anchor \-a \(dqroot.key\(dq || logger \(dqPlease check root.key\(dq
+.ft P
.fi
+.UNINDENT
+.UNINDENT
+.sp
Or something more suitable for your operational environment.
-.SH "TRUST"
-The root keys and update certificate included in this tool
-are provided for convenience and under the terms of our
-license (see the LICENSE file in the source distribution or
-https://github.com/NLnetLabs/unbound/blob/master/LICENSE) and might be stale or
-not suitable to your purpose.
-.P
-By running "unbound\-anchor \-l" the keys and certificate that are
+.SH TRUST
+.sp
+The root keys and update certificate included in this tool are provided for
+convenience and under the terms of our license (see the LICENSE file in the
+source distribution or \fI\%https://github.com/NLnetLabs/unbound/blob/master/LICENSE\fP
+and might be stale or not suitable to your purpose.
+.sp
+By running \fI\%unbound\-anchor \-l\fP the keys and certificate that are
configured in the code are printed for your convenience.
-.P
-The build\-in configuration can be overridden by providing a root\-cert
-file and a rootkey file.
-.SH "FILES"
+.sp
+The built\-in configuration can be overridden by providing a root\-cert file and
+a rootkey file.
+.SH FILES
+.INDENT 0.0
.TP
-.I @UNBOUND_ROOTKEY_FILE@
-The root anchor file, updated with 5011 tracking, and read and written to.
+.B @UNBOUND_ROOTKEY_FILE@
+The root anchor file, updated with 5011 tracking, and read and written
+to.
The file is created if it does not exist.
.TP
-.I @UNBOUND_ROOTCERT_FILE@
-The trusted self\-signed certificate that is used to verify the downloaded
-DNSSEC root trust anchor. You can update it by fetching it from
-https://data.iana.org/root\-anchors/icannbundle.pem (and validate it).
+.B @UNBOUND_ROOTCERT_FILE@
+The trusted self\-signed certificate that is used to verify the
+downloaded DNSSEC root trust anchor.
+You can update it by fetching it from
+\fI\%https://data.iana.org/root\-anchors/icannbundle.pem\fP (and validate it).
If the file does not exist or is empty, a builtin version is used.
.TP
-.I https://data.iana.org/root\-anchors/root\-anchors.xml
+.B \fI\%https://data.iana.org/root\-anchors/root\-anchors.xml\fP
Source for the root key information.
.TP
-.I https://data.iana.org/root\-anchors/root\-anchors.p7s
+.B \fI\%https://data.iana.org/root\-anchors/root\-anchors.p7s\fP
Signature on the root key information.
-.SH "SEE ALSO"
-\fIunbound.conf\fR(5),
-\fIunbound\fR(8).
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fI\%unbound.conf(5)\fP,
+\fI\%unbound(8)\fP\&.
+.SH AUTHOR
+Unbound developers are mentioned in the CREDITS file in the distribution.
+.SH COPYRIGHT
+1999-2025, NLnet Labs
+.\" Generated by docutils manpage writer.
+.
--- /dev/null
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+.. program:: unbound-anchor
+
+unbound-anchor(8)
+=================
+
+Synopsis
+--------
+
+**unbound-anchor** [``opts``]
+
+Description
+-----------
+
+``unbound-anchor`` performs setup or update of the root trust anchor for DNSSEC
+validation.
+The program fetches the trust anchor with the method from :rfc:`7958` when
+regular :rfc:`5011` update fails to bring it up to date.
+It can be run (as root) from the commandline, or run as part of startup
+scripts.
+Before you start the :doc:`unbound(8)</manpages/unbound>` DNS server.
+
+Suggested usage:
+
+.. code-block:: text
+
+ # in the init scripts.
+ # provide or update the root anchor (if necessary)
+ unbound-anchor -a "@UNBOUND_ROOTKEY_FILE@"
+ # Please note usage of this root anchor is at your own risk
+ # and under the terms of our LICENSE (see source).
+ #
+ # start validating resolver
+ # the unbound.conf contains:
+ # auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@"
+ unbound -c unbound.conf
+
+This tool provides builtin default contents for the root anchor and root update
+certificate files.
+
+It tests if the root anchor file works, and if not, and an update is possible,
+attempts to update the root anchor using the root update certificate.
+It performs a https fetch of
+`root-anchors.xml <http://data.iana.org/root-anchors/root-anchors.xml>`__
+and checks the results (:rfc:`7958`); if all checks are successful, it updates
+the root anchor file.
+Otherwise the root anchor file is unchanged.
+It performs :rfc:`5011` tracking if the DNSSEC information available via the
+DNS makes that possible.
+
+It does not perform an update if the certificate is expired, if the network is
+down or other errors occur.
+
+The available options are:
+
+.. option:: -a <file>
+
+ The root anchor key file, that is read in and written out.
+ Default is :file:`@UNBOUND_ROOTKEY_FILE@`.
+ If the file does not exist, or is empty, a builtin root key is written
+ to it.
+
+.. option:: -c <file>
+
+ The root update certificate file, that is read in.
+ Default is :file:`@UNBOUND_ROOTCERT_FILE@`.
+ If the file does not exist, or is empty, a builtin certificate is used.
+
+.. option:: -l
+
+ List the builtin root key and builtin root update certificate on stdout.
+
+.. option:: -u <name>
+
+ The server name, it connects to ``https://name``.
+ Specify without ``https://`` prefix.
+ The default is ``"data.iana.org"``.
+ It connects to the port specified with :option:`-P`.
+ You can pass an IPv4 address or IPv6 address (no brackets) if you want.
+
+.. option:: -S
+
+ Do not use SNI for the HTTPS connection.
+ Default is to use SNI.
+
+.. option:: -b <address>
+
+ The source address to bind to for domain resolution and contacting the
+ server on https.
+ May be either an IPv4 address or IPv6 address (no brackets).
+
+.. option:: -x <path>
+
+ The pathname to the root-anchors.xml file on the server.
+ (forms URL with :option:`-u`).
+ The default is :file:`/root-anchors/root-anchors.xml`.
+
+.. option:: -s <path>
+
+ The pathname to the root-anchors.p7s file on the server.
+ (forms URL with :option:`-u`).
+ The default is :file:`/root-anchors/root-anchors.p7s`.
+ This file has to be a PKCS7 signature over the xml file, using the pem
+ file (:option:`-c`) as trust anchor.
+
+.. option:: -n <name>
+
+ The emailAddress for the Subject of the signer's certificate from the
+ p7s signature file.
+ Only signatures from this name are allowed.
+ The default is ``dnssec@iana.org``.
+ If you pass ``""`` then the emailAddress is not checked.
+
+.. option:: -4
+
+ Use IPv4 for domain resolution and contacting the server on
+ https.
+ Default is to use IPv4 and IPv6 where appropriate.
+
+.. option:: -6
+
+ Use IPv6 for domain resolution and contacting the server on https.
+ Default is to use IPv4 and IPv6 where appropriate.
+
+.. option:: -f <resolv.conf>
+
+ Use the given resolv.conf file.
+ Not enabled by default, but you could try to pass
+ :file:`/etc/resolv.conf` on some systems.
+ It contains the IP addresses of the recursive nameservers to use.
+ However, since this tool could be used to bootstrap that very recursive
+ nameserver, it would not be useful (since that server is not up yet,
+ since we are bootstrapping it).
+ It could be useful in a situation where you know an upstream cache is
+ deployed (and running) and in captive portal situations.
+
+.. option:: -r <root.hints>
+
+ Use the given root.hints file (same syntax as the BIND and Unbound root
+ hints file) to bootstrap domain resolution.
+ By default a list of builtin root hints is used.
+ unbound-anchor goes to the network itself for these roots, to resolve
+ the server (:option:`-u` option) and to check the root DNSKEY records.
+ It does so, because the tool when used for bootstrapping the recursive
+ resolver, cannot use that recursive resolver itself because it is
+ bootstrapping that server.
+
+.. option:: -R
+
+ Allow fallback from :option:`-f` ``<resolv.conf>`` file to direct root
+ servers query.
+ It allows you to prefer local resolvers, but fallback automatically to
+ direct root query if they do not respond or do not support DNSSEC.
+
+.. option:: -v
+
+ More verbose.
+ Once prints informational messages, multiple times may enable large
+ debug amounts (such as full certificates or byte-dumps of downloaded
+ files).
+ By default it prints almost nothing.
+ It also prints nothing on errors by default; in that case the original
+ root anchor file is simply left undisturbed, so that a recursive server
+ can start right after it.
+
+.. option:: -C <unbound.conf>
+
+ Debug option to read :file:`<unbound.conf>` into the resolver process
+ used.
+
+.. option:: -P <port>
+
+ Set the port number to use for the https connection.
+ The default is 443.
+
+.. option:: -F
+
+ Debug option to force update of the root anchor through downloading the
+ xml file and verifying it with the certificate.
+ By default it first tries to update by contacting the DNS, which uses
+ much less bandwidth, is much faster (200 msec not 2 sec), and is nicer
+ to the deployed infrastructure.
+ With this option, it still attempts to do so (and may verbosely tell
+ you), but then ignores the result and goes on to use the xml fallback
+ method.
+
+.. option:: -h
+
+ Show the version and commandline option help.
+
+Exit Code
+---------
+
+This tool exits with value 1 if the root anchor was updated using the
+certificate or if the builtin root-anchor was used.
+It exits with code 0 if no update was necessary, if the update was possible
+with :rfc:`5011` tracking, or if an error occurred.
+
+You can check the exit value in this manner:
+
+.. code-block:: text
+
+ unbound-anchor -a "root.key" || logger "Please check root.key"
+
+Or something more suitable for your operational environment.
+
+Trust
+-----
+
+The root keys and update certificate included in this tool are provided for
+convenience and under the terms of our license (see the LICENSE file in the
+source distribution or https://github.com/NLnetLabs/unbound/blob/master/LICENSE
+and might be stale or not suitable to your purpose.
+
+By running :option:`unbound-anchor -l` the keys and certificate that are
+configured in the code are printed for your convenience.
+
+The built-in configuration can be overridden by providing a root-cert file and
+a rootkey file.
+
+Files
+-----
+
+@UNBOUND_ROOTKEY_FILE@
+ The root anchor file, updated with 5011 tracking, and read and written
+ to.
+ The file is created if it does not exist.
+
+@UNBOUND_ROOTCERT_FILE@
+ The trusted self-signed certificate that is used to verify the
+ downloaded DNSSEC root trust anchor.
+ You can update it by fetching it from
+ https://data.iana.org/root-anchors/icannbundle.pem (and validate it).
+ If the file does not exist or is empty, a builtin version is used.
+
+https://data.iana.org/root-anchors/root-anchors.xml
+ Source for the root key information.
+
+https://data.iana.org/root-anchors/root-anchors.p7s
+ Signature on the root key information.
+
+See Also
+--------
+
+:doc:`unbound.conf(5)</manpages/unbound.conf>`,
+:doc:`unbound(8)</manpages/unbound>`.
-.TH "unbound-checkconf" "8" "@date@" "NLnet Labs" "unbound @version@"
-.\"
-.\" unbound-checkconf.8 -- unbound configuration checker manual
-.\"
-.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
-.\"
-.\" See LICENSE for the license.
-.\"
-.\"
-.SH "NAME"
-unbound\-checkconf
-\- Check Unbound configuration file for errors.
-.SH "SYNOPSIS"
-.B unbound\-checkconf
-.RB [ \-h ]
-.RB [ \-f ]
-.RB [ \-q ]
-.RB [ \-o
-.IR option ]
-.RI [ cfgfile ]
-.SH "DESCRIPTION"
-.B Unbound\-checkconf
-checks the configuration file for the
-\fIunbound\fR(8)
-DNS resolver for syntax and other errors.
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "UNBOUND-CHECKCONF" "8" "@date@" "@version@" "Unbound"
+.SH NAME
+unbound-checkconf \- Check Unbound @version@ configuration file for errors.
+.SH SYNOPSIS
+.sp
+\fBunbound\-checkconf\fP [\fB\-hf\fP] [\fB\-o option\fP] [cfgfile]
+.SH DESCRIPTION
+.sp
+\fBunbound\-checkconf\fP checks the configuration file for the
+\fI\%unbound(8)\fP DNS resolver for syntax and other errors.
The config file syntax is described in
-\fIunbound.conf\fR(5).
-.P
+\fI\%unbound.conf(5)\fP\&.
+.sp
The available options are:
+.INDENT 0.0
.TP
.B \-h
Show the version and commandline option help.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-f
-Print full pathname, with chroot applied to it. Use with the \-o option.
-.TP
-.B \-o\fI option
-If given, after checking the config file the value of this option is
-printed to stdout. For "" (disabled) options an empty line is printed.
+Print full pathname, with chroot applied to it.
+Use with the \fI\%\-o\fP option.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-q
Make the operation quiet, suppress output on success.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-o <option>
+If given, after checking the config file the value of this option is
+printed to stdout.
+For \fB\(dq\(dq\fP (disabled) options an empty line is printed.
+.UNINDENT
+.INDENT 0.0
.TP
-.I cfgfile
-The config file to read with settings for Unbound. It is checked.
+.B cfgfile
+The config file to read with settings for Unbound.
+It is checked.
If omitted, the config file at the default location is checked.
-.SH "EXIT CODE"
-The unbound\-checkconf program exits with status code 1 on error,
-0 for a correct config file.
-.SH "FILES"
+.UNINDENT
+.SH EXIT CODE
+.sp
+The \fBunbound\-checkconf\fP program exits with status code 1 on error, 0 for a
+correct config file.
+.SH FILES
+.INDENT 0.0
.TP
-.I @ub_conf_file@
+.B @ub_conf_file@
Unbound configuration file.
-.SH "SEE ALSO"
-\fIunbound.conf\fR(5),
-\fIunbound\fR(8).
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fI\%unbound.conf(5)\fP,
+\fI\%unbound(8)\fP\&.
+.SH AUTHOR
+Unbound developers are mentioned in the CREDITS file in the distribution.
+.SH COPYRIGHT
+1999-2025, NLnet Labs
+.\" Generated by docutils manpage writer.
+.
--- /dev/null
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+.. program:: unbound-checkconf
+
+unbound-checkconf(8)
+====================
+
+Synopsis
+--------
+
+**unbound-checkconf** [``-hf``] [``-o option``] [cfgfile]
+
+Description
+-----------
+
+``unbound-checkconf`` checks the configuration file for the
+:doc:`unbound(8)</manpages/unbound>` DNS resolver for syntax and other errors.
+The config file syntax is described in
+:doc:`unbound.conf(5)</manpages/unbound.conf>`.
+
+The available options are:
+
+.. option:: -h
+
+ Show the version and commandline option help.
+
+.. option:: -f
+
+ Print full pathname, with chroot applied to it.
+ Use with the :option:`-o` option.
+
+.. option:: -q
+
+ Make the operation quiet, suppress output on success.
+
+.. option:: -o <option>
+
+ If given, after checking the config file the value of this option is
+ printed to stdout.
+ For ``""`` (disabled) options an empty line is printed.
+
+.. option:: cfgfile
+
+ The config file to read with settings for Unbound.
+ It is checked.
+ If omitted, the config file at the default location is checked.
+
+Exit Code
+---------
+
+The ``unbound-checkconf`` program exits with status code 1 on error, 0 for a
+correct config file.
+
+Files
+-----
+
+@ub_conf_file@
+ Unbound configuration file.
+
+See Also
+--------
+
+:doc:`unbound.conf(5)</manpages/unbound.conf>`,
+:doc:`unbound(8)</manpages/unbound>`.
-.TH "unbound-control" "8" "@date@" "NLnet Labs" "unbound @version@"
-.\"
-.\" unbound-control.8 -- unbound remote control manual
-.\"
-.\" Copyright (c) 2008, NLnet Labs. All rights reserved.
-.\"
-.\" See LICENSE for the license.
-.\"
-.\"
-.SH "NAME"
-.B unbound\-control,
-.B unbound\-control\-setup
-\- Unbound remote server control utility.
-.SH "SYNOPSIS"
-.B unbound\-control
-.RB [ \-hq ]
-.RB [ \-c
-.IR cfgfile ]
-.RB [ \-s
-.IR server ]
-.IR command
-.SH "DESCRIPTION"
-.B Unbound\-control
-performs remote administration on the \fIunbound\fR(8) DNS server.
-It reads the configuration file, contacts the Unbound server over SSL
-sends the command and displays the result.
-.P
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "UNBOUND-CONTROL" "8" "@date@" "@version@" "Unbound"
+.SH NAME
+unbound-control \- Unbound @version@ remote server control utility.
+.SH SYNOPSIS
+.sp
+\fBunbound\-control\fP [\fB\-hq\fP] [\fB\-c cfgfile\fP] [\fB\-s server\fP] command
+.SH DESCRIPTION
+.sp
+\fBunbound\-control\fP performs remote administration on the
+\fI\%unbound(8)\fP DNS server.
+It reads the configuration file, contacts the Unbound server over TLS sends the
+command and displays the result.
+.sp
The available options are:
+.INDENT 0.0
.TP
.B \-h
Show the version and commandline option help.
-.TP
-.B \-c \fIcfgfile
-The config file to read with settings. If not given the default
-config file @ub_conf_file@ is used.
-.TP
-.B \-s \fIserver[@port]
-IPv4 or IPv6 address of the server to contact. If not given, the
-address is read from the config file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-c <cfgfile>
+The config file to read with settings.
+If not given the default config file
+\fB@ub_conf_file@\fP is used.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-s <server[@port]>
+IPv4 or IPv6 address of the server to contact.
+If not given, the address is read from the config file.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-q
-quiet, if the option is given it does not print anything if it works ok.
-.SH "COMMANDS"
+Quiet, if the option is given it does not print anything if it works ok.
+.UNINDENT
+.SH COMMANDS
+.sp
There are several commands that the server understands.
-.TP
-.B start
-Start the server. Simply execs \fIunbound\fR(8). The Unbound executable
-is searched for in the \fBPATH\fR set in the environment. It is started
-with the config file specified using \fI\-c\fR or the default config file.
-.TP
-.B stop
-Stop the server. The server daemon exits.
-.TP
-.B reload
-Reload the server. This flushes the cache and reads the config file fresh.
-.TP
-.B reload_keep_cache
+.INDENT 0.0
+.TP
+.B start
+Start the server.
+Simply execs \fI\%unbound(8)\fP\&.
+The \fBunbound\fP executable is searched for in the \fBPATH\fP set in the
+environment.
+It is started with the config file specified using \fI\%\-c\fP or the
+default config file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stop
+Stop the server.
+The server daemon exits.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B reload
+Reload the server.
+This flushes the cache and reads the config file fresh.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B reload_keep_cache
Reload the server but try to keep the RRset and message cache if
(re)configuration allows for it.
-That means the caches sizes and the number of threads must not change between
-reloads.
+That means the caches sizes and the number of threads must not change
+between reloads.
+.UNINDENT
+.INDENT 0.0
.TP
-.B fast_reload \fR[\fI+dpv\fR]
+.B fast_reload [\fB+dpv\fP]
Reload the server, but keep downtime to a minimum, so that user queries
-keep seeing service. This needs the code compiled with threads. The config
-is loaded in a thread, and prepared, then it briefly pauses the existing
-server and updates config options. The intent is that the pause does not
-impact the service of user queries. The cache is kept. Also user queries
-worked on are kept and continue, but with the new config options.
-.IP
+keep seeing service.
+This needs the code compiled with threads.
+The config is loaded in a thread, and prepared, then it briefly pauses the
+existing server and updates config options.
+The intent is that the pause does not impact the service of user queries.
+The cache is kept.
+Also user queries worked on are kept and continue, but with the new config
+options.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
This command is experimental at this time.
-.IP
+.UNINDENT
+.UNINDENT
+.sp
The amount of temporal memory needed during a fast_reload is twice the
amount needed for configuration.
-This is because Unbound temporarily needs to store both current configuration
-values and new ones while trying to fast_reload.
+This is because Unbound temporarily needs to store both current
+configuration values and new ones while trying to fast_reload.
Zones loaded from disk (authority zones and RPZ zones) are included in such
memory needs.
-.IP
+.sp
Options that can be changed are for
-forwards,
-stubs,
-views,
-authority zones,
-RPZ zones and
-local zones.
-.IP
+\fI\%forwards\fP,
+\fI\%stubs\fP,
+\fI\%views\fP,
+\fI\%authority zones\fP,
+\fI\%RPZ zones\fP and
+\fI\%local zones\fP\&.
+.sp
Also
-access-control and similar options,
-interface-action and similar options and
-tcp-connection-limit.
+\fI\%access\-control\fP and similar options,
+\fI\%interface\-action\fP and similar
+options and
+\fI\%tcp\-connection\-limit\fP\&.
It can reload some
-define-tag
+\fI\%define\-tag\fP
changes, more on that below.
Further options include
-insecure-lan-zones,
-domain-insecure,
-trust-anchor-file,
-trust-anchor,
-trusted-keys-file,
-auto-trust-anchor-file,
-edns-client-string,
+\fI\%insecure\-lan\-zones\fP,
+\fI\%domain\-insecure\fP,
+\fI\%trust\-anchor\-file\fP,
+\fI\%trust\-anchor\fP,
+\fI\%trusted\-keys\-file\fP,
+\fI\%auto\-trust\-anchor\-file\fP,
+\fI\%edns\-client\-string\fP,
ipset,
-log-identity,
-infra-cache-numhosts,
-msg-cache-size,
-rrset-cache-size,
-key-cache-size,
-ratelimit-size,
-neg-cache-size,
-num-queries-per-thread,
-jostle-timeout,
-use-caps-for-id,
-unwanted-reply-threshold,
-tls-use-sni,
-outgoing-tcp-mss,
-ip-dscp,
-max-reuse-tcp-queries,
-tcp-reuse-timeout,
-tcp-auth-query-timeout,
-delay-close.
-.IP
+\fI\%log\-identity\fP,
+\fI\%infra\-cache\-numhosts\fP,
+\fI\%msg\-cache\-size\fP,
+\fI\%rrset\-cache\-size\fP,
+\fI\%key\-cache\-size\fP,
+\fI\%ratelimit\-size\fP,
+\fI\%neg\-cache\-size\fP,
+\fI\%num\-queries\-per\-thread\fP,
+\fI\%jostle\-timeout\fP,
+\fI\%use\-caps\-for\-id\fP,
+\fI\%unwanted\-reply\-threshold\fP,
+\fI\%tls\-use\-sni\fP,
+\fI\%outgoing\-tcp\-mss\fP,
+\fI\%ip\-dscp\fP,
+\fI\%max\-reuse\-tcp\-queries\fP,
+\fI\%tcp\-reuse\-timeout\fP,
+\fI\%tcp\-auth\-query\-timeout\fP,
+\fI\%delay\-close\fP\&.
+.sp
It does not work with
-interface and
-outgoing-interface changes,
+\fI\%interface\fP and
+\fI\%outgoing\-interface\fP changes,
also not with
-remote control,
-outgoing-port-permit,
-outgoing-port-avoid,
-msg-buffer-size,
-any **\*-slabs** options and
-statistics-interval changes.
-.IP
-For dnstap these options can be changed:
-dnstap-log-resolver-query-messages,
-dnstap-log-resolver-response-messages,
-dnstap-log-client-query-messages,
-dnstap-log-client-response-messages,
-dnstap-log-forwarder-query-messages and
-dnstap-log-forwarder-response-messages.
-.IP
+\fI\%remote control\fP,
+\fI\%outgoing\-port\-permit\fP,
+\fI\%outgoing\-port\-avoid\fP,
+\fI\%msg\-buffer\-size\fP,
+any \fB*\-slabs\fP options and
+\fI\%statistics\-interval\fP changes.
+.sp
+For \fI\%dnstap\fP these options can be changed:
+\fI\%dnstap\-log\-resolver\-query\-messages\fP,
+\fI\%dnstap\-log\-resolver\-response\-messages\fP,
+\fI\%dnstap\-log\-client\-query\-messages\fP,
+\fI\%dnstap\-log\-client\-response\-messages\fP,
+\fI\%dnstap\-log\-forwarder\-query\-messages\fP and
+\fI\%dnstap\-log\-forwarder\-response\-messages\fP\&.
+.sp
It does not work with these options:
-dnstap-enable,
-dnstap-bidirectional,
-dnstap-socket-path,
-dnstap-ip,
-dnstap-tls,
-dnstap-tls-server-name,
-dnstap-tls-cert-bundle,
-dnstap-tls-client-key-file and
-dnstap-tls-client-cert-file.
-.IP
+\fI\%dnstap\-enable\fP,
+\fI\%dnstap\-bidirectional\fP,
+\fI\%dnstap\-socket\-path\fP,
+\fI\%dnstap\-ip\fP,
+\fI\%dnstap\-tls\fP,
+\fI\%dnstap\-tls\-server\-name\fP,
+\fI\%dnstap\-tls\-cert\-bundle\fP,
+\fI\%dnstap\-tls\-client\-key\-file\fP and
+\fI\%dnstap\-tls\-client\-cert\-file\fP\&.
+.sp
The options
-dnstap-send-identity,
-dnstap-send-version,
-dnstap-identity, and
-dnstap-version can be loaded
-when ``+p`` is not used.
-.IP
-The '+v' option makes the output verbose which includes the time it took to do
-the reload.
-With '+vv' it is more verbose which includes the amount of memory that was
-allocated temporarily to perform the reload; this amount of memory can be big
-if the config has large contents.
-In the timing output the 'reload' time is the time during which the server was
-paused.
-.IP
-The '+p' option makes the reload not pause threads, they keep running.
+\fI\%dnstap\-send\-identity\fP,
+\fI\%dnstap\-send\-version\fP,
+\fI\%dnstap\-identity\fP, and
+\fI\%dnstap\-version\fP can be loaded
+when \fB+p\fP is not used.
+.sp
+The \fB+v\fP option makes the output verbose which includes the time it took
+to do the reload.
+With \fB+vv\fP it is more verbose which includes the amount of memory that
+was allocated temporarily to perform the reload; this amount of memory can
+be big if the config has large contents.
+In the timing output the \(aqreload\(aq time is the time during which the server
+was paused.
+.sp
+The \fB+p\fP option makes the reload not pause threads, they keep running.
Locks are acquired, but items are updated in sequence, so it is possible
for threads to see an inconsistent state with some options from the old
and some options from the new config, such as cache TTL parameters from the
-old config and forwards from the new config. The stubs and forwards are
-updated at the same time, so that they are viewed consistently, either old
-or new values together. The option makes the reload time take eg. 3
-microseconds instead of 0.3 milliseconds during which the worker threads are
-interrupted. So, the interruption is much shorter, at the expense of some
-inconsistency. After the reload itself, every worker thread is briefly
-contacted to make them release resources, this makes the delete timing
-a little longer, and takes up time from the remote control servicing
-worker thread.
-.IP
-With the nopause option, the reload does not work to reload some options,
-that fast reload works on without the nopause option: val-bogus-ttl,
-val-override-date, val-sig-skew-min, val-sig-skew-max, val-max-restart,
-val-nsec3-keysize-iterations, target-fetch-policy, outbound-msg-retry,
-max-sent-count, max-query-restarts, do-not-query-address,
-do-not-query-localhost, private-address, private-domain, caps-exempt,
-nat64-prefix, do-nat64, infra-host-ttl, infra-keep-probing, ratelimit,
-ip-ratelimit, ip-ratelimit-cookie, wait-limit-netblock,
-wait-limit-cookie-netblock, ratelimit-below-domain, ratelimit-for-domain.
-.IP
-The '+d' option makes the reload drop queries that the worker threads are
-working on. This is like flush_requestlist. Without it the queries are kept
-so that users keep getting answers for those queries that are currently
-processed. The drop makes it so that queries during the life time of the
+old config and forwards from the new config.
+The stubs and forwards are updated at the same time, so that they are
+viewed consistently, either old or new values together.
+The option makes the reload time take eg. 3 microseconds instead of 0.3
+milliseconds during which the worker threads are interrupted.
+So, the interruption is much shorter, at the expense of some inconsistency.
+After the reload itself, every worker thread is briefly contacted to make
+them release resources, this makes the delete timing a little longer, and
+takes up time from the remote control servicing worker thread.
+.sp
+With the nopause option (\fB+p\fP), the reload does not work to reload some
+options, that fast reload works on without the nopause option:
+\fI\%val\-bogus\-ttl\fP,
+\fI\%val\-override\-date\fP,
+\fI\%val\-sig\-skew\-min\fP,
+\fI\%val\-sig\-skew\-max\fP,
+\fI\%val\-max\-restart\fP,
+\fI\%val\-nsec3\-keysize\-iterations\fP,
+\fI\%target\-fetch\-policy\fP,
+\fI\%outbound\-msg\-retry\fP,
+\fI\%max\-sent\-count\fP,
+\fI\%max\-query\-restarts\fP,
+\fI\%do\-not\-query\-address\fP,
+\fI\%do\-not\-query\-localhost\fP,
+\fI\%private\-address\fP,
+\fI\%private\-domain\fP,
+\fI\%caps\-exempt\fP,
+\fI\%nat64\-prefix\fP,
+\fI\%do\-nat64\fP,
+\fI\%infra\-host\-ttl\fP,
+\fI\%infra\-keep\-probing\fP,
+\fI\%ratelimit\fP,
+\fI\%ip\-ratelimit\fP,
+\fI\%ip\-ratelimit\-cookie\fP,
+\fI\%wait\-limit\-netblock\fP,
+\fI\%wait\-limit\-cookie\-netblock\fP,
+\fI\%ratelimit\-below\-domain\fP,
+\fI\%ratelimit\-for\-domain\fP\&.
+.sp
+The \fB+d\fP option makes the reload drop queries that the worker threads are
+working on.
+This is like
+\fI\%flush_requestlist\fP\&.
+Without it the queries are kept so that users keep getting answers for
+those queries that are currently processed.
+The drop makes it so that queries during the life time of the
query processing see only old, or only new config options.
-.IP
-When there are changes to the config tags, from the \fBdefine\-tag\fR option,
-then the '+d' option is implicitly turned on with a warning printout, and
+.sp
+When there are changes to the config tags, from the
+\fI\%define\-tag\fP option,
+then the \fB+d\fP option is implicitly turned on with a warning printout, and
queries are dropped.
This is to stop references to the old tag information, by the old
-queries. If the number of tags is increased in the newly loaded config, by
-adding tags at the end, then the implicit '+d' option is not needed.
-.IP
+queries.
+If the number of tags is increased in the newly loaded config, by
+adding tags at the end, then the implicit \fB+d\fP option is not needed.
+.sp
For response ip, that is actions associated with IP addresses, and perhaps
intersected with access control tag and action information, those settings
are stored with a query when it comes in based on its source IP address.
The old information is kept with the query until the queries are done.
-This is gone when those queries are resolved and finished, or it is possible
-to flush the requestlist with '+d'.
-.TP
-.B verbosity \fInumber
-Change verbosity value for logging. Same values as \fBverbosity\fR keyword in
-\fIunbound.conf\fR(5). This new setting lasts until the server is issued
-a reload (taken from config file again), or the next verbosity control command.
-.TP
-.B log_reopen
-Reopen the logfile, close and open it. Useful for logrotation to make the
-daemon release the file it is logging to. If you are using syslog it will
-attempt to close and open the syslog (which may not work if chrooted).
-.TP
-.B stats
-Print statistics. Resets the internal counters to zero, this can be
-controlled using the \fBstatistics\-cumulative\fR config statement.
-Statistics are printed with one [name]: [value] per line.
-.TP
-.B stats_noreset
-Peek at statistics. Prints them like the \fBstats\fR command does, but does not
-reset the internal counters to zero.
-.TP
-.B status
-Display server status. Exit code 3 if not running (the connection to the
-port is refused), 1 on error, 0 if running.
-.TP
-.B local_zone \fIname\fR \fItype
-Add new local zone with name and type. Like \fBlocal\-zone\fR config statement.
+This is gone when those queries are resolved and finished, or it is
+possible to flush the requestlist with \fB+d\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B verbosity \fInumber\fP
+Change verbosity value for logging.
+Same values as the \fBverbosity:\fP keyword in
+\fI\%unbound.conf(5)\fP\&.
+This new setting lasts until the server is issued a reload (taken from
+config file again), or the next verbosity control command.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B log_reopen
+Reopen the logfile, close and open it.
+Useful for logrotation to make the daemon release the file it is logging
+to.
+If you are using syslog it will attempt to close and open the syslog (which
+may not work if chrooted).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stats
+Print statistics.
+Resets the internal counters to zero, this can be controlled using the
+\fBstatistics\-cumulative:\fP config statement.
+Statistics are printed with one \fB[name]: [value]\fP per line.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stats_noreset
+Peek at statistics.
+Prints them like the stats command does, but does not reset the internal
+counters to zero.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B status
+Display server status.
+Exit code 3 if not running (the connection to the port is refused), 1 on
+error, 0 if running.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local_zone \fIname type\fP
+Add new local zone with name and type.
+Like local\-zone config statement.
If the zone already exists, the type is changed to the given argument.
-.TP
-.B local_zone_remove \fIname
-Remove the local zone with the given name. Removes all local data inside
-it. If the zone does not exist, the command succeeds.
-.TP
-.B local_data \fIRR data...
-Add new local data, the given resource record. Like \fBlocal\-data\fR
-config statement, except for when no covering zone exists. In that case
-this remote control command creates a transparent zone with the same
-name as this record.
-.TP
-.B local_data_remove \fIname
-Remove all RR data from local name. If the name already has no items,
-nothing happens. Often results in NXDOMAIN for the name (in a static zone),
-but if the name has become an empty nonterminal (there is still data in
-domain names below the removed name), NOERROR nodata answers are the
-result for that name.
-.TP
-.B local_zones
-Add local zones read from stdin of unbound\-control. Input is read per line,
-with name space type on a line. For bulk additions.
-.TP
-.B local_zones_remove
-Remove local zones read from stdin of unbound\-control. Input is one name per
-line. For bulk removals.
-.TP
-.B local_datas
-Add local data RRs read from stdin of unbound\-control. Input is one RR per
-line. For bulk additions.
-.TP
-.B local_datas_remove
-Remove local data RRs read from stdin of unbound\-control. Input is one name per
-line. For bulk removals.
-.TP
-.B dump_cache
-The content of the cache is printed in a text format to stdout.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local_zone_remove \fIname\fP
+Remove the local zone with the given name.
+Removes all local data inside it.
+If the zone does not exist, the command succeeds.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local_data \fIRR data...\fP
+Add new local data, the given resource record.
+Like \fBlocal\-data:\fP keyword, except for when no covering zone exists.
+In that case this remote control command creates a transparent zone with
+the same name as this record.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local_data_remove \fIname\fP
+Remove all RR data from local name.
+If the name already has no items, nothing happens.
+Often results in NXDOMAIN for the name (in a static zone), but if the name
+has become an empty nonterminal (there is still data in domain names below
+the removed name), NOERROR nodata answers are the result for that name.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local_zones
+Add local zones read from stdin of unbound\-control.
+Input is read per line, with name space type on a line.
+For bulk additions.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local_zones_remove
+Remove local zones read from stdin of unbound\-control.
+Input is one name per line.
+For bulk removals.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local_datas
+Add local data RRs read from stdin of unbound\-control.
+Input is one RR per line.
+For bulk additions.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local_datas_remove
+Remove local data RRs read from stdin of unbound\-control.
+Input is one name per line.
+For bulk removals.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dump_cache
+The contents of the cache is printed in a text format to stdout.
You can redirect it to a file to store the cache in a file.
-Not supported in remote Unbounds in multi-process operation.
+Not supported in remote Unbounds in multi\-process operation.
+.UNINDENT
+.INDENT 0.0
.TP
-.B load_cache
-The content of the cache is loaded from stdin.
+.B load_cache
+The contents of the cache is loaded from stdin.
Uses the same format as dump_cache uses.
Loading the cache with old, or wrong data can result in old or wrong data
returned to clients.
Loading data into the cache in this way is supported in order to aid with
debugging.
-Not supported in remote Unbounds in multi-process operation.
-.TP
-.B lookup \fIname
-Print to stdout the name servers that would be used to look up the
-name specified.
-.TP
-.B flush \fR[\fI+c\fR] \fIname
-Remove the name from the cache. Removes the types
-A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV, NAPTR, SVCB and HTTPS.
-Because that is fast to do. Other record types can be removed using
-.B flush_type
-or
-.B flush_zone\fR.
-.IP
-The '+c' option removes the items also from the cachedb cache. If
-cachedb is in use.
-.TP
-.B flush_type \fR[\fI+c\fR] \fIname\fR \fItype
+Not supported in remote Unbounds in multi\-process operation.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B lookup \fIname\fP
+Print to stdout the name servers that would be used to look up the name
+specified.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B flush [\fB+c\fP] \fIname\fP
+Remove the name from the cache.
+Removes the types A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV, NAPTR,
+SVCB and HTTPS.
+Because that is fast to do.
+Other record types can be removed using \fBflush_type\fP or \fBflush_zone\fP\&.
+.sp
+The \fB+c\fP option removes the items also from the cachedb cache.
+If cachedb is in use.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B flush_type [\fB+c\fP] \fIname type\fP
Remove the name, type information from the cache.
+.sp
+The \fB+c\fP option removes the items also from the cachedb cache.
+If cachedb is in use.
+.UNINDENT
+.INDENT 0.0
.TP
-.B flush_zone \fR[\fI+c\fR] \fIname
+.B flush_zone [\fB+c\fP] name
Remove all information at or below the name from the cache.
-The rrsets and key entries are removed so that new lookups will be performed.
+The rrsets and key entries are removed so that new lookups will be
+performed.
This needs to walk and inspect the entire cache, and is a slow operation.
The entries are set to expired in the implementation of this command (so,
-with serve\-expired enabled, it'll serve that information but schedule a
+with serve\-expired enabled, it\(aqll serve that information but schedule a
prefetch for new information).
+.sp
+The \fB+c\fP option removes the items also from the cachedb cache.
+If cachedb is in use.
+.UNINDENT
+.INDENT 0.0
.TP
-.B flush_bogus \fR[\fI+c\fR]
+.B flush_bogus [\fB+c\fP]
Remove all bogus data from the cache.
-.TP
-.B flush_negative \fR[\fI+c\fR]
-Remove all negative data from the cache. This is nxdomain answers,
-nodata answers and servfail answers. Also removes bad key entries
-(which could be due to failed lookups) from the dnssec key cache, and
-iterator last-resort lookup failures from the rrset cache.
-.TP
-.B flush_stats
+.sp
+The \fB+c\fP option removes the items also from the cachedb cache.
+If cachedb is in use.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B flush_negative [\fB+c\fP]
+Remove all negative data from the cache.
+This is nxdomain answers, nodata answers and servfail answers.
+Also removes bad key entries (which could be due to failed lookups) from
+the dnssec key cache, and iterator last\-resort lookup failures from the
+rrset cache.
+.sp
+The \fB+c\fP option removes the items also from the cachedb cache.
+If cachedb is in use.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B flush_stats
Reset statistics to zero.
-.TP
-.B flush_requestlist
-Drop the queries that are worked on. Stops working on the queries that the
-server is working on now. The cache is unaffected. No reply is sent for
-those queries, probably making those users request again later.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B flush_requestlist
+Drop the queries that are worked on.
+Stops working on the queries that the server is working on now.
+The cache is unaffected.
+No reply is sent for those queries, probably making those users request
+again later.
Useful to make the server restart working on queries with new settings,
such as a higher verbosity level.
-.TP
-.B dump_requestlist
-Show what is worked on. Prints all queries that the server is currently
-working on. Prints the time that users have been waiting. For internal
-requests, no time is printed. And then prints out the module status.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dump_requestlist
+Show what is worked on.
+Prints all queries that the server is currently working on.
+Prints the time that users have been waiting.
+For internal requests, no time is printed.
+And then prints out the module status.
This prints the queries from the first thread, and not queries that are
being serviced from other threads.
-.TP
-.B flush_infra \fIall|IP
-If all then entire infra cache is emptied. If a specific IP address, the
-entry for that address is removed from the cache. It contains EDNS, ping
-and lameness data.
-.TP
-.B dump_infra
+.UNINDENT
+.INDENT 0.0
+.TP
+.B flush_infra \fIall|IP\fP
+If all then entire infra cache is emptied.
+If a specific IP address, the entry for that address is removed from the
+cache.
+It contains EDNS, ping and lameness data.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dump_infra
Show the contents of the infra cache.
-.TP
-.B set_option \fIopt: val
-Set the option to the given value without a reload. The cache is
-therefore not flushed. The option must end with a ':' and whitespace
-must be between the option and the value. Some values may not have an
-effect if set this way, the new values are not written to the config file,
-not all options are supported. This is different from the set_option call
-in libunbound, where all values work because Unbound has not been initialized.
-.IP
+.UNINDENT
+.INDENT 0.0
+.TP
+.B set_option \fIopt: val\fP
+Set the option to the given value without a reload.
+The cache is therefore not flushed.
+The option must end with a \fB\(aq:\(aq\fP and whitespace must be between the
+option and the value.
+Some values may not have an effect if set this way, the new values are not
+written to the config file, not all options are supported.
+This is different from the set_option call in libunbound, where all values
+work because Unbound has not been initialized.
+.sp
The values that work are: statistics\-interval, statistics\-cumulative,
-do\-not\-query\-localhost, harden\-short\-bufsize, harden\-large\-queries,
+do\-not\-query\-localhost, harden\-short\-bufsize, harden\-large\-queries,
harden\-glue, harden\-dnssec\-stripped, harden\-below\-nxdomain,
-harden\-referral\-path, prefetch, prefetch\-key, log\-queries,
-hide\-identity, hide\-version, identity, version, val\-log\-level,
-val\-log\-squelch, ignore\-cd\-flag, add\-holddown, del\-holddown,
-keep\-missing, tcp\-upstream, ssl\-upstream, max\-udp\-size, ratelimit,
-ip\-ratelimit, cache\-max\-ttl, cache\-min\-ttl, cache\-max\-negative\-ttl.
-.TP
-.B get_option \fIopt
-Get the value of the option. Give the option name without a trailing ':'.
-The value is printed. If the value is "", nothing is printed
-and the connection closes. On error 'error ...' is printed (it gives
-a syntax error on unknown option). For some options a list of values,
-one on each line, is printed. The options are shown from the config file
-as modified with set_option. For some options an override may have been
-taken that does not show up with this command, not results from e.g. the
-verbosity and forward control commands. Not all options work, see list_stubs,
-list_forwards, list_local_zones and list_local_data for those.
-.TP
-.B list_stubs
-List the stub zones in use. These are printed one by one to the output.
+harden\-referral\-path, prefetch, prefetch\-key, log\-queries, hide\-identity,
+hide\-version, identity, version, val\-log\-level, val\-log\-squelch,
+ignore\-cd\-flag, add\-holddown, del\-holddown, keep\-missing, tcp\-upstream,
+ssl\-upstream, max\-udp\-size, ratelimit, ip\-ratelimit, cache\-max\-ttl,
+cache\-min\-ttl, cache\-max\-negative\-ttl.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B get_option \fIopt\fP
+Get the value of the option.
+Give the option name without a trailing \fB\(aq:\(aq\fP\&.
+The value is printed.
+If the value is \fB\(dq\(dq\fP, nothing is printed and the connection closes.
+On error \fB\(aqerror ...\(aq\fP is printed (it gives a syntax error on unknown
+option).
+For some options a list of values, one on each line, is printed.
+The options are shown from the config file as modified with set_option.
+For some options an override may have been taken that does not show up with
+this command, not results from e.g. the verbosity and forward control
+commands.
+Not all options work, see list_stubs, list_forwards, list_local_zones and
+list_local_data for those.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B list_stubs
+List the stub zones in use.
+These are printed one by one to the output.
This includes the root hints in use.
+.UNINDENT
+.INDENT 0.0
.TP
-.B list_forwards
-List the forward zones in use. These are printed zone by zone to the output.
+.B list_forwards
+List the forward zones in use.
+These are printed zone by zone to the output.
+.UNINDENT
+.INDENT 0.0
.TP
-.B list_insecure
+.B list_insecure
List the zones with domain\-insecure.
-.TP
-.B list_local_zones
-List the local zones in use. These are printed one per line with zone type.
-.TP
-.B list_local_data
-List the local data RRs in use. The resource records are printed.
-.TP
-.B insecure_add \fIzone
-Add a \fBdomain\-insecure\fR for the given zone, like the statement in unbound.conf.
-Adds to the running Unbound without affecting the cache contents (which may
-still be bogus, use \fBflush_zone\fR to remove it), does not affect the config file.
-.TP
-.B insecure_remove \fIzone
+.UNINDENT
+.INDENT 0.0
+.TP
+.B list_local_zones
+List the local zones in use.
+These are printed one per line with zone type.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B list_local_data
+List the local data RRs in use.
+The resource records are printed.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B insecure_add \fIzone\fP
+Add a domain\-insecure for the given zone, like the statement in
+unbound.conf.
+Adds to the running Unbound without affecting the cache
+contents (which may still be bogus, use flush_zone to remove it), does not
+affect the config file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B insecure_remove \fIzone\fP
Removes domain\-insecure for the given zone.
-.TP
-.B forward_add \fR[\fI+it\fR] \fIzone addr ...
-Add a new forward zone to running Unbound. With +i option also adds a
-\fIdomain\-insecure\fR for the zone (so it can resolve insecurely if you have
-a DNSSEC root trust anchor configured for other names).
-The addr can be IP4, IP6 or nameserver names, like \fIforward-zone\fR config
-in unbound.conf.
-The +t option sets it to use tls upstream, like \fIforward\-tls\-upstream\fR: yes.
-.TP
-.B forward_remove \fR[\fI+i\fR] \fIzone
-Remove a forward zone from running Unbound. The +i also removes a
-\fIdomain\-insecure\fR for the zone.
-.TP
-.B stub_add \fR[\fI+ipt\fR] \fIzone addr ...
-Add a new stub zone to running Unbound. With +i option also adds a
-\fIdomain\-insecure\fR for the zone. With +p the stub zone is set to prime,
-without it it is set to notprime. The addr can be IP4, IP6 or nameserver
-names, like the \fIstub-zone\fR config in unbound.conf.
-The +t option sets it to use tls upstream, like \fIstub\-tls\-upstream\fR: yes.
-.TP
-.B stub_remove \fR[\fI+i\fR] \fIzone
-Remove a stub zone from running Unbound. The +i also removes a
-\fIdomain\-insecure\fR for the zone.
-.TP
-.B forward \fR[\fIoff\fR | \fIaddr ...\fR ]
-Setup forwarding mode. Configures if the server should ask other upstream
-nameservers, should go to the internet root nameservers itself, or show
-the current config. You could pass the nameservers after a DHCP update.
-.IP
+.UNINDENT
+.INDENT 0.0
+.TP
+.B forward_add [\fB+it\fP] \fIzone addr ...\fP
+Add a new forward zone to running Unbound.
+With \fB+i\fP option also adds a domain\-insecure for the zone (so it can
+resolve insecurely if you have a DNSSEC root trust anchor configured for
+other names).
+The addr can be IP4, IP6 or nameserver names, like forward\-zone config in
+unbound.conf.
+The \fB+t\fP option sets it to use TLS upstream, like
+\fI\%forward\-tls\-upstream: yes\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B forward_remove [\fB+i\fP] \fIzone\fP
+Remove a forward zone from running Unbound.
+The \fB+i\fP also removes a domain\-insecure for the zone.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stub_add [\fB+ipt\fP] \fIzone addr ...\fP
+Add a new stub zone to running Unbound.
+With \fB+i\fP option also adds a domain\-insecure for the zone.
+With \fB+p\fP the stub zone is set to prime, without it it is set to
+notprime.
+The addr can be IP4, IP6 or nameserver names, like the \fBstub\-zone:\fP
+config in unbound.conf.
+The \fB+t\fP option sets it to use TLS upstream, like
+\fI\%stub\-tls\-upstream: yes\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stub_remove [\fB+i\fP] \fIzone\fP
+Remove a stub zone from running Unbound.
+The \fB+i\fP also removes a domain\-insecure for the zone.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B forward [\fIoff\fP | \fIaddr ...\fP ]
+Setup forwarding mode.
+Configures if the server should ask other upstream nameservers, should go
+to the internet root nameservers itself, or show the current config.
+You could pass the nameservers after a DHCP update.
+.sp
Without arguments the current list of addresses used to forward all queries
-to is printed. On startup this is from the forward\-zone "." configuration.
-Afterwards it shows the status. It prints off when no forwarding is used.
-.IP
-If \fIoff\fR is passed, forwarding is disabled and the root nameservers
-are used. This can be used to avoid to avoid buggy or non\-DNSSEC supporting
-nameservers returned from DHCP. But may not work in hotels or hotspots.
-.IP
-If one or more IPv4 or IPv6 addresses are given, those are then used to forward
-queries to. The addresses must be separated with spaces. With '@port' the
-port number can be set explicitly (default port is 53 (DNS)).
-.IP
-By default the forwarder information from the config file for the root "." is
-used. The config file is not changed, so after a reload these changes are
-gone. Other forward zones from the config file are not affected by this command.
-.TP
-.B ratelimit_list \fR[\fI+a\fR]
-List the domains that are ratelimited. Printed one per line with current
-estimated qps and qps limit from config. With +a it prints all domains, not
-just the ratelimited domains, with their estimated qps. The ratelimited
-domains return an error for uncached (new) queries, but cached queries work
-as normal.
-.TP
-.B ip_ratelimit_list \fR[\fI+a\fR]
-List the ip addresses that are ratelimited. Printed one per line with current
-estimated qps and qps limit from config. With +a it prints all ips, not
-just the ratelimited ips, with their estimated qps. The ratelimited
-ips are dropped before checking the cache.
-.TP
-.B list_auth_zones
-List the auth zones that are configured. Printed one per line with a status,
-indicating if the zone is expired and current serial number. Configured RPZ
-zones are included.
-.TP
-.B auth_zone_reload \fIzone\fR
-Reload the auth zone (or RPZ zone) from zonefile. The zonefile is read in
-overwriting the current contents of the zone in memory. This changes the auth
-zone contents itself, not the cache contents. Such cache contents exists if
-you set Unbound to validate with for-upstream yes and that can be cleared with
-\fBflush_zone\fR \fIzone\fR.
-.TP
-.B auth_zone_transfer \fIzone\fR
-Transfer the auth zone (or RPZ zone) from master. The auth zone probe sequence
-is started, where the masters are probed to see if they have an updated zone
-(with the SOA serial check). And then the zone is transferred for a newer zone
-version.
-.TP
-.B rpz_enable \fIzone\fR
+to is printed.
+On startup this is from the forward\-zone \fB\(dq.\(dq\fP configuration.
+Afterwards it shows the status.
+It prints off when no forwarding is used.
+.sp
+If off is passed, forwarding is disabled and the root nameservers are
+used.
+This can be used to avoid to avoid buggy or non\-DNSSEC supporting
+nameservers returned from DHCP.
+But may not work in hotels or hotspots.
+.sp
+If one or more IPv4 or IPv6 addresses are given, those are then used to
+forward queries to.
+The addresses must be separated with spaces.
+With \fB\(aq@port\(aq\fP the port number can be set explicitly (default port is 53
+(DNS)).
+.sp
+By default the forwarder information from the config file for the root
+\fB\(dq.\(dq\fP is used.
+The config file is not changed, so after a reload these changes are gone.
+Other forward zones from the config file are not affected by this command.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ratelimit_list [\fB+a\fP]
+List the domains that are ratelimited.
+Printed one per line with current estimated qps and qps limit from config.
+With \fB+a\fP it prints all domains, not just the ratelimited domains, with
+their estimated qps.
+The ratelimited domains return an error for uncached (new) queries, but
+cached queries work as normal.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ip_ratelimit_list [\fB+a\fP]
+List the ip addresses that are ratelimited.
+Printed one per line with current estimated qps and qps limit from config.
+With \fB+a\fP it prints all ips, not just the ratelimited ips, with their
+estimated qps.
+The ratelimited ips are dropped before checking the cache.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B list_auth_zones
+List the auth zones that are configured.
+Printed one per line with a status, indicating if the zone is expired and
+current serial number.
+Configured RPZ zones are included.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B auth_zone_reload \fIzone\fP
+Reload the auth zone (or RPZ zone) from zonefile.
+The zonefile is read in overwriting the current contents of the zone in
+memory.
+This changes the auth zone contents itself, not the cache contents.
+Such cache contents exists if you set Unbound to validate with
+\fBfor\-upstream: yes\fP and that can be cleared with \fBflush_zone\fP \fIzone\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B auth_zone_transfer \fIzone\fP
+Transfer the auth zone (or RPZ zone) from master.
+The auth zone probe sequence is started, where the masters are probed to
+see if they have an updated zone (with the SOA serial check).
+And then the zone is transferred for a newer zone version.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B rpz_enable \fIzone\fP
Enable the RPZ zone if it had previously been disabled.
+.UNINDENT
+.INDENT 0.0
.TP
-.B rpz_disable \fIzone\fR
+.B rpz_disable \fIzone\fP
Disable the RPZ zone.
-.TP
-.B view_list_local_zones \fIview\fR
-\fIlist_local_zones\fR for given view.
-.TP
-.B view_local_zone \fIview\fR \fIname\fR \fItype
-\fIlocal_zone\fR for given view.
-.TP
-.B view_local_zone_remove \fIview\fR \fIname
-\fIlocal_zone_remove\fR for given view.
-.TP
-.B view_list_local_data \fIview\fR
-\fIlist_local_data\fR for given view.
-.TP
-.B view_local_data \fIview\fR \fIRR data...
-\fIlocal_data\fR for given view.
-.TP
-.B view_local_data_remove \fIview\fR \fIname
-\fIlocal_data_remove\fR for given view.
-.TP
-.B view_local_datas_remove \fIview\fR
-Remove a list of \fIlocal_data\fR for given view from stdin. Like local_datas_remove.
-.TP
-.B view_local_datas \fIview\fR
-Add a list of \fIlocal_data\fR for given view from stdin. Like local_datas.
-.TP
-.B add_cookie_secret <secret>
-Add or replace a cookie secret persistently. <secret> needs to be an 128 bit
-hex string.
-.IP
-Cookie secrets can be either \fIactive\fR or \fIstaging\fR. \fIActive\fR cookie
-secrets are used to create DNS Cookies, but verification of a DNS Cookie
-succeeds with any of the \fIactive\fR or \fIstaging\fR cookie secrets. The
-state of the current cookie secrets can be printed with the
-\fBprint_cookie_secrets\fR command.
-.IP
-When there are no cookie secrets configured yet, the <secret> is added as
-\fIactive\fR. If there is already an \fIactive\fR cookie secret, the <secret>
-is added as \fIstaging\fR or replacing an existing \fIstaging\fR secret.
-.IP
-To "roll" a cookie secret used in an anycast set. The new secret has to be
-added as staging secret to \fBall\fR nodes in the anycast set. When \fBall\fR
-nodes can verify DNS Cookies with the new secret, the new secret can be
-activated with the \fBactivate_cookie_secret\fR command. After \fBall\fR nodes
-have the new secret \fIactive\fR for at least one hour, the previous secret can
-be dropped with the \fBdrop_cookie_secret\fR command.
-.IP
-Persistence is accomplished by writing to a file which if configured with the
-\fBcookie\-secret\-file\fR option in the server section of the config file.
-This is disabled by default, "".
-.TP
-.B drop_cookie_secret
-Drop the \fIstaging\fR cookie secret.
-.TP
-.B activate_cookie_secret
-Make the current \fIstaging\fR cookie secret \fIactive\fR, and the current
-\fIactive\fR cookie secret \fIstaging\fR.
-.TP
-.B print_cookie_secrets
+.UNINDENT
+.INDENT 0.0
+.TP
+.B view_list_local_zones \fIview\fP
+\fIlist_local_zones\fP for given view.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B view_local_zone \fIview name type\fP
+\fIlocal_zone\fP for given view.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B view_local_zone_remove \fIview name\fP
+\fIlocal_zone_remove\fP for given view.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B view_list_local_data \fIview\fP
+\fIlist_local_data\fP for given view.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B view_local_data \fIview RR data...\fP
+\fIlocal_data\fP for given view.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B view_local_data_remove \fIview name\fP
+\fIlocal_data_remove\fP for given view.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B view_local_datas_remove \fIview\fP
+Remove a list of \fIlocal_data\fP for given view from stdin.
+Like \fIlocal_datas_remove\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B view_local_datas \fIview\fP
+Add a list of \fIlocal_data\fP for given view from stdin.
+Like \fIlocal_datas\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B add_cookie_secret \fIsecret\fP
+Add or replace a cookie secret persistently.
+\fIsecret\fP needs to be an 128 bit hex string.
+.sp
+Cookie secrets can be either \fBactive\fP or \fBstaging\fP\&.
+\fBActive\fP cookie secrets are used to create DNS Cookies, but verification
+of a DNS Cookie succeeds with any of the \fBactive\fP or \fBstaging\fP cookie
+secrets.
+The state of the current cookie secrets can be printed with the
+\fI\%print_cookie_secrets\fP
+command.
+.sp
+When there are no cookie secrets configured yet, the \fIsecret\fP is added as
+\fBactive\fP\&.
+If there is already an \fBactive\fP cookie secret, the \fIsecret\fP is added as
+\fBstaging\fP or replacing an existing \fBstaging\fP secret.
+.sp
+To \(dqroll\(dq a cookie secret used in an anycast set.
+The new secret has to be added as \fBstaging\fP secret to \fBall\fP nodes in
+the anycast set.
+When \fBall\fP nodes can verify DNS Cookies with the new secret, the new
+secret can be activated with the
+\fI\%activate_cookie_secret\fP
+command.
+After \fBall\fP nodes have the new secret \fBactive\fP for at least one hour,
+the previous secret can be dropped with the
+\fI\%drop_cookie_secret\fP
+command.
+.sp
+Persistence is accomplished by writing to a file which is configured with
+the
+\fI\%cookie\-secret\-file\fP
+option in the server section of the config file.
+This is disabled by default, \(dq\(dq.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B drop_cookie_secret
+Drop the \fBstaging\fP cookie secret.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B activate_cookie_secret
+Make the current \fBstaging\fP cookie secret \fBactive\fP, and the current
+\fBactive\fP cookie secret \fBstaging\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B print_cookie_secrets
Show the current configured cookie secrets with their status.
-.SH "EXIT CODE"
-The unbound\-control program exits with status code 1 on error, 0 on success.
-.SH "SET UP"
-The setup requires a self\-signed certificate and private keys for both
-the server and client. The script \fIunbound\-control\-setup\fR generates
-these in the default run directory, or with \-d in another directory.
+.UNINDENT
+.SH EXIT CODE
+.sp
+The \fBunbound\-control\fP program exits with status code 1 on error, 0 on
+success.
+.SH SET UP
+.sp
+The setup requires a self\-signed certificate and private keys for both the
+server and client.
+The script \fBunbound\-control\-setup\fP generates these in the default run
+directory, or with \fB\-d\fP in another directory.
If you change the access control permissions on the key files you can decide
-who can use unbound\-control, by default owner and group but not all users.
-Run the script under the same username as you have configured in unbound.conf
-or as root, so that the daemon is permitted to read the files, for example with:
+who can use \fBunbound\-control\fP, by default owner and group but not all users.
+Run the script under the same username as you have configured in
+\fBunbound.conf\fP or as root, so that the daemon is permitted to read the
+files, for example with:
+.INDENT 0.0
+.INDENT 3.5
+.sp
.nf
- sudo \-u unbound unbound\-control\-setup
+.ft C
+sudo \-u unbound unbound\-control\-setup
+.ft P
.fi
-If you have not configured
-a username in unbound.conf, the keys need read permission for the user
-credentials under which the daemon is started.
+.UNINDENT
+.UNINDENT
+.sp
+If you have not configured a username in \fBunbound.conf\fP, the keys need
+read permission for the user credentials under which the daemon is started.
The script preserves private keys present in the directory.
-After running the script as root, turn on \fBcontrol\-enable\fR in
-\fIunbound.conf\fR.
-.SH "STATISTIC COUNTERS"
-The \fIstats\fR command shows a number of statistic counters.
-.TP
-.I threadX.num.queries
+After running the script as root, turn on
+\fI\%control\-enable\fP in
+\fBunbound.conf\fP\&.
+.SH STATISTIC COUNTERS
+.sp
+The \fI\%stats\fP and
+\fI\%stats_noreset\fP commands show a
+number of statistic counters:
+.INDENT 0.0
+.TP
+.B threadX.num.queries
number of queries received by thread
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.queries_ip_ratelimited
+.B threadX.num.queries_ip_ratelimited
number of queries rate limited by thread
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.queries_cookie_valid
+.B threadX.num.queries_cookie_valid
number of queries with a valid DNS Cookie by thread
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.queries_cookie_client
+.B threadX.num.queries_cookie_client
number of queries with a client part only DNS Cookie by thread
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.queries_cookie_invalid
+.B threadX.num.queries_cookie_invalid
number of queries with an invalid DNS Cookie by thread
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.queries_discard_timeout
-number of queries removed due to discard-timeout by thread
+.B threadX.num.queries_discard_timeout
+number of queries removed due to discard\-timeout by thread
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.queries_wait_limit
-number of queries removed due to wait-limit by thread
+.B threadX.num.queries_wait_limit
+number of queries removed due to wait\-limit by thread
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.cachehits
+.B threadX.num.cachehits
number of queries that were successfully answered using a cache lookup
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.cachemiss
+.B threadX.num.cachemiss
number of queries that needed recursive processing
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.dnscrypt.crypted
-number of queries that were encrypted and successfully decapsulated by dnscrypt.
+.B threadX.num.dnscrypt.crypted
+number of queries that were encrypted and successfully decapsulated by
+dnscrypt.
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.dnscrypt.cert
+.B threadX.num.dnscrypt.cert
number of queries that were requesting dnscrypt certificates.
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.dnscrypt.cleartext
+.B threadX.num.dnscrypt.cleartext
number of queries received on dnscrypt port that were cleartext and not a
request for certificates.
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.dnscrypt.malformed
+.B threadX.num.dnscrypt.malformed
number of request that were neither cleartext, not valid dnscrypt messages.
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.dns_error_reports
+.B threadX.num.dns_error_reports
number of DNS Error Reports generated by thread
-.TP
-.I threadX.num.prefetch
-number of cache prefetches performed. This number is included in
-cachehits, as the original query had the unprefetched answer from cache,
-and resulted in recursive processing, taking a slot in the requestlist.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B threadX.num.prefetch
+number of cache prefetches performed.
+This number is included in cachehits, as the original query had the
+unprefetched answer from cache, and resulted in recursive processing,
+taking a slot in the requestlist.
Not part of the recursivereplies (or the histogram thereof) or cachemiss,
as a cache response was sent.
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.num.expired
+.B threadX.num.expired
number of replies that served an expired cache entry.
-.TP
-.I threadX.num.queries_timed_out
-number of queries that are dropped because they waited in the UDP socket buffer
-for too long.
-.TP
-.I threadX.query.queue_time_us.max
-The maximum wait time for packets in the socket buffer, in microseconds. This
-is only reported when sock-queue-timeout is enabled.
-.TP
-.I threadX.num.recursivereplies
-The number of replies sent to queries that needed recursive processing. Could be smaller than threadX.num.cachemiss if due to timeouts no replies were sent for some queries.
-.TP
-.I threadX.requestlist.avg
-The average number of requests in the internal recursive processing request list on insert of a new incoming recursive processing query.
-.TP
-.I threadX.requestlist.max
+.UNINDENT
+.INDENT 0.0
+.TP
+.B threadX.num.queries_timed_out
+number of queries that are dropped because they waited in the UDP socket
+buffer for too long.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B threadX.query.queue_time_us.max
+The maximum wait time for packets in the socket buffer, in microseconds.
+This is only reported when
+\fI\%sock\-queue\-timeout\fP is enabled.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B threadX.num.recursivereplies
+The number of replies sent to queries that needed recursive processing.
+Could be smaller than threadX.num.cachemiss if due to timeouts no replies
+were sent for some queries.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B threadX.requestlist.avg
+The average number of requests in the internal recursive processing request
+list on insert of a new incoming recursive processing query.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B threadX.requestlist.max
Maximum size attained by the internal recursive processing request list.
-.TP
-.I threadX.requestlist.overwritten
-Number of requests in the request list that were overwritten by newer entries. This happens if there is a flood of queries that recursive processing and the server has a hard time.
-.TP
-.I threadX.requestlist.exceeded
-Queries that were dropped because the request list was full. This happens if a flood of queries need recursive processing, and the server can not keep up.
-.TP
-.I threadX.requestlist.current.all
-Current size of the request list, includes internally generated queries (such
-as priming queries and glue lookups).
-.TP
-.I threadX.requestlist.current.user
+.UNINDENT
+.INDENT 0.0
+.TP
+.B threadX.requestlist.overwritten
+Number of requests in the request list that were overwritten by newer
+entries.
+This happens if there is a flood of queries that recursive processing and
+the server has a hard time.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B threadX.requestlist.exceeded
+Queries that were dropped because the request list was full.
+This happens if a flood of queries need recursive processing, and the
+server can not keep up.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B threadX.requestlist.current.all
+Current size of the request list, includes internally generated queries
+(such as priming queries and glue lookups).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B threadX.requestlist.current.user
Current size of the request list, only the requests from client queries.
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.recursion.time.avg
-Average time it took to answer queries that needed recursive processing. Note that queries that were answered from the cache are not in this average.
+.B threadX.recursion.time.avg
+Average time it took to answer queries that needed recursive processing.
+Note that queries that were answered from the cache are not in this average.
+.UNINDENT
+.INDENT 0.0
.TP
-.I threadX.recursion.time.median
+.B threadX.recursion.time.median
The median of the time it took to answer queries that needed recursive
-processing. The median means that 50% of the user queries were answered in
-less than this time. Because of big outliers (usually queries to non
-responsive servers), the average can be bigger than the median. This median
-has been calculated by interpolation from a histogram.
-.TP
-.I threadX.tcpusage
-The currently held tcp buffers for incoming connections. A spot value on
-the time of the request. This helps you spot if the incoming\-num\-tcp
-buffers are full.
-.TP
-.I total.num.queries
+processing.
+The median means that 50% of the user queries were answered in less than
+this time.
+Because of big outliers (usually queries to non responsive servers), the
+average can be bigger than the median.
+This median has been calculated by interpolation from a histogram.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B threadX.tcpusage
+The currently held tcp buffers for incoming connections.
+A spot value on the time of the request.
+This helps you spot if the incoming\-num\-tcp buffers are full.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B total.num.queries
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.queries_ip_ratelimited
+.B total.num.queries_ip_ratelimited
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.queries_cookie_valid
+.B total.num.queries_cookie_valid
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.queries_cookie_client
+.B total.num.queries_cookie_client
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.queries_cookie_invalid
+.B total.num.queries_cookie_invalid
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.queries_discard_timeout
+.B total.num.queries_discard_timeout
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.queries_wait_limit
+.B total.num.queries_wait_limit
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.cachehits
+.B total.num.cachehits
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.cachemiss
+.B total.num.cachemiss
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.dnscrypt.crypted
+.B total.num.dnscrypt.crypted
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.dnscrypt.cert
+.B total.num.dnscrypt.cert
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.dnscrypt.cleartext
+.B total.num.dnscrypt.cleartext
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.dnscrypt.malformed
+.B total.num.dnscrypt.malformed
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.dns_error_reports
+.B total.num.dns_error_reports
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.prefetch
+.B total.num.prefetch
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.expired
+.B total.num.expired
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.queries_timed_out
+.B total.num.queries_timed_out
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.query.queue_time_us.max
+.B total.query.queue_time_us.max
the maximum of the thread values.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.num.recursivereplies
+.B total.num.recursivereplies
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.requestlist.avg
+.B total.requestlist.avg
averaged over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.requestlist.max
+.B total.requestlist.max
the maximum of the thread requestlist.max values.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.requestlist.overwritten
+.B total.requestlist.overwritten
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.requestlist.exceeded
+.B total.requestlist.exceeded
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.requestlist.current.all
+.B total.requestlist.current.all
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.recursion.time.median
+.B total.recursion.time.median
averaged over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I total.tcpusage
+.B total.tcpusage
summed over threads.
+.UNINDENT
+.INDENT 0.0
.TP
-.I time.now
+.B time.now
current time in seconds since 1970.
+.UNINDENT
+.INDENT 0.0
.TP
-.I time.up
+.B time.up
uptime since server boot in seconds.
+.UNINDENT
+.INDENT 0.0
.TP
-.I time.elapsed
+.B time.elapsed
time since last statistics printout, in seconds.
+.UNINDENT
.SH EXTENDED STATISTICS
+.INDENT 0.0
.TP
-.I mem.cache.rrset
+.B mem.cache.rrset
Memory in bytes in use by the RRset cache.
+.UNINDENT
+.INDENT 0.0
.TP
-.I mem.cache.message
+.B mem.cache.message
Memory in bytes in use by the message cache.
+.UNINDENT
+.INDENT 0.0
.TP
-.I mem.cache.dnscrypt_shared_secret
+.B mem.cache.dnscrypt_shared_secret
Memory in bytes in use by the dnscrypt shared secrets cache.
+.UNINDENT
+.INDENT 0.0
.TP
-.I mem.cache.dnscrypt_nonce
+.B mem.cache.dnscrypt_nonce
Memory in bytes in use by the dnscrypt nonce cache.
+.UNINDENT
+.INDENT 0.0
.TP
-.I mem.mod.iterator
+.B mem.mod.iterator
Memory in bytes in use by the iterator module.
-.TP
-.I mem.mod.validator
-Memory in bytes in use by the validator module. Includes the key cache and
-negative cache.
-.TP
-.I mem.streamwait
-Memory in bytes in used by the TCP and TLS stream wait buffers. These are
-answers waiting to be written back to the clients.
-.TP
-.I mem.http.query_buffer
-Memory in bytes used by the HTTP/2 query buffers. Containing (partial) DNS
-queries waiting for request stream completion.
-.TP
-.I mem.http.response_buffer
-Memory in bytes used by the HTTP/2 response buffers. Containing DNS responses
-waiting to be written back to the clients.
-.TP
-.I mem.quic
-Memory in bytes used by QUIC. Containing connection information, stream
-information, queries read and responses written back to the clients.
-.TP
-.I histogram.<sec>.<usec>.to.<sec>.<usec>
-Shows a histogram, summed over all threads. Every element counts the
-recursive queries whose reply time fit between the lower and upper bound.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B mem.mod.validator
+Memory in bytes in use by the validator module.
+Includes the key cache and negative cache.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B mem.streamwait
+Memory in bytes in used by the TCP and TLS stream wait buffers.
+These are answers waiting to be written back to the clients.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B mem.http.query_buffer
+Memory in bytes used by the HTTP/2 query buffers.
+Containing (partial) DNS queries waiting for request stream completion.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B mem.http.response_buffer
+Memory in bytes used by the HTTP/2 response buffers.
+Containing DNS responses waiting to be written back to the clients.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B mem.quic
+Memory in bytes used by QUIC.
+Containing connection information, stream information, queries read and
+responses written back to the clients.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B histogram.<sec>.<usec>.to.<sec>.<usec>
+Shows a histogram, summed over all threads.
+Every element counts the recursive queries whose reply time fit between the
+lower and upper bound.
Times larger or equal to the lowerbound, and smaller than the upper bound.
There are 40 buckets, with bucket sizes doubling.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.type.A
+.B num.query.type.A
The total number of queries over all threads with query type A.
Printed for the other query types as well, but only for the types for which
queries were received, thus =0 entries are omitted for brevity.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.type.other
+.B num.query.type.other
Number of queries with query types 256\-65535.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.class.IN
-The total number of queries over all threads with query class IN (internet).
+.B num.query.class.IN
+The total number of queries over all threads with query class IN
+(internet).
Also printed for other classes (such as CH (CHAOS) sometimes used for
debugging), or NONE, ANY, used by dynamic update.
num.query.class.other is printed for classes 256\-65535.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.opcode.QUERY
+.B num.query.opcode.QUERY
The total number of queries over all threads with query opcode QUERY.
Also printed for other opcodes, UPDATE, ...
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.tcp
+.B num.query.tcp
Number of queries that were made using TCP towards the Unbound server.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.tcpout
+.B num.query.tcpout
Number of queries that the Unbound server made using TCP outgoing towards
other servers.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.udpout
+.B num.query.udpout
Number of queries that the Unbound server made using UDP outgoing towards
other servers.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.tls
+.B num.query.tls
Number of queries that were made using TLS towards the Unbound server.
These are also counted in num.query.tcp, because TLS uses TCP.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.tls.resume
-Number of TLS session resumptions, these are queries over TLS towards
-the Unbound server where the client negotiated a TLS session resumption key.
+.B num.query.tls.resume
+Number of TLS session resumptions, these are queries over TLS towards the
+Unbound server where the client negotiated a TLS session resumption key.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.https
+.B num.query.https
Number of queries that were made using HTTPS towards the Unbound server.
These are also counted in num.query.tcp and num.query.tls, because HTTPS
uses TLS and TCP.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.quic
+.B num.query.quic
Number of queries that were made using QUIC towards the Unbound server.
-These are also counted in num.query.tls, because TLS is used for these queries.
+These are also counted in num.query.tls, because TLS is used for these
+queries.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.ipv6
+.B num.query.ipv6
Number of queries that were made using IPv6 towards the Unbound server.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.flags.RD
+.B num.query.flags.RD
The number of queries that had the RD flag set in the header.
Also printed for flags QR, AA, TC, RA, Z, AD, CD.
-Note that queries with flags QR, AA or TC may have been rejected
-because of that.
+Note that queries with flags QR, AA or TC may have been rejected because of
+that.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.edns.present
+.B num.query.edns.present
number of queries that had an EDNS OPT record present.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.edns.DO
-number of queries that had an EDNS OPT record with the DO (DNSSEC OK) bit set.
+.B num.query.edns.DO
+number of queries that had an EDNS OPT record with the DO (DNSSEC OK) bit
+set.
These queries are also included in the num.query.edns.present number.
-.TP
-.I num.query.ratelimited
-The number of queries that are turned away from being send to nameserver due to
-ratelimiting.
-.TP
-.I num.query.dnscrypt.shared_secret.cachemiss
-The number of dnscrypt queries that did not find a shared secret in the cache.
-This can be used to compute the shared secret hitrate.
-.TP
-.I num.query.dnscrypt.replay
-The number of dnscrypt queries that found a nonce hit in the nonce cache and
-hence are considered a query replay.
-.TP
-.I num.answer.rcode.NXDOMAIN
-The number of answers to queries, from cache or from recursion, that had the
-return code NXDOMAIN. Also printed for the other return codes.
-.TP
-.I num.answer.rcode.nodata
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.query.ratelimited
+The number of queries that are turned away from being send to nameserver
+due to ratelimiting.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.query.dnscrypt.shared_secret.cachemiss
+The number of dnscrypt queries that did not find a shared secret in the
+cache.
+This can be use to compute the shared secret hitrate.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.query.dnscrypt.replay
+The number of dnscrypt queries that found a nonce hit in the nonce cache
+and hence are considered a query replay.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.answer.rcode.NXDOMAIN
+The number of answers to queries, from cache or from recursion, that had
+the return code NXDOMAIN.
+Also printed for the other return codes.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.answer.rcode.nodata
The number of answers to queries that had the pseudo return code nodata.
-This means the actual return code was NOERROR, but additionally, no data was
-carried in the answer (making what is called a NOERROR/NODATA answer).
+This means the actual return code was NOERROR, but additionally, no data
+was carried in the answer (making what is called a NOERROR/NODATA answer).
These queries are also included in the num.answer.rcode.NOERROR number.
Common for AAAA lookups when an A record exists, and no AAAA.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.answer.secure
-Number of answers that were secure. The answer validated correctly.
+.B num.answer.secure
+Number of answers that were secure.
+The answer validated correctly.
The AD bit might have been set in some of these answers, where the client
signalled (with DO or AD bit in the query) that they were ready to accept
the AD bit in the answer.
-.TP
-.I num.answer.bogus
-Number of answers that were bogus. These answers resulted in SERVFAIL
-to the client because the answer failed validation.
-.TP
-.I num.rrset.bogus
-The number of rrsets marked bogus by the validator. Increased for every
-RRset inspection that fails.
-.TP
-.I unwanted.queries
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.answer.bogus
+Number of answers that were bogus.
+These answers resulted in SERVFAIL to the client because the answer failed
+validation.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.rrset.bogus
+The number of rrsets marked bogus by the validator.
+Increased for every RRset inspection that fails.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B unwanted.queries
Number of queries that were refused or dropped because they failed the
access control settings.
+.UNINDENT
+.INDENT 0.0
.TP
-.I unwanted.replies
-Replies that were unwanted or unsolicited. Could have been random traffic,
-delayed duplicates, very late answers, or could be spoofing attempts.
+.B unwanted.replies
+Replies that were unwanted or unsolicited.
+Could have been random traffic, delayed duplicates, very late answers, or
+could be spoofing attempts.
Some low level of late answers and delayed duplicates are to be expected
-with the UDP protocol. Very high values could indicate a threat (spoofing).
+with the UDP protocol.
+Very high values could indicate a threat (spoofing).
+.UNINDENT
+.INDENT 0.0
.TP
-.I msg.cache.count
+.B msg.cache.count
The number of items (DNS replies) in the message cache.
-.TP
-.I rrset.cache.count
-The number of RRsets in the rrset cache. This includes rrsets used by
-the messages in the message cache, but also delegation information.
-.TP
-.I infra.cache.count
-The number of items in the infra cache. These are IP addresses with their
-timing and protocol support information.
-.TP
-.I key.cache.count
-The number of items in the key cache. These are DNSSEC keys, one item
-per delegation point, and their validation status.
-.TP
-.I msg.cache.max_collisions
-The maximum number of hash table collisions in the msg cache. This is the
-number of hashes that are identical when a new element is inserted in the
-hash table. If the value is very large, like hundreds, something is wrong
-with the performance of the hash table, hash values are incorrect or malicious.
-.TP
-.I rrset.cache.max_collisions
-The maximum number of hash table collisions in the rrset cache. This is the
-number of hashes that are identical when a new element is inserted in the
-hash table. If the value is very large, like hundreds, something is wrong
-with the performance of the hash table, hash values are incorrect or malicious.
-.TP
-.I dnscrypt_shared_secret.cache.count
-The number of items in the shared secret cache. These are precomputed shared
-secrets for a given client public key/server secret key pair. Shared secrets
-are CPU intensive and this cache allows Unbound to avoid recomputing the
-shared secret when multiple dnscrypt queries are sent from the same client.
-.TP
-.I dnscrypt_nonce.cache.count
-The number of items in the client nonce cache. This cache is used to prevent
-dnscrypt queries replay. The client nonce must be unique for each client public
-key/server secret key pair. This cache should be able to host QPS * `replay
-window` interval keys to prevent replay of a query during `replay window`
-seconds.
-.TP
-.I num.query.authzone.up
+.UNINDENT
+.INDENT 0.0
+.TP
+.B rrset.cache.count
+The number of RRsets in the rrset cache.
+This includes rrsets used by the messages in the message cache, but also
+delegation information.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B infra.cache.count
+The number of items in the infra cache.
+These are IP addresses with their timing and protocol support information.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B key.cache.count
+The number of items in the key cache.
+These are DNSSEC keys, one item per delegation point, and their validation
+status.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B msg.cache.max_collisions
+The maximum number of hash table collisions in the msg cache.
+This is the number of hashes that are identical when a new element is
+inserted in the hash table.
+If the value is very large, like hundreds, something is wrong with the
+performance of the hash table, hash values are incorrect or malicious.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B rrset.cache.max_collisions
+The maximum number of hash table collisions in the rrset cache.
+This is the number of hashes that are identical when a new element is
+inserted in the hash table.
+If the value is very large, like hundreds, something is wrong with the
+performance of the hash table, hash values are incorrect or malicious.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnscrypt_shared_secret.cache.count
+The number of items in the shared secret cache.
+These are precomputed shared secrets for a given client public key/server
+secret key pair.
+Shared secrets are CPU intensive and this cache allows Unbound to avoid
+recomputing the shared secret when multiple dnscrypt queries are sent from
+the same client.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnscrypt_nonce.cache.count
+The number of items in the client nonce cache.
+This cache is used to prevent dnscrypt queries replay.
+The client nonce must be unique for each client public key/server secret
+key pair.
+This cache should be able to host QPS * \fIreplay window\fP interval keys to
+prevent replay of a query during \fIreplay window\fP seconds.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.query.authzone.up
The number of queries answered from auth\-zone data, upstream queries.
-These queries would otherwise have been sent (with fallback enabled) to
-the internet, but are now answered from the auth zone.
+These queries would otherwise have been sent (with fallback enabled) to the
+internet, but are now answered from the auth zone.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.authzone.down
+.B num.query.authzone.down
The number of queries for downstream answered from auth\-zone data.
-These queries are from downstream clients, and have had an answer from
-the data in the auth zone.
+These queries are from downstream clients, and have had an answer from the
+data in the auth zone.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.aggressive.NOERROR
+.B num.query.aggressive.NOERROR
The number of queries answered using cached NSEC records with NODATA RCODE.
These queries would otherwise have been sent to the internet, but are now
answered using cached data.
+.UNINDENT
+.INDENT 0.0
.TP
-.I num.query.aggressive.NXDOMAIN
-The number of queries answered using cached NSEC records with NXDOMAIN RCODE.
+.B num.query.aggressive.NXDOMAIN
+The number of queries answered using cached NSEC records with NXDOMAIN
+RCODE.
These queries would otherwise have been sent to the internet, but are now
answered using cached data.
-.TP
-.I num.query.subnet
-Number of queries that got an answer that contained EDNS client subnet data.
-.TP
-.I num.query.subnet_cache
-Number of queries answered from the edns client subnet cache. These are
-counted as cachemiss by the main counters, but hit the client subnet
-specific cache after getting processed by the edns client subnet module.
-.TP
-.I num.query.cachedb
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.query.subnet
+Number of queries that got an answer that contained EDNS client subnet
+data.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.query.subnet_cache
+Number of queries answered from the edns client subnet cache.
+These are counted as cachemiss by the main counters, but hit the client
+subnet specific cache after getting processed by the edns client subnet
+module.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.query.cachedb
Number of queries answered from the external cache of cachedb.
These are counted as cachemiss by the main counters, but hit the cachedb
external cache after getting processed by the cachedb module.
-.TP
-.I num.rpz.action.<rpz_action>
-Number of queries answered using configured RPZ policy, per RPZ action type.
-Possible actions are: nxdomain, nodata, passthru, drop, tcp\-only, local\-data,
-disabled, and cname\-override.
-.SH "FILES"
-.TP
-.I @ub_conf_file@
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num.rpz.action.<rpz_action>
+Number of queries answered using configured RPZ policy, per RPZ action
+type.
+Possible actions are: nxdomain, nodata, passthru, drop, tcp\-only,
+local\-data, disabled, and cname\-override.
+.UNINDENT
+.SH FILES
+.INDENT 0.0
+.TP
+.B @ub_conf_file@
Unbound configuration file.
.TP
-.I @UNBOUND_RUN_DIR@
-directory with private keys (unbound_server.key and unbound_control.key) and
-self\-signed certificates (unbound_server.pem and unbound_control.pem).
-.SH "SEE ALSO"
-\fIunbound.conf\fR(5),
-\fIunbound\fR(8).
+.B @UNBOUND_RUN_DIR@
+directory with private keys (\fBunbound_server.key\fP and
+\fBunbound_control.key\fP) and self\-signed certificates
+(\fBunbound_server.pem\fP and \fBunbound_control.pem\fP).
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fI\%unbound.conf(5)\fP,
+\fI\%unbound(8)\fP\&.
+.SH AUTHOR
+Unbound developers are mentioned in the CREDITS file in the distribution.
+.SH COPYRIGHT
+1999-2025, NLnet Labs
+.\" Generated by docutils manpage writer.
+.
--- /dev/null
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+.. program:: unbound-control
+
+unbound-control(8)
+==================
+
+Synopsis
+--------
+
+**unbound-control** [``-hq``] [``-c cfgfile``] [``-s server``] command
+
+Description
+-----------
+
+``unbound-control`` performs remote administration on the
+:doc:`unbound(8)</manpages/unbound>` DNS server.
+It reads the configuration file, contacts the Unbound server over TLS sends the
+command and displays the result.
+
+The available options are:
+
+.. option:: -h
+
+ Show the version and commandline option help.
+
+.. option:: -c <cfgfile>
+
+ The config file to read with settings.
+ If not given the default config file
+ :file:`@ub_conf_file@` is used.
+
+.. option:: -s <server[@port]>
+
+ IPv4 or IPv6 address of the server to contact.
+ If not given, the address is read from the config file.
+
+.. option:: -q
+
+ Quiet, if the option is given it does not print anything if it works ok.
+
+Commands
+--------
+
+There are several commands that the server understands.
+
+
+@@UAHL@unbound-control.commands@start@@
+ Start the server.
+ Simply execs :doc:`unbound(8)</manpages/unbound>`.
+ The ``unbound`` executable is searched for in the **PATH** set in the
+ environment.
+ It is started with the config file specified using :option:`-c` or the
+ default config file.
+
+
+@@UAHL@unbound-control.commands@stop@@
+ Stop the server.
+ The server daemon exits.
+
+
+@@UAHL@unbound-control.commands@reload@@
+ Reload the server.
+ This flushes the cache and reads the config file fresh.
+
+
+@@UAHL@unbound-control.commands@reload_keep_cache@@
+ Reload the server but try to keep the RRset and message cache if
+ (re)configuration allows for it.
+ That means the caches sizes and the number of threads must not change
+ between reloads.
+
+
+@@UAHL@unbound-control.commands@fast_reload@@ [``+dpv``]
+ Reload the server, but keep downtime to a minimum, so that user queries
+ keep seeing service.
+ This needs the code compiled with threads.
+ The config is loaded in a thread, and prepared, then it briefly pauses the
+ existing server and updates config options.
+ The intent is that the pause does not impact the service of user queries.
+ The cache is kept.
+ Also user queries worked on are kept and continue, but with the new config
+ options.
+
+ .. note::
+ This command is experimental at this time.
+
+ The amount of temporal memory needed during a fast_reload is twice the
+ amount needed for configuration.
+ This is because Unbound temporarily needs to store both current
+ configuration values and new ones while trying to fast_reload.
+ Zones loaded from disk (authority zones and RPZ zones) are included in such
+ memory needs.
+
+ Options that can be changed are for
+ :ref:`forwards<unbound.conf.forward>`,
+ :ref:`stubs<unbound.conf.stub>`,
+ :ref:`views<unbound.conf.view>`,
+ :ref:`authority zones<unbound.conf.auth>`,
+ :ref:`RPZ zones<unbound.conf.rpz>` and
+ :ref:`local zones<unbound.conf.local-zone>`.
+
+ Also
+ :ref:`access-control<unbound.conf.access-control>` and similar options,
+ :ref:`interface-action<unbound.conf.interface-action>` and similar
+ options and
+ :ref:`tcp-connection-limit<unbound.conf.tcp-connection-limit>`.
+ It can reload some
+ :ref:`define-tag<unbound.conf.define-tag>`
+ changes, more on that below.
+ Further options include
+ :ref:`insecure-lan-zones<unbound.conf.insecure-lan-zones>`,
+ :ref:`domain-insecure<unbound.conf.domain-insecure>`,
+ :ref:`trust-anchor-file<unbound.conf.trust-anchor-file>`,
+ :ref:`trust-anchor<unbound.conf.trust-anchor>`,
+ :ref:`trusted-keys-file<unbound.conf.trusted-keys-file>`,
+ :ref:`auto-trust-anchor-file<unbound.conf.auto-trust-anchor-file>`,
+ :ref:`edns-client-string<unbound.conf.edns-client-string>`,
+ ipset,
+ :ref:`log-identity<unbound.conf.log-identity>`,
+ :ref:`infra-cache-numhosts<unbound.conf.infra-cache-numhosts>`,
+ :ref:`msg-cache-size<unbound.conf.msg-cache-size>`,
+ :ref:`rrset-cache-size<unbound.conf.rrset-cache-size>`,
+ :ref:`key-cache-size<unbound.conf.key-cache-size>`,
+ :ref:`ratelimit-size<unbound.conf.ratelimit-size>`,
+ :ref:`neg-cache-size<unbound.conf.neg-cache-size>`,
+ :ref:`num-queries-per-thread<unbound.conf.num-queries-per-thread>`,
+ :ref:`jostle-timeout<unbound.conf.jostle-timeout>`,
+ :ref:`use-caps-for-id<unbound.conf.use-caps-for-id>`,
+ :ref:`unwanted-reply-threshold<unbound.conf.unwanted-reply-threshold>`,
+ :ref:`tls-use-sni<unbound.conf.tls-use-sni>`,
+ :ref:`outgoing-tcp-mss<unbound.conf.outgoing-tcp-mss>`,
+ :ref:`ip-dscp<unbound.conf.ip-dscp>`,
+ :ref:`max-reuse-tcp-queries<unbound.conf.max-reuse-tcp-queries>`,
+ :ref:`tcp-reuse-timeout<unbound.conf.tcp-reuse-timeout>`,
+ :ref:`tcp-auth-query-timeout<unbound.conf.tcp-auth-query-timeout>`,
+ :ref:`delay-close<unbound.conf.delay-close>`.
+
+ It does not work with
+ :ref:`interface<unbound.conf.interface>` and
+ :ref:`outgoing-interface<unbound.conf.outgoing-interface>` changes,
+ also not with
+ :ref:`remote control<unbound.conf.remote>`,
+ :ref:`outgoing-port-permit<unbound.conf.outgoing-port-permit>`,
+ :ref:`outgoing-port-avoid<unbound.conf.outgoing-port-avoid>`,
+ :ref:`msg-buffer-size<unbound.conf.msg-buffer-size>`,
+ any **\*-slabs** options and
+ :ref:`statistics-interval<unbound.conf.statistics-interval>` changes.
+
+ For :ref:`dnstap<unbound.conf.dnstap>` these options can be changed:
+ :ref:`dnstap-log-resolver-query-messages<unbound.conf.dnstap.dnstap-log-resolver-query-messages>`,
+ :ref:`dnstap-log-resolver-response-messages<unbound.conf.dnstap.dnstap-log-resolver-response-messages>`,
+ :ref:`dnstap-log-client-query-messages<unbound.conf.dnstap.dnstap-log-client-query-messages>`,
+ :ref:`dnstap-log-client-response-messages<unbound.conf.dnstap.dnstap-log-client-response-messages>`,
+ :ref:`dnstap-log-forwarder-query-messages<unbound.conf.dnstap.dnstap-log-forwarder-query-messages>` and
+ :ref:`dnstap-log-forwarder-response-messages<unbound.conf.dnstap.dnstap-log-forwarder-response-messages>`.
+
+ It does not work with these options:
+ :ref:`dnstap-enable<unbound.conf.dnstap.dnstap-enable>`,
+ :ref:`dnstap-bidirectional<unbound.conf.dnstap.dnstap-bidirectional>`,
+ :ref:`dnstap-socket-path<unbound.conf.dnstap.dnstap-socket-path>`,
+ :ref:`dnstap-ip<unbound.conf.dnstap.dnstap-ip>`,
+ :ref:`dnstap-tls<unbound.conf.dnstap.dnstap-tls>`,
+ :ref:`dnstap-tls-server-name<unbound.conf.dnstap.dnstap-tls-server-name>`,
+ :ref:`dnstap-tls-cert-bundle<unbound.conf.dnstap.dnstap-tls-cert-bundle>`,
+ :ref:`dnstap-tls-client-key-file<unbound.conf.dnstap.dnstap-tls-client-key-file>` and
+ :ref:`dnstap-tls-client-cert-file<unbound.conf.dnstap.dnstap-tls-client-cert-file>`.
+
+ The options
+ :ref:`dnstap-send-identity<unbound.conf.dnstap.dnstap-send-identity>`,
+ :ref:`dnstap-send-version<unbound.conf.dnstap.dnstap-send-version>`,
+ :ref:`dnstap-identity<unbound.conf.dnstap.dnstap-identity>`, and
+ :ref:`dnstap-version<unbound.conf.dnstap.dnstap-version>` can be loaded
+ when ``+p`` is not used.
+
+ The ``+v`` option makes the output verbose which includes the time it took
+ to do the reload.
+ With ``+vv`` it is more verbose which includes the amount of memory that
+ was allocated temporarily to perform the reload; this amount of memory can
+ be big if the config has large contents.
+ In the timing output the 'reload' time is the time during which the server
+ was paused.
+
+ The ``+p`` option makes the reload not pause threads, they keep running.
+ Locks are acquired, but items are updated in sequence, so it is possible
+ for threads to see an inconsistent state with some options from the old
+ and some options from the new config, such as cache TTL parameters from the
+ old config and forwards from the new config.
+ The stubs and forwards are updated at the same time, so that they are
+ viewed consistently, either old or new values together.
+ The option makes the reload time take eg. 3 microseconds instead of 0.3
+ milliseconds during which the worker threads are interrupted.
+ So, the interruption is much shorter, at the expense of some inconsistency.
+ After the reload itself, every worker thread is briefly contacted to make
+ them release resources, this makes the delete timing a little longer, and
+ takes up time from the remote control servicing worker thread.
+
+ With the nopause option (``+p``), the reload does not work to reload some
+ options, that fast reload works on without the nopause option:
+ :ref:`val-bogus-ttl<unbound.conf.val-bogus-ttl>`,
+ :ref:`val-override-date<unbound.conf.val-override-date>`,
+ :ref:`val-sig-skew-min<unbound.conf.val-sig-skew-min>`,
+ :ref:`val-sig-skew-max<unbound.conf.val-sig-skew-max>`,
+ :ref:`val-max-restart<unbound.conf.val-max-restart>`,
+ :ref:`val-nsec3-keysize-iterations<unbound.conf.val-nsec3-keysize-iterations>`,
+ :ref:`target-fetch-policy<unbound.conf.target-fetch-policy>`,
+ :ref:`outbound-msg-retry<unbound.conf.outbound-msg-retry>`,
+ :ref:`max-sent-count<unbound.conf.max-sent-count>`,
+ :ref:`max-query-restarts<unbound.conf.max-query-restarts>`,
+ :ref:`do-not-query-address<unbound.conf.do-not-query-address>`,
+ :ref:`do-not-query-localhost<unbound.conf.do-not-query-localhost>`,
+ :ref:`private-address<unbound.conf.private-address>`,
+ :ref:`private-domain<unbound.conf.private-domain>`,
+ :ref:`caps-exempt<unbound.conf.caps-exempt>`,
+ :ref:`nat64-prefix<unbound.conf.nat64.nat64-prefix>`,
+ :ref:`do-nat64<unbound.conf.nat64.do-nat64>`,
+ :ref:`infra-host-ttl<unbound.conf.infra-host-ttl>`,
+ :ref:`infra-keep-probing<unbound.conf.infra-keep-probing>`,
+ :ref:`ratelimit<unbound.conf.ratelimit>`,
+ :ref:`ip-ratelimit<unbound.conf.ip-ratelimit>`,
+ :ref:`ip-ratelimit-cookie<unbound.conf.ip-ratelimit-cookie>`,
+ :ref:`wait-limit-netblock<unbound.conf.wait-limit-netblock>`,
+ :ref:`wait-limit-cookie-netblock<unbound.conf.wait-limit-cookie-netblock>`,
+ :ref:`ratelimit-below-domain<unbound.conf.ratelimit-below-domain>`,
+ :ref:`ratelimit-for-domain<unbound.conf.ratelimit-for-domain>`.
+
+ The ``+d`` option makes the reload drop queries that the worker threads are
+ working on.
+ This is like
+ :ref:`flush_requestlist<unbound-control.commands.flush_requestlist>`.
+ Without it the queries are kept so that users keep getting answers for
+ those queries that are currently processed.
+ The drop makes it so that queries during the life time of the
+ query processing see only old, or only new config options.
+
+ When there are changes to the config tags, from the
+ :ref:`define-tag<unbound.conf.define-tag>` option,
+ then the ``+d`` option is implicitly turned on with a warning printout, and
+ queries are dropped.
+ This is to stop references to the old tag information, by the old
+ queries.
+ If the number of tags is increased in the newly loaded config, by
+ adding tags at the end, then the implicit ``+d`` option is not needed.
+
+ For response ip, that is actions associated with IP addresses, and perhaps
+ intersected with access control tag and action information, those settings
+ are stored with a query when it comes in based on its source IP address.
+ The old information is kept with the query until the queries are done.
+ This is gone when those queries are resolved and finished, or it is
+ possible to flush the requestlist with ``+d``.
+
+
+@@UAHL@unbound-control.commands@verbosity@@ *number*
+ Change verbosity value for logging.
+ Same values as the **verbosity:** keyword in
+ :doc:`unbound.conf(5)</manpages/unbound.conf>`.
+ This new setting lasts until the server is issued a reload (taken from
+ config file again), or the next verbosity control command.
+
+
+@@UAHL@unbound-control.commands@log_reopen@@
+ Reopen the logfile, close and open it.
+ Useful for logrotation to make the daemon release the file it is logging
+ to.
+ If you are using syslog it will attempt to close and open the syslog (which
+ may not work if chrooted).
+
+
+@@UAHL@unbound-control.commands@stats@@
+ Print statistics.
+ Resets the internal counters to zero, this can be controlled using the
+ **statistics-cumulative:** config statement.
+ Statistics are printed with one ``[name]: [value]`` per line.
+
+
+@@UAHL@unbound-control.commands@stats_noreset@@
+ Peek at statistics.
+ Prints them like the stats command does, but does not reset the internal
+ counters to zero.
+
+
+@@UAHL@unbound-control.commands@status@@
+ Display server status.
+ Exit code 3 if not running (the connection to the port is refused), 1 on
+ error, 0 if running.
+
+
+@@UAHL@unbound-control.commands@local_zone@@ *name type*
+ Add new local zone with name and type.
+ Like local-zone config statement.
+ If the zone already exists, the type is changed to the given argument.
+
+
+@@UAHL@unbound-control.commands@local_zone_remove@@ *name*
+ Remove the local zone with the given name.
+ Removes all local data inside it.
+ If the zone does not exist, the command succeeds.
+
+
+@@UAHL@unbound-control.commands@local_data@@ *RR data...*
+ Add new local data, the given resource record.
+ Like **local-data:** keyword, except for when no covering zone exists.
+ In that case this remote control command creates a transparent zone with
+ the same name as this record.
+
+
+@@UAHL@unbound-control.commands@local_data_remove@@ *name*
+ Remove all RR data from local name.
+ If the name already has no items, nothing happens.
+ Often results in NXDOMAIN for the name (in a static zone), but if the name
+ has become an empty nonterminal (there is still data in domain names below
+ the removed name), NOERROR nodata answers are the result for that name.
+
+
+@@UAHL@unbound-control.commands@local_zones@@
+ Add local zones read from stdin of unbound-control.
+ Input is read per line, with name space type on a line.
+ For bulk additions.
+
+
+@@UAHL@unbound-control.commands@local_zones_remove@@
+ Remove local zones read from stdin of unbound-control.
+ Input is one name per line.
+ For bulk removals.
+
+
+@@UAHL@unbound-control.commands@local_datas@@
+ Add local data RRs read from stdin of unbound-control.
+ Input is one RR per line.
+ For bulk additions.
+
+
+@@UAHL@unbound-control.commands@local_datas_remove@@
+ Remove local data RRs read from stdin of unbound-control.
+ Input is one name per line.
+ For bulk removals.
+
+
+@@UAHL@unbound-control.commands@dump_cache@@
+ The contents of the cache is printed in a text format to stdout.
+ You can redirect it to a file to store the cache in a file.
+ Not supported in remote Unbounds in multi-process operation.
+
+
+@@UAHL@unbound-control.commands@load_cache@@
+ The contents of the cache is loaded from stdin.
+ Uses the same format as dump_cache uses.
+ Loading the cache with old, or wrong data can result in old or wrong data
+ returned to clients.
+ Loading data into the cache in this way is supported in order to aid with
+ debugging.
+ Not supported in remote Unbounds in multi-process operation.
+
+
+@@UAHL@unbound-control.commands@lookup@@ *name*
+ Print to stdout the name servers that would be used to look up the name
+ specified.
+
+
+@@UAHL@unbound-control.commands@flush@@ [``+c``] *name*
+ Remove the name from the cache.
+ Removes the types A, AAAA, NS, SOA, CNAME, DNAME, MX, PTR, SRV, NAPTR,
+ SVCB and HTTPS.
+ Because that is fast to do.
+ Other record types can be removed using **flush_type** or **flush_zone**.
+
+ The ``+c`` option removes the items also from the cachedb cache.
+ If cachedb is in use.
+
+
+@@UAHL@unbound-control.commands@flush_type@@ [``+c``] *name type*
+ Remove the name, type information from the cache.
+
+ The ``+c`` option removes the items also from the cachedb cache.
+ If cachedb is in use.
+
+
+@@UAHL@unbound-control.commands@flush_zone@@ [``+c``] name
+ Remove all information at or below the name from the cache.
+ The rrsets and key entries are removed so that new lookups will be
+ performed.
+ This needs to walk and inspect the entire cache, and is a slow operation.
+ The entries are set to expired in the implementation of this command (so,
+ with serve-expired enabled, it'll serve that information but schedule a
+ prefetch for new information).
+
+ The ``+c`` option removes the items also from the cachedb cache.
+ If cachedb is in use.
+
+
+@@UAHL@unbound-control.commands@flush_bogus@@ [``+c``]
+ Remove all bogus data from the cache.
+
+ The ``+c`` option removes the items also from the cachedb cache.
+ If cachedb is in use.
+
+
+@@UAHL@unbound-control.commands@flush_negative@@ [``+c``]
+ Remove all negative data from the cache.
+ This is nxdomain answers, nodata answers and servfail answers.
+ Also removes bad key entries (which could be due to failed lookups) from
+ the dnssec key cache, and iterator last-resort lookup failures from the
+ rrset cache.
+
+ The ``+c`` option removes the items also from the cachedb cache.
+ If cachedb is in use.
+
+
+@@UAHL@unbound-control.commands@flush_stats@@
+ Reset statistics to zero.
+
+
+@@UAHL@unbound-control.commands@flush_requestlist@@
+ Drop the queries that are worked on.
+ Stops working on the queries that the server is working on now.
+ The cache is unaffected.
+ No reply is sent for those queries, probably making those users request
+ again later.
+ Useful to make the server restart working on queries with new settings,
+ such as a higher verbosity level.
+
+
+@@UAHL@unbound-control.commands@dump_requestlist@@
+ Show what is worked on.
+ Prints all queries that the server is currently working on.
+ Prints the time that users have been waiting.
+ For internal requests, no time is printed.
+ And then prints out the module status.
+ This prints the queries from the first thread, and not queries that are
+ being serviced from other threads.
+
+
+@@UAHL@unbound-control.commands@flush_infra@@ *all|IP*
+ If all then entire infra cache is emptied.
+ If a specific IP address, the entry for that address is removed from the
+ cache.
+ It contains EDNS, ping and lameness data.
+
+
+@@UAHL@unbound-control.commands@dump_infra@@
+ Show the contents of the infra cache.
+
+
+@@UAHL@unbound-control.commands@set_option@@ *opt: val*
+ Set the option to the given value without a reload.
+ The cache is therefore not flushed.
+ The option must end with a ``':'`` and whitespace must be between the
+ option and the value.
+ Some values may not have an effect if set this way, the new values are not
+ written to the config file, not all options are supported.
+ This is different from the set_option call in libunbound, where all values
+ work because Unbound has not been initialized.
+
+ The values that work are: statistics-interval, statistics-cumulative,
+ do-not-query-localhost, harden-short-bufsize, harden-large-queries,
+ harden-glue, harden-dnssec-stripped, harden-below-nxdomain,
+ harden-referral-path, prefetch, prefetch-key, log-queries, hide-identity,
+ hide-version, identity, version, val-log-level, val-log-squelch,
+ ignore-cd-flag, add-holddown, del-holddown, keep-missing, tcp-upstream,
+ ssl-upstream, max-udp-size, ratelimit, ip-ratelimit, cache-max-ttl,
+ cache-min-ttl, cache-max-negative-ttl.
+
+
+@@UAHL@unbound-control.commands@get_option@@ *opt*
+ Get the value of the option.
+ Give the option name without a trailing ``':'``.
+ The value is printed.
+ If the value is ``""``, nothing is printed and the connection closes.
+ On error ``'error ...'`` is printed (it gives a syntax error on unknown
+ option).
+ For some options a list of values, one on each line, is printed.
+ The options are shown from the config file as modified with set_option.
+ For some options an override may have been taken that does not show up with
+ this command, not results from e.g. the verbosity and forward control
+ commands.
+ Not all options work, see list_stubs, list_forwards, list_local_zones and
+ list_local_data for those.
+
+
+@@UAHL@unbound-control.commands@list_stubs@@
+ List the stub zones in use.
+ These are printed one by one to the output.
+ This includes the root hints in use.
+
+
+@@UAHL@unbound-control.commands@list_forwards@@
+ List the forward zones in use.
+ These are printed zone by zone to the output.
+
+
+@@UAHL@unbound-control.commands@list_insecure@@
+ List the zones with domain-insecure.
+
+
+@@UAHL@unbound-control.commands@list_local_zones@@
+ List the local zones in use.
+ These are printed one per line with zone type.
+
+
+@@UAHL@unbound-control.commands@list_local_data@@
+ List the local data RRs in use.
+ The resource records are printed.
+
+
+@@UAHL@unbound-control.commands@insecure_add@@ *zone*
+ Add a domain-insecure for the given zone, like the statement in
+ unbound.conf.
+ Adds to the running Unbound without affecting the cache
+ contents (which may still be bogus, use flush_zone to remove it), does not
+ affect the config file.
+
+
+@@UAHL@unbound-control.commands@insecure_remove@@ *zone*
+ Removes domain-insecure for the given zone.
+
+
+@@UAHL@unbound-control.commands@forward_add@@ [``+it``] *zone addr ...*
+ Add a new forward zone to running Unbound.
+ With ``+i`` option also adds a domain-insecure for the zone (so it can
+ resolve insecurely if you have a DNSSEC root trust anchor configured for
+ other names).
+ The addr can be IP4, IP6 or nameserver names, like forward-zone config in
+ unbound.conf.
+ The ``+t`` option sets it to use TLS upstream, like
+ :ref:`forward-tls-upstream: yes<unbound.conf.forward.forward-tls-upstream>`.
+
+
+@@UAHL@unbound-control.commands@forward_remove@@ [``+i``] *zone*
+ Remove a forward zone from running Unbound.
+ The ``+i`` also removes a domain-insecure for the zone.
+
+
+@@UAHL@unbound-control.commands@stub_add@@ [``+ipt``] *zone addr ...*
+ Add a new stub zone to running Unbound.
+ With ``+i`` option also adds a domain-insecure for the zone.
+ With ``+p`` the stub zone is set to prime, without it it is set to
+ notprime.
+ The addr can be IP4, IP6 or nameserver names, like the **stub-zone:**
+ config in unbound.conf.
+ The ``+t`` option sets it to use TLS upstream, like
+ :ref:`stub-tls-upstream: yes<unbound.conf.stub.stub-tls-upstream>`.
+
+
+@@UAHL@unbound-control.commands@stub_remove@@ [``+i``] *zone*
+ Remove a stub zone from running Unbound.
+ The ``+i`` also removes a domain-insecure for the zone.
+
+
+@@UAHL@unbound-control.commands@forward@@ [*off* | *addr ...* ]
+ Setup forwarding mode.
+ Configures if the server should ask other upstream nameservers, should go
+ to the internet root nameservers itself, or show the current config.
+ You could pass the nameservers after a DHCP update.
+
+ Without arguments the current list of addresses used to forward all queries
+ to is printed.
+ On startup this is from the forward-zone ``"."`` configuration.
+ Afterwards it shows the status.
+ It prints off when no forwarding is used.
+
+ If off is passed, forwarding is disabled and the root nameservers are
+ used.
+ This can be used to avoid to avoid buggy or non-DNSSEC supporting
+ nameservers returned from DHCP.
+ But may not work in hotels or hotspots.
+
+ If one or more IPv4 or IPv6 addresses are given, those are then used to
+ forward queries to.
+ The addresses must be separated with spaces.
+ With ``'@port'`` the port number can be set explicitly (default port is 53
+ (DNS)).
+
+ By default the forwarder information from the config file for the root
+ ``"."`` is used.
+ The config file is not changed, so after a reload these changes are gone.
+ Other forward zones from the config file are not affected by this command.
+
+
+@@UAHL@unbound-control.commands@ratelimit_list@@ [``+a``]
+ List the domains that are ratelimited.
+ Printed one per line with current estimated qps and qps limit from config.
+ With ``+a`` it prints all domains, not just the ratelimited domains, with
+ their estimated qps.
+ The ratelimited domains return an error for uncached (new) queries, but
+ cached queries work as normal.
+
+
+@@UAHL@unbound-control.commands@ip_ratelimit_list@@ [``+a``]
+ List the ip addresses that are ratelimited.
+ Printed one per line with current estimated qps and qps limit from config.
+ With ``+a`` it prints all ips, not just the ratelimited ips, with their
+ estimated qps.
+ The ratelimited ips are dropped before checking the cache.
+
+
+@@UAHL@unbound-control.commands@list_auth_zones@@
+ List the auth zones that are configured.
+ Printed one per line with a status, indicating if the zone is expired and
+ current serial number.
+ Configured RPZ zones are included.
+
+
+@@UAHL@unbound-control.commands@auth_zone_reload@@ *zone*
+ Reload the auth zone (or RPZ zone) from zonefile.
+ The zonefile is read in overwriting the current contents of the zone in
+ memory.
+ This changes the auth zone contents itself, not the cache contents.
+ Such cache contents exists if you set Unbound to validate with
+ **for-upstream: yes** and that can be cleared with **flush_zone** *zone*.
+
+
+@@UAHL@unbound-control.commands@auth_zone_transfer@@ *zone*
+ Transfer the auth zone (or RPZ zone) from master.
+ The auth zone probe sequence is started, where the masters are probed to
+ see if they have an updated zone (with the SOA serial check).
+ And then the zone is transferred for a newer zone version.
+
+
+@@UAHL@unbound-control.commands@rpz_enable@@ *zone*
+ Enable the RPZ zone if it had previously been disabled.
+
+
+@@UAHL@unbound-control.commands@rpz_disable@@ *zone*
+ Disable the RPZ zone.
+
+
+@@UAHL@unbound-control.commands@view_list_local_zones@@ *view*
+ *list_local_zones* for given view.
+
+
+@@UAHL@unbound-control.commands@view_local_zone@@ *view name type*
+ *local_zone* for given view.
+
+
+@@UAHL@unbound-control.commands@view_local_zone_remove@@ *view name*
+ *local_zone_remove* for given view.
+
+
+@@UAHL@unbound-control.commands@view_list_local_data@@ *view*
+ *list_local_data* for given view.
+
+
+@@UAHL@unbound-control.commands@view_local_data@@ *view RR data...*
+ *local_data* for given view.
+
+
+@@UAHL@unbound-control.commands@view_local_data_remove@@ *view name*
+ *local_data_remove* for given view.
+
+
+@@UAHL@unbound-control.commands@view_local_datas_remove@@ *view*
+ Remove a list of *local_data* for given view from stdin.
+ Like *local_datas_remove*.
+
+
+@@UAHL@unbound-control.commands@view_local_datas@@ *view*
+ Add a list of *local_data* for given view from stdin.
+ Like *local_datas*.
+
+
+@@UAHL@unbound-control.commands@add_cookie_secret@@ *secret*
+ Add or replace a cookie secret persistently.
+ *secret* needs to be an 128 bit hex string.
+
+ Cookie secrets can be either **active** or **staging**.
+ **Active** cookie secrets are used to create DNS Cookies, but verification
+ of a DNS Cookie succeeds with any of the **active** or **staging** cookie
+ secrets.
+ The state of the current cookie secrets can be printed with the
+ :ref:`print_cookie_secrets<unbound-control.commands.print_cookie_secrets>`
+ command.
+
+ When there are no cookie secrets configured yet, the *secret* is added as
+ **active**.
+ If there is already an **active** cookie secret, the *secret* is added as
+ **staging** or replacing an existing **staging** secret.
+
+ To "roll" a cookie secret used in an anycast set.
+ The new secret has to be added as **staging** secret to **all** nodes in
+ the anycast set.
+ When **all** nodes can verify DNS Cookies with the new secret, the new
+ secret can be activated with the
+ :ref:`activate_cookie_secret<unbound-control.commands.activate_cookie_secret>`
+ command.
+ After **all** nodes have the new secret **active** for at least one hour,
+ the previous secret can be dropped with the
+ :ref:`drop_cookie_secret<unbound-control.commands.drop_cookie_secret>`
+ command.
+
+ Persistence is accomplished by writing to a file which is configured with
+ the
+ :ref:`cookie-secret-file<unbound.conf.cookie-secret-file>`
+ option in the server section of the config file.
+ This is disabled by default, "".
+
+
+@@UAHL@unbound-control.commands@drop_cookie_secret@@
+ Drop the **staging** cookie secret.
+
+
+@@UAHL@unbound-control.commands@activate_cookie_secret@@
+ Make the current **staging** cookie secret **active**, and the current
+ **active** cookie secret **staging**.
+
+
+@@UAHL@unbound-control.commands@print_cookie_secrets@@
+ Show the current configured cookie secrets with their status.
+
+Exit Code
+---------
+
+The ``unbound-control`` program exits with status code 1 on error, 0 on
+success.
+
+Set Up
+------
+
+The setup requires a self-signed certificate and private keys for both the
+server and client.
+The script ``unbound-control-setup`` generates these in the default run
+directory, or with ``-d`` in another directory.
+If you change the access control permissions on the key files you can decide
+who can use ``unbound-control``, by default owner and group but not all users.
+Run the script under the same username as you have configured in
+:file:`unbound.conf` or as root, so that the daemon is permitted to read the
+files, for example with:
+
+.. code-block:: bash
+
+ sudo -u unbound unbound-control-setup
+
+If you have not configured a username in :file:`unbound.conf`, the keys need
+read permission for the user credentials under which the daemon is started.
+The script preserves private keys present in the directory.
+After running the script as root, turn on
+:ref:`control-enable<unbound.conf.remote.control-enable>` in
+:file:`unbound.conf`.
+
+Statistic Counters
+------------------
+
+The :ref:`stats<unbound-control.commands.stats>` and
+:ref:`stats_noreset<unbound-control.commands.stats_noreset>` commands show a
+number of statistic counters:
+
+
+@@UAHL@unbound-control.stats@threadX.num.queries@@
+ number of queries received by thread
+
+
+@@UAHL@unbound-control.stats@threadX.num.queries_ip_ratelimited@@
+ number of queries rate limited by thread
+
+
+@@UAHL@unbound-control.stats@threadX.num.queries_cookie_valid@@
+ number of queries with a valid DNS Cookie by thread
+
+
+@@UAHL@unbound-control.stats@threadX.num.queries_cookie_client@@
+ number of queries with a client part only DNS Cookie by thread
+
+
+@@UAHL@unbound-control.stats@threadX.num.queries_cookie_invalid@@
+ number of queries with an invalid DNS Cookie by thread
+
+
+@@UAHL@unbound-control.stats@threadX.num.queries_discard_timeout@@
+ number of queries removed due to discard-timeout by thread
+
+
+@@UAHL@unbound-control.stats@threadX.num.queries_wait_limit@@
+ number of queries removed due to wait-limit by thread
+
+
+@@UAHL@unbound-control.stats@threadX.num.cachehits@@
+ number of queries that were successfully answered using a cache lookup
+
+
+@@UAHL@unbound-control.stats@threadX.num.cachemiss@@
+ number of queries that needed recursive processing
+
+
+@@UAHL@unbound-control.stats@threadX.num.dnscrypt.crypted@@
+ number of queries that were encrypted and successfully decapsulated by
+ dnscrypt.
+
+
+@@UAHL@unbound-control.stats@threadX.num.dnscrypt.cert@@
+ number of queries that were requesting dnscrypt certificates.
+
+
+@@UAHL@unbound-control.stats@threadX.num.dnscrypt.cleartext@@
+ number of queries received on dnscrypt port that were cleartext and not a
+ request for certificates.
+
+
+@@UAHL@unbound-control.stats@threadX.num.dnscrypt.malformed@@
+ number of request that were neither cleartext, not valid dnscrypt messages.
+
+
+@@UAHL@unbound-control.stats@threadX.num.dns_error_reports@@
+ number of DNS Error Reports generated by thread
+
+
+@@UAHL@unbound-control.stats@threadX.num.prefetch@@
+ number of cache prefetches performed.
+ This number is included in cachehits, as the original query had the
+ unprefetched answer from cache, and resulted in recursive processing,
+ taking a slot in the requestlist.
+ Not part of the recursivereplies (or the histogram thereof) or cachemiss,
+ as a cache response was sent.
+
+
+@@UAHL@unbound-control.stats@threadX.num.expired@@
+ number of replies that served an expired cache entry.
+
+
+@@UAHL@unbound-control.stats@threadX.num.queries_timed_out@@
+ number of queries that are dropped because they waited in the UDP socket
+ buffer for too long.
+
+
+@@UAHL@unbound-control.stats@threadX.query.queue_time_us.max@@
+ The maximum wait time for packets in the socket buffer, in microseconds.
+ This is only reported when
+ :ref:`sock-queue-timeout<unbound.conf.sock-queue-timeout>` is enabled.
+
+
+@@UAHL@unbound-control.stats@threadX.num.recursivereplies@@
+ The number of replies sent to queries that needed recursive processing.
+ Could be smaller than threadX.num.cachemiss if due to timeouts no replies
+ were sent for some queries.
+
+
+@@UAHL@unbound-control.stats@threadX.requestlist.avg@@
+ The average number of requests in the internal recursive processing request
+ list on insert of a new incoming recursive processing query.
+
+
+@@UAHL@unbound-control.stats@threadX.requestlist.max@@
+ Maximum size attained by the internal recursive processing request list.
+
+
+@@UAHL@unbound-control.stats@threadX.requestlist.overwritten@@
+ Number of requests in the request list that were overwritten by newer
+ entries.
+ This happens if there is a flood of queries that recursive processing and
+ the server has a hard time.
+
+
+@@UAHL@unbound-control.stats@threadX.requestlist.exceeded@@
+ Queries that were dropped because the request list was full.
+ This happens if a flood of queries need recursive processing, and the
+ server can not keep up.
+
+
+@@UAHL@unbound-control.stats@threadX.requestlist.current.all@@
+ Current size of the request list, includes internally generated queries
+ (such as priming queries and glue lookups).
+
+
+@@UAHL@unbound-control.stats@threadX.requestlist.current.user@@
+ Current size of the request list, only the requests from client queries.
+
+
+@@UAHL@unbound-control.stats@threadX.recursion.time.avg@@
+ Average time it took to answer queries that needed recursive processing.
+ Note that queries that were answered from the cache are not in this average.
+
+
+@@UAHL@unbound-control.stats@threadX.recursion.time.median@@
+ The median of the time it took to answer queries that needed recursive
+ processing.
+ The median means that 50% of the user queries were answered in less than
+ this time.
+ Because of big outliers (usually queries to non responsive servers), the
+ average can be bigger than the median.
+ This median has been calculated by interpolation from a histogram.
+
+
+@@UAHL@unbound-control.stats@threadX.tcpusage@@
+ The currently held tcp buffers for incoming connections.
+ A spot value on the time of the request.
+ This helps you spot if the incoming-num-tcp buffers are full.
+
+
+@@UAHL@unbound-control.stats@total.num.queries@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.queries_ip_ratelimited@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.queries_cookie_valid@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.queries_cookie_client@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.queries_cookie_invalid@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.queries_discard_timeout@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.queries_wait_limit@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.cachehits@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.cachemiss@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.dnscrypt.crypted@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.dnscrypt.cert@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.dnscrypt.cleartext@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.dnscrypt.malformed@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.dns_error_reports@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.prefetch@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.expired@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.num.queries_timed_out@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.query.queue_time_us.max@@
+ the maximum of the thread values.
+
+
+@@UAHL@unbound-control.stats@total.num.recursivereplies@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.requestlist.avg@@
+ averaged over threads.
+
+
+@@UAHL@unbound-control.stats@total.requestlist.max@@
+ the maximum of the thread requestlist.max values.
+
+
+@@UAHL@unbound-control.stats@total.requestlist.overwritten@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.requestlist.exceeded@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.requestlist.current.all@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@total.recursion.time.median@@
+ averaged over threads.
+
+
+@@UAHL@unbound-control.stats@total.tcpusage@@
+ summed over threads.
+
+
+@@UAHL@unbound-control.stats@time.now@@
+ current time in seconds since 1970.
+
+
+@@UAHL@unbound-control.stats@time.up@@
+ uptime since server boot in seconds.
+
+
+@@UAHL@unbound-control.stats@time.elapsed@@
+ time since last statistics printout, in seconds.
+
+Extended Statistics
+-------------------
+
+
+@@UAHL@unbound-control.stats@mem.cache.rrset@@
+ Memory in bytes in use by the RRset cache.
+
+
+@@UAHL@unbound-control.stats@mem.cache.message@@
+ Memory in bytes in use by the message cache.
+
+
+@@UAHL@unbound-control.stats@mem.cache.dnscrypt_shared_secret@@
+ Memory in bytes in use by the dnscrypt shared secrets cache.
+
+
+@@UAHL@unbound-control.stats@mem.cache.dnscrypt_nonce@@
+ Memory in bytes in use by the dnscrypt nonce cache.
+
+
+@@UAHL@unbound-control.stats@mem.mod.iterator@@
+ Memory in bytes in use by the iterator module.
+
+
+@@UAHL@unbound-control.stats@mem.mod.validator@@
+ Memory in bytes in use by the validator module.
+ Includes the key cache and negative cache.
+
+
+@@UAHL@unbound-control.stats@mem.streamwait@@
+ Memory in bytes in used by the TCP and TLS stream wait buffers.
+ These are answers waiting to be written back to the clients.
+
+
+@@UAHL@unbound-control.stats@mem.http.query_buffer@@
+ Memory in bytes used by the HTTP/2 query buffers.
+ Containing (partial) DNS queries waiting for request stream completion.
+
+
+@@UAHL@unbound-control.stats@mem.http.response_buffer@@
+ Memory in bytes used by the HTTP/2 response buffers.
+ Containing DNS responses waiting to be written back to the clients.
+
+
+@@UAHL@unbound-control.stats@mem.quic@@
+ Memory in bytes used by QUIC.
+ Containing connection information, stream information, queries read and
+ responses written back to the clients.
+
+@@UAHL@unbound-control.stats@histogram@@.<sec>.<usec>.to.<sec>.<usec>
+ Shows a histogram, summed over all threads.
+ Every element counts the recursive queries whose reply time fit between the
+ lower and upper bound.
+ Times larger or equal to the lowerbound, and smaller than the upper bound.
+ There are 40 buckets, with bucket sizes doubling.
+
+
+@@UAHL@unbound-control.stats@num.query.type.A@@
+ The total number of queries over all threads with query type A.
+ Printed for the other query types as well, but only for the types for which
+ queries were received, thus =0 entries are omitted for brevity.
+
+
+@@UAHL@unbound-control.stats@num.query.type.other@@
+ Number of queries with query types 256-65535.
+
+
+@@UAHL@unbound-control.stats@num.query.class.IN@@
+ The total number of queries over all threads with query class IN
+ (internet).
+ Also printed for other classes (such as CH (CHAOS) sometimes used for
+ debugging), or NONE, ANY, used by dynamic update.
+ num.query.class.other is printed for classes 256-65535.
+
+
+@@UAHL@unbound-control.stats@num.query.opcode.QUERY@@
+ The total number of queries over all threads with query opcode QUERY.
+ Also printed for other opcodes, UPDATE, ...
+
+
+@@UAHL@unbound-control.stats@num.query.tcp@@
+ Number of queries that were made using TCP towards the Unbound server.
+
+
+@@UAHL@unbound-control.stats@num.query.tcpout@@
+ Number of queries that the Unbound server made using TCP outgoing towards
+ other servers.
+
+
+@@UAHL@unbound-control.stats@num.query.udpout@@
+ Number of queries that the Unbound server made using UDP outgoing towards
+ other servers.
+
+
+@@UAHL@unbound-control.stats@num.query.tls@@
+ Number of queries that were made using TLS towards the Unbound server.
+ These are also counted in num.query.tcp, because TLS uses TCP.
+
+
+@@UAHL@unbound-control.stats@num.query.tls.resume@@
+ Number of TLS session resumptions, these are queries over TLS towards the
+ Unbound server where the client negotiated a TLS session resumption key.
+
+
+@@UAHL@unbound-control.stats@num.query.https@@
+ Number of queries that were made using HTTPS towards the Unbound server.
+ These are also counted in num.query.tcp and num.query.tls, because HTTPS
+ uses TLS and TCP.
+
+
+@@UAHL@unbound-control.stats@num.query.quic@@
+ Number of queries that were made using QUIC towards the Unbound server.
+ These are also counted in num.query.tls, because TLS is used for these
+ queries.
+
+
+@@UAHL@unbound-control.stats@num.query.ipv6@@
+ Number of queries that were made using IPv6 towards the Unbound server.
+
+
+@@UAHL@unbound-control.stats@num.query.flags.RD@@
+ The number of queries that had the RD flag set in the header.
+ Also printed for flags QR, AA, TC, RA, Z, AD, CD.
+ Note that queries with flags QR, AA or TC may have been rejected because of
+ that.
+
+
+@@UAHL@unbound-control.stats@num.query.edns.present@@
+ number of queries that had an EDNS OPT record present.
+
+
+@@UAHL@unbound-control.stats@num.query.edns.DO@@
+ number of queries that had an EDNS OPT record with the DO (DNSSEC OK) bit
+ set.
+ These queries are also included in the num.query.edns.present number.
+
+
+@@UAHL@unbound-control.stats@num.query.ratelimited@@
+ The number of queries that are turned away from being send to nameserver
+ due to ratelimiting.
+
+
+@@UAHL@unbound-control.stats@num.query.dnscrypt.shared_secret.cachemiss@@
+ The number of dnscrypt queries that did not find a shared secret in the
+ cache.
+ This can be use to compute the shared secret hitrate.
+
+
+@@UAHL@unbound-control.stats@num.query.dnscrypt.replay@@
+ The number of dnscrypt queries that found a nonce hit in the nonce cache
+ and hence are considered a query replay.
+
+
+@@UAHL@unbound-control.stats@num.answer.rcode.NXDOMAIN@@
+ The number of answers to queries, from cache or from recursion, that had
+ the return code NXDOMAIN.
+ Also printed for the other return codes.
+
+
+@@UAHL@unbound-control.stats@num.answer.rcode.nodata@@
+ The number of answers to queries that had the pseudo return code nodata.
+ This means the actual return code was NOERROR, but additionally, no data
+ was carried in the answer (making what is called a NOERROR/NODATA answer).
+ These queries are also included in the num.answer.rcode.NOERROR number.
+ Common for AAAA lookups when an A record exists, and no AAAA.
+
+
+@@UAHL@unbound-control.stats@num.answer.secure@@
+ Number of answers that were secure.
+ The answer validated correctly.
+ The AD bit might have been set in some of these answers, where the client
+ signalled (with DO or AD bit in the query) that they were ready to accept
+ the AD bit in the answer.
+
+
+@@UAHL@unbound-control.stats@num.answer.bogus@@
+ Number of answers that were bogus.
+ These answers resulted in SERVFAIL to the client because the answer failed
+ validation.
+
+
+@@UAHL@unbound-control.stats@num.rrset.bogus@@
+ The number of rrsets marked bogus by the validator.
+ Increased for every RRset inspection that fails.
+
+
+@@UAHL@unbound-control.stats@unwanted.queries@@
+ Number of queries that were refused or dropped because they failed the
+ access control settings.
+
+
+@@UAHL@unbound-control.stats@unwanted.replies@@
+ Replies that were unwanted or unsolicited.
+ Could have been random traffic, delayed duplicates, very late answers, or
+ could be spoofing attempts.
+ Some low level of late answers and delayed duplicates are to be expected
+ with the UDP protocol.
+ Very high values could indicate a threat (spoofing).
+
+
+@@UAHL@unbound-control.stats@msg.cache.count@@
+ The number of items (DNS replies) in the message cache.
+
+
+@@UAHL@unbound-control.stats@rrset.cache.count@@
+ The number of RRsets in the rrset cache.
+ This includes rrsets used by the messages in the message cache, but also
+ delegation information.
+
+
+@@UAHL@unbound-control.stats@infra.cache.count@@
+ The number of items in the infra cache.
+ These are IP addresses with their timing and protocol support information.
+
+
+@@UAHL@unbound-control.stats@key.cache.count@@
+ The number of items in the key cache.
+ These are DNSSEC keys, one item per delegation point, and their validation
+ status.
+
+
+@@UAHL@unbound-control.stats@msg.cache.max_collisions@@
+ The maximum number of hash table collisions in the msg cache.
+ This is the number of hashes that are identical when a new element is
+ inserted in the hash table.
+ If the value is very large, like hundreds, something is wrong with the
+ performance of the hash table, hash values are incorrect or malicious.
+
+
+@@UAHL@unbound-control.stats@rrset.cache.max_collisions@@
+ The maximum number of hash table collisions in the rrset cache.
+ This is the number of hashes that are identical when a new element is
+ inserted in the hash table.
+ If the value is very large, like hundreds, something is wrong with the
+ performance of the hash table, hash values are incorrect or malicious.
+
+
+@@UAHL@unbound-control.stats@dnscrypt_shared_secret.cache.count@@
+ The number of items in the shared secret cache.
+ These are precomputed shared secrets for a given client public key/server
+ secret key pair.
+ Shared secrets are CPU intensive and this cache allows Unbound to avoid
+ recomputing the shared secret when multiple dnscrypt queries are sent from
+ the same client.
+
+
+@@UAHL@unbound-control.stats@dnscrypt_nonce.cache.count@@
+ The number of items in the client nonce cache.
+ This cache is used to prevent dnscrypt queries replay.
+ The client nonce must be unique for each client public key/server secret
+ key pair.
+ This cache should be able to host QPS * `replay window` interval keys to
+ prevent replay of a query during `replay window` seconds.
+
+
+@@UAHL@unbound-control.stats@num.query.authzone.up@@
+ The number of queries answered from auth-zone data, upstream queries.
+ These queries would otherwise have been sent (with fallback enabled) to the
+ internet, but are now answered from the auth zone.
+
+
+@@UAHL@unbound-control.stats@num.query.authzone.down@@
+ The number of queries for downstream answered from auth-zone data.
+ These queries are from downstream clients, and have had an answer from the
+ data in the auth zone.
+
+
+@@UAHL@unbound-control.stats@num.query.aggressive.NOERROR@@
+ The number of queries answered using cached NSEC records with NODATA RCODE.
+ These queries would otherwise have been sent to the internet, but are now
+ answered using cached data.
+
+
+@@UAHL@unbound-control.stats@num.query.aggressive.NXDOMAIN@@
+ The number of queries answered using cached NSEC records with NXDOMAIN
+ RCODE.
+ These queries would otherwise have been sent to the internet, but are now
+ answered using cached data.
+
+
+@@UAHL@unbound-control.stats@num.query.subnet@@
+ Number of queries that got an answer that contained EDNS client subnet
+ data.
+
+
+@@UAHL@unbound-control.stats@num.query.subnet_cache@@
+ Number of queries answered from the edns client subnet cache.
+ These are counted as cachemiss by the main counters, but hit the client
+ subnet specific cache after getting processed by the edns client subnet
+ module.
+
+
+@@UAHL@unbound-control.stats@num.query.cachedb@@
+ Number of queries answered from the external cache of cachedb.
+ These are counted as cachemiss by the main counters, but hit the cachedb
+ external cache after getting processed by the cachedb module.
+
+@@UAHL@unbound-control.stats@num.rpz.action@@.<rpz_action>
+ Number of queries answered using configured RPZ policy, per RPZ action
+ type.
+ Possible actions are: nxdomain, nodata, passthru, drop, tcp-only,
+ local-data, disabled, and cname-override.
+
+Files
+-----
+
+@ub_conf_file@
+ Unbound configuration file.
+
+@UNBOUND_RUN_DIR@
+ directory with private keys (:file:`unbound_server.key` and
+ :file:`unbound_control.key`) and self-signed certificates
+ (:file:`unbound_server.pem` and :file:`unbound_control.pem`).
+
+See Also
+--------
+
+:doc:`unbound.conf(5)</manpages/unbound.conf>`,
+:doc:`unbound(8)</manpages/unbound>`.
-.TH "unbound\-host" "1" "@date@" "NLnet Labs" "unbound @version@"
-.\"
-.\" unbound-host.1 -- unbound DNS lookup utility
-.\"
-.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
-.\"
-.\" See LICENSE for the license.
-.\"
-.\"
-.SH "NAME"
-.B unbound\-host
-\- unbound DNS lookup utility
-.SH "SYNOPSIS"
-.B unbound\-host
-.RB [ \-C
-.IR configfile ]
-.RB [ \-vdhr46D ]
-.RB [ \-c
-.IR class ]
-.RB [ \-t
-.IR type ]
-.RB [ \-y
-.IR key ]
-.RB [ \-f
-.IR keyfile ]
-.RB [ \-F
-.IR namedkeyfile ]
-.I hostname
-.SH "DESCRIPTION"
-.B Unbound\-host
-uses the Unbound validating resolver to query for the hostname and display
-results. With the \fB\-v\fR option it displays validation
-status: secure, insecure, bogus (security failure).
-.P
-By default it reads no configuration file whatsoever. It attempts to reach
-the internet root servers. With \fB\-C\fR an Unbound config file and with
-\fB\-r\fR resolv.conf can be read.
-.P
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "UNBOUND-HOST" "1" "@date@" "@version@" "Unbound"
+.SH NAME
+unbound-host \- Unbound @version@ DNS lookup utility.
+.SH SYNOPSIS
+.sp
+\fBunbound\-host\fP [\fB\-C configfile\fP] [\fB\-vdhr46D\fP] [\fB\-c class\fP]
+[\fB\-t type\fP] [\fB\-y key\fP] [\fB\-f keyfile\fP] [\fB\-F namedkeyfile\fP] hostname
+.SH DESCRIPTION
+.sp
+\fBunbound\-host\fP uses the Unbound validating resolver to query for the hostname
+and display results.
+With the \fI\%\-v\fP option it displays validation status: secure, insecure,
+bogus (security failure).
+.sp
+By default it reads no configuration file whatsoever.
+It attempts to reach the internet root servers.
+With \fI\%\-C\fP an unbound config file and with \fI\%\-r\fP \fBresolv.conf\fP
+can be read.
+.sp
The available options are:
+.INDENT 0.0
.TP
-.I hostname
+.B hostname
This name is resolved (looked up in the DNS).
If a IPv4 or IPv6 address is given, a reverse lookup is performed.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-h
Show the version and commandline option help.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-v
Enable verbose output and it shows validation results, on every line.
-Secure means that the NXDOMAIN (no such domain name), nodata (no such data)
-or positive data response validated correctly with one of the keys.
+Secure means that the NXDOMAIN (no such domain name), nodata (no such
+data) or positive data response validated correctly with one of the
+keys.
Insecure means that that domain name has no security set up for it.
-Bogus (security failure) means that the response failed one or more checks,
-it is likely wrong, outdated, tampered with, or broken.
+Bogus (security failure) means that the response failed one or more
+checks, it is likely wrong, outdated, tampered with, or broken.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-d
-Enable debug output to stderr. One \-d shows what the resolver and validator
-are doing and may tell you what is going on. More times, \-d \-d, gives a
-lot of output, with every packet sent and received.
+Enable debug output to stderr.
+One \fI\%\-d\fP shows what the resolver and validator are doing and may
+tell you what is going on.
+More times, \fI\%\-d\fP \fI\%\-d\fP, gives a lot of output, with every
+packet sent and received.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-c \fIclass
-Specify the class to lookup for, the default is IN the internet class.
+.B \-c <class>
+Specify the class to lookup for, the default is IN the internet
+class.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-t \fItype
-Specify the type of data to lookup. The default looks for IPv4, IPv6 and
-mail handler data, or domain name pointers for reverse queries.
+.B \-t <type>
+Specify the type of data to lookup.
+The default looks for IPv4, IPv6 and mail handler data, or domain name
+pointers for reverse queries.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-y \fIkey
-Specify a public key to use as trust anchor. This is the base for a chain
-of trust that is built up from the trust anchor to the response, in order
-to validate the response message. Can be given as a DS or DNSKEY record.
-For example \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD".
+.B \-y <key>
+Specify a public key to use as trust anchor.
+This is the base for a chain of trust that is built up from the trust
+anchor to the response, in order to validate the response message.
+Can be given as a DS or DNSKEY record.
+For example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-y \(dqexample.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD\(dq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
.TP
.B \-D
-Enables DNSSEC validation. Reads the root anchor from the default configured
-root anchor at the default location, \fI@UNBOUND_ROOTKEY_FILE@\fR.
+Enables DNSSEC validation.
+Reads the root anchor from the default configured root anchor at the
+default location, \fB@UNBOUND_ROOTKEY_FILE@\fP\&.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-f \fIkeyfile
-Reads keys from a file. Every line has a DS or DNSKEY record, in the format
-as for \-y. The zone file format, the same as dig and drill produce.
+.B \-f <keyfile>
+Reads keys from a file.
+Every line has a DS or DNSKEY record, in the format as for \fI\%\-y\fP\&.
+The zone file format, the same as \fBdig\fP and \fBdrill\fP produce.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-F \fInamedkeyfile
-Reads keys from a BIND\-style named.conf file. Only the trusted\-key {}; entries
-are read.
+.B \-F <namedkeyfile>
+Reads keys from a BIND\-style \fBnamed.conf\fP file.
+Only the \fBtrusted\-key {};\fP entries are read.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-C \fIconfigfile
-Uses the specified unbound.conf to prime
-.IR libunbound (3).
+.B \-C <configfile>
+Uses the specified unbound.conf to prime \fI\%libunbound(3)\fP\&.
Pass it as first argument if you want to override some options from the
config file with further arguments on the commandline.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-r
-Read /etc/resolv.conf, and use the forward DNS servers from there (those could
-have been set by DHCP). More info in
-.IR resolv.conf (5).
+Read \fB/etc/resolv.conf\fP, and use the forward DNS servers from
+there (those could have been set by DHCP).
+More info in \fIresolv.conf(5)\fP\&.
Breaks validation if those servers do not support DNSSEC.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-4
Use solely the IPv4 network for sending packets.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-6
Use solely the IPv6 network for sending packets.
-.SH "EXAMPLES"
-Some examples of use. The keys shown below are fakes, thus a security failure
-is encountered.
-.P
+.UNINDENT
+.SH EXAMPLES
+.sp
+Some examples of use.
+The keys shown below are fakes, thus a security failure is encountered.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
$ unbound\-host www.example.com
-.P
-$ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" www.example.com
-.P
-$ unbound\-host \-v \-y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" 192.0.2.153
-.SH "EXIT CODE"
-The unbound\-host program exits with status code 1 on error,
-0 on no error. The data may not be available on exit code 0, exit code 1
-means the lookup encountered a fatal error.
-.SH "SEE ALSO"
-\fIunbound.conf\fR(5),
-\fIunbound\fR(8).
+
+$ unbound\-host \-v \-y \(dqexample.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD\(dq www.example.com
+
+$ unbound\-host \-v \-y \(dqexample.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD\(dq 192.0.2.153
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH EXIT CODE
+.sp
+The \fBunbound\-host\fP program exits with status code 1 on error, 0 on no error.
+The data may not be available on exit code 0, exit code 1 means the lookup
+encountered a fatal error.
+.SH SEE ALSO
+.sp
+\fI\%unbound.conf(5)\fP,
+\fI\%unbound(8)\fP\&.
+.SH AUTHOR
+Unbound developers are mentioned in the CREDITS file in the distribution.
+.SH COPYRIGHT
+1999-2025, NLnet Labs
+.\" Generated by docutils manpage writer.
+.
--- /dev/null
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+.. program:: unbound-host
+
+unbound-host(1)
+===============
+
+Synopsis
+--------
+
+**unbound-host** [``-C configfile``] [``-vdhr46D``] [``-c class``]
+[``-t type``] [``-y key``] [``-f keyfile``] [``-F namedkeyfile``] hostname
+
+Description
+-----------
+
+``unbound-host`` uses the Unbound validating resolver to query for the hostname
+and display results.
+With the :option:`-v` option it displays validation status: secure, insecure,
+bogus (security failure).
+
+By default it reads no configuration file whatsoever.
+It attempts to reach the internet root servers.
+With :option:`-C` an unbound config file and with :option:`-r` ``resolv.conf``
+can be read.
+
+The available options are:
+
+.. option:: hostname
+
+ This name is resolved (looked up in the DNS).
+ If a IPv4 or IPv6 address is given, a reverse lookup is performed.
+
+.. option:: -h
+
+ Show the version and commandline option help.
+
+.. option:: -v
+
+ Enable verbose output and it shows validation results, on every line.
+ Secure means that the NXDOMAIN (no such domain name), nodata (no such
+ data) or positive data response validated correctly with one of the
+ keys.
+ Insecure means that that domain name has no security set up for it.
+ Bogus (security failure) means that the response failed one or more
+ checks, it is likely wrong, outdated, tampered with, or broken.
+
+.. option:: -d
+
+ Enable debug output to stderr.
+ One :option:`-d` shows what the resolver and validator are doing and may
+ tell you what is going on.
+ More times, :option:`-d` :option:`-d`, gives a lot of output, with every
+ packet sent and received.
+
+.. option:: -c <class>
+
+ Specify the class to lookup for, the default is IN the internet
+ class.
+
+.. option:: -t <type>
+
+ Specify the type of data to lookup.
+ The default looks for IPv4, IPv6 and mail handler data, or domain name
+ pointers for reverse queries.
+
+.. option:: -y <key>
+
+ Specify a public key to use as trust anchor.
+ This is the base for a chain of trust that is built up from the trust
+ anchor to the response, in order to validate the response message.
+ Can be given as a DS or DNSKEY record.
+ For example:
+
+ .. code-block:: text
+
+ -y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD"
+
+.. option:: -D
+
+ Enables DNSSEC validation.
+ Reads the root anchor from the default configured root anchor at the
+ default location, :file:`@UNBOUND_ROOTKEY_FILE@`.
+
+.. option:: -f <keyfile>
+
+ Reads keys from a file.
+ Every line has a DS or DNSKEY record, in the format as for :option:`-y`.
+ The zone file format, the same as ``dig`` and ``drill`` produce.
+
+.. option:: -F <namedkeyfile>
+
+ Reads keys from a BIND-style :file:`named.conf` file.
+ Only the ``trusted-key {};`` entries are read.
+
+.. option:: -C <configfile>
+
+ Uses the specified unbound.conf to prime :doc:`libunbound(3)</manpages/libunbound>`.
+ Pass it as first argument if you want to override some options from the
+ config file with further arguments on the commandline.
+
+.. option:: -r
+
+ Read :file:`/etc/resolv.conf`, and use the forward DNS servers from
+ there (those could have been set by DHCP).
+ More info in *resolv.conf(5)*.
+ Breaks validation if those servers do not support DNSSEC.
+
+.. option:: -4
+
+ Use solely the IPv4 network for sending packets.
+
+.. option:: -6
+
+ Use solely the IPv6 network for sending packets.
+
+Examples
+--------
+
+Some examples of use.
+The keys shown below are fakes, thus a security failure is encountered.
+
+.. code-block:: text
+
+ $ unbound-host www.example.com
+
+ $ unbound-host -v -y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" www.example.com
+
+ $ unbound-host -v -y "example.com DS 31560 5 1 1CFED84787E6E19CCF9372C1187325972FE546CD" 192.0.2.153
+
+Exit Code
+---------
+
+The ``unbound-host`` program exits with status code 1 on error, 0 on no error.
+The data may not be available on exit code 0, exit code 1 means the lookup
+encountered a fatal error.
+
+See Also
+--------
+
+:doc:`unbound.conf(5)</manpages/unbound.conf>`,
+:doc:`unbound(8)</manpages/unbound>`.
-.TH "unbound" "8" "@date@" "NLnet Labs" "unbound @version@"
-.\"
-.\" unbound.8 -- unbound manual
-.\"
-.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
-.\"
-.\" See LICENSE for the license.
-.\"
-.\"
-.SH "NAME"
-.B unbound
-\- Unbound DNS validating resolver @version@.
-.SH "SYNOPSIS"
-.B unbound
-.RB [ \-h ]
-.RB [ \-d ]
-.RB [ \-p ]
-.RB [ \-v ]
-.RB [ \-c
-.IR cfgfile ]
-.SH "DESCRIPTION"
-.B Unbound
-is a caching DNS resolver.
-.P
-It uses a built in list of authoritative nameservers for the root zone (.),
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "UNBOUND" "8" "@date@" "@version@" "Unbound"
+.SH NAME
+unbound \- Unbound DNS validating resolver @version@.
+.SH SYNOPSIS
+.sp
+\fBunbound\fP [\fB\-hdpv\fP] [\fB\-c <cfgfile>\fP]
+.SH DESCRIPTION
+.sp
+\fBunbound\fP is a caching DNS resolver.
+.sp
+It uses a built in list of authoritative nameservers for the root zone (\fB\&.\fP),
the so called root hints.
-On receiving a DNS query it will ask the root nameservers for
-an answer and will in almost all cases receive a delegation to a top level
-domain (TLD) authoritative nameserver.
+On receiving a DNS query it will ask the root nameservers for an answer and
+will in almost all cases receive a delegation to a top level domain (TLD)
+authoritative nameserver.
It will then ask that nameserver for an answer.
-It will recursively continue until an answer is found or no answer is
-available (NXDOMAIN).
-For performance and efficiency reasons that answer is cached for a
-certain time (the answer's time\-to\-live or TTL).
+It will recursively continue until an answer is found or no answer is available
+(NXDOMAIN).
+For performance and efficiency reasons that answer is cached for a certain time
+(the answer\(aqs time\-to\-live or TTL).
A second query for the same name will then be answered from the cache.
Unbound can also do DNSSEC validation.
-.P
-To use a locally running
-.B Unbound
-for resolving put
.sp
-.RS 6n
+To use a locally running Unbound for resolving put:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
nameserver 127.0.0.1
-.RE
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+into \fIresolv.conf(5)\fP\&.
+.sp
+If authoritative DNS is needed as well using \fI\%nsd(8)\fP,
+careful setup is required because authoritative nameservers and resolvers are
+using the same port number (53).
.sp
-into
-.IR resolv.conf (5).
-.P
-If authoritative DNS is needed as well using
-.IR nsd (8),
-careful setup is required because authoritative nameservers and
-resolvers are using the same port number (53).
-.P
The available options are:
+.INDENT 0.0
.TP
.B \-h
Show the version number and commandline option help, and exit.
+.UNINDENT
+.INDENT 0.0
.TP
-.B \-c\fI cfgfile
-Set the config file with settings for Unbound to read instead of reading the
-file at the default location, @ub_conf_file@. The syntax is
-described in \fIunbound.conf\fR(5).
+.B \-c <cfgfile>
+Set the config file with settings for unbound to read instead of reading the
+file at the default location, \fB@ub_conf_file@\fP\&.
+The syntax is described in \fI\%unbound.conf(5)\fP\&.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-d
-Debug flag: do not fork into the background, but stay attached to
-the console. This flag will also delay writing to the log file until
-the thread\-spawn time, so that most config and setup errors appear on
-stderr. If given twice or more, logging does not switch to the log file
-or to syslog, but the log messages are printed to stderr all the time.
+Debug flag: do not fork into the background, but stay attached to the
+console.
+This flag will also delay writing to the log file until the thread\-spawn
+time, so that most config and setup errors appear on stderr.
+If given twice or more, logging does not switch to the log file or to
+syslog, but the log messages are printed to stderr all the time.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-p
-Don't use a pidfile. This argument should only be used by supervision
-systems which can ensure that only one instance of Unbound will run
-concurrently.
+Don\(aqt use a pidfile.
+This argument should only be used by supervision systems which can ensure
+that only one instance of Unbound will run concurrently.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-v
-Increase verbosity. If given multiple times, more information is logged.
-This is added to the verbosity (if any) from the config file.
+Increase verbosity.
+If given multiple times, more information is logged.
+This is in addition to the verbosity (if any) from the config file.
+.UNINDENT
+.INDENT 0.0
.TP
.B \-V
Show the version number and build options, and exit.
-.SH "SEE ALSO"
-\fIunbound.conf\fR(5),
-\fIunbound\-checkconf\fR(8),
-\fInsd\fR(8).
-.SH "AUTHORS"
-.B Unbound
-developers are mentioned in the CREDITS file in the distribution.
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fI\%unbound.conf(5)\fP,
+\fI\%unbound\-checkconf(8)\fP,
+\fI\%nsd(8)\fP\&.
+.SH AUTHOR
+Unbound developers are mentioned in the CREDITS file in the distribution.
+.SH COPYRIGHT
+1999-2025, NLnet Labs
+.\" Generated by docutils manpage writer.
+.
-.TH "unbound.conf" "5" "@date@" "NLnet Labs" "unbound @version@"
-.\"
-.\" unbound.conf.5 -- unbound.conf manual
-.\"
-.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
-.\"
-.\" See LICENSE for the license.
-.\"
-.\"
-.SH "NAME"
-.B unbound.conf
-\- Unbound configuration file.
-.SH "SYNOPSIS"
-.B unbound.conf
-.SH "DESCRIPTION"
-.B unbound.conf
-is used to configure
-\fIunbound\fR(8).
-The file format has attributes and values. Some attributes have attributes
-inside them.
-The notation is: attribute: value.
-.P
-Comments start with # and last to the end of line. Empty lines are
-ignored as is whitespace at the beginning of a line.
-.P
-The utility
-\fIunbound\-checkconf\fR(8)
-can be used to check unbound.conf prior to usage.
-.SH "EXAMPLE"
-An example config file is shown below. Copy this to /etc/unbound/unbound.conf
-and start the server with:
-.P
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "UNBOUND.CONF" "5" "@date@" "@version@" "Unbound"
+.SH NAME
+unbound.conf \- Unbound @version@ configuration file.
+.SH SYNOPSIS
+.sp
+\fBunbound.conf\fP
+.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 EXAMPLE
+.sp
+An example config file is shown below.
+Copy this to \fB/etc/unbound/unbound.conf\fP and start the server with:
+.INDENT 0.0
+.INDENT 3.5
+.sp
.nf
- $ unbound \-c /etc/unbound/unbound.conf
+.ft C
+$ unbound \-c /etc/unbound/unbound.conf
+.ft P
.fi
-.P
-Most settings are the defaults. Stop the server with:
-.P
+.UNINDENT
+.UNINDENT
+.sp
+Most settings are the defaults.
+Stop the server with:
+.INDENT 0.0
+.INDENT 3.5
+.sp
.nf
- $ kill `cat /etc/unbound/unbound.pid`
+.ft C
+$ kill \(gacat /etc/unbound/unbound.pid\(ga
+.ft P
.fi
-.P
-Below is a minimal config file. The source distribution contains an extensive
-example.conf file with all the options.
-.P
+.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
+.INDENT 3.5
+.sp
.nf
+.ft C
# unbound.conf(5) config file for unbound(8).
server:
- directory: "/etc/unbound"
- username: unbound
- # make sure unbound can access entropy from inside the chroot.
- # e.g. on linux the use these commands (on BSD, devfs(8) is used):
- # mount \-\-bind \-n /dev/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"
- # verbosity: 1 # uncomment and increase to get more logging.
- # listen on all interfaces, answer queries from the local subnet.
- interface: 0.0.0.0
- interface: ::0
- access\-control: 10.0.0.0/8 allow
- access\-control: 2001:DB8::/64 allow
+ directory: \(dq/etc/unbound\(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
+ # verbosity: 1 # uncomment and increase to get more logging.
+ # listen on all interfaces, answer queries from the local subnet.
+ interface: 0.0.0.0
+ interface: ::0
+ access\-control: 10.0.0.0/8 allow
+ access\-control: 2001:DB8::/64 allow
+.ft P
.fi
-.SH "FILE FORMAT"
-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.
-.P
-Files can be included using the
-.B include:
-directive. It can appear anywhere, it accepts a single file name as argument.
-Processing continues as if the text from the included file was copied into
-the config file at that point. If also using chroot, using full path names
-for the included files works, relative pathnames for the included names work
-if the directory where the daemon is started equals its chroot/working
-directory or is specified before the include statement with directory: dir.
-Wildcards can be used to include multiple files, see \fIglob\fR(7).
-.P
-For a more structural include option, the
-.B 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.
-.SS "Server Options"
-These options are part of the
-.B server:
-clause.
-.TP
-.B verbosity: \fI<number>
-The verbosity number, level 0 means no verbosity, only errors. Level 1
-gives operational information. Level 2 gives detailed operational
-information including short information per query. Level 3 gives query level
-information, output per query. Level 4 gives algorithm level information.
-Level 5 logs client identification for cache misses. Default is level 1.
-The verbosity can also be increased from the commandline, see \fIunbound\fR(8).
-.TP
-.B statistics\-interval: \fI<seconds>
-The number of seconds between printing statistics to the log for every thread.
-Disable with value 0 or "". Default is disabled. The histogram statistics
-are only printed if replies were sent during the statistics interval,
-requestlist statistics are printed for every interval (but can be 0).
+.UNINDENT
+.UNINDENT
+.SH FILE FORMAT
+.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.
+.sp
+Files can be included using the \fBinclude:\fP directive.
+It can appear anywhere, it accepts a single file name as argument.
+Processing continues as if the text from the included file was copied into the
+config file at that point.
+If also using \fI\%chroot\fP, using full path names for
+the included files works, relative pathnames for the included names work if the
+directory where the daemon is started equals its chroot/working directory or is
+specified before the include statement with \fI\%directory:
+dir\fP\&.
+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
+.sp
+These options are part of the \fBserver:\fP clause.
+.INDENT 0.0
+.TP
+.B verbosity: \fI<number>\fP
+The verbosity level.
+.INDENT 7.0
+.TP
+.B Level 0
+No verbosity, only errors.
+.TP
+.B Level 1
+Gives operational information.
+.TP
+.B Level 2
+Gives detailed operational information including short information per
+query.
+.TP
+.B Level 3
+Gives query level information, output per query.
+.TP
+.B Level 4
+Gives algorithm level information.
+.TP
+.B Level 5
+Logs client identification for cache misses.
+.UNINDENT
+.sp
+The verbosity can also be increased from the command line and during run
+time via remote control. See \fI\%unbound(8)\fP and
+\fI\%unbound\-control(8)\fP respectively.
+.sp
+Default: 1
+.UNINDENT
+.INDENT 0.0
+.TP
+.B statistics\-interval: \fI<seconds>\fP
+The number of seconds between printing statistics to the log for every
+thread.
+Disable with value \fB0\fP or \fB\(dq\(dq\fP\&.
+The histogram statistics are only printed if replies were sent during the
+statistics interval, requestlist statistics are printed for every interval
+(but can be 0).
This is because the median calculation requires data to be present.
-.TP
-.B statistics\-cumulative: \fI<yes or no>
-If enabled, statistics are cumulative since starting Unbound, without clearing
-the statistics counters after logging the statistics. Default is no.
-.TP
-.B extended\-statistics: \fI<yes or no>
-If enabled, extended statistics are printed from \fIunbound\-control\fR(8).
-Default is off, because keeping track of more statistics takes time. The
-counters are listed in \fIunbound\-control\fR(8).
-.TP
-.B statistics\-inhibit\-zero: \fI<yes or no>
-If enabled, selected extended statistics with a value of 0 are inhibited from
-printing with \fIunbound\-control\fR(8).
+.sp
+Default: 0 (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B statistics\-cumulative: \fI<yes or no>\fP
+If enabled, statistics are cumulative since starting Unbound, without
+clearing the statistics counters after logging the statistics.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B extended\-statistics: \fI<yes or no>\fP
+If enabled, extended statistics are printed from
+\fI\%unbound\-control(8)\fP\&.
+The counters are listed in
+\fI\%unbound\-control(8)\fP\&.
+Keeping track of more statistics takes time.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B statistics\-inhibit\-zero: \fI<yes or no>\fP
+If enabled, selected extended statistics with a value of 0 are inhibited
+from printing with
+\fI\%unbound\-control(8)\fP\&.
These are query types, query classes, query opcodes, answer rcodes
-(except NOERROR, FORMERR, SERVFAIL, NXDOMAIN, NOTIMPL, REFUSED) and
-RPZ actions.
-Default is on.
-.TP
-.B num\-threads: \fI<number>
+(except NOERROR, FORMERR, SERVFAIL, NXDOMAIN, NOTIMPL, REFUSED)
+and PRZ actions.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num\-threads: \fI<number>\fP
The number of threads to create to serve clients. Use 1 for no threading.
-.TP
-.B port: \fI<port number>
-The port number, default 53, on which the server responds to queries.
-.TP
-.B interface: \fI<ip address or interface name [@port]>
-Interface to use to connect to the network. This interface is listened to
-for queries from clients, and answers to clients are given from it.
-Can be given multiple times to work on several interfaces. If none are
-given the default is to listen to localhost. If an interface name is used
-instead of an ip address, the list of ip addresses on that interface are used.
-The interfaces are not changed on a reload (kill \-HUP) but only on restart.
-A port number can be specified with @port (without spaces between
-interface and port number), if not specified the default port (from
-\fBport\fR) is used.
-.TP
-.B ip\-address: \fI<ip address or interface name [@port]>
-Same as interface: (for ease of compatibility with nsd.conf).
-.TP
-.B interface\-automatic: \fI<yes or no>
+.sp
+Default: 1
+.UNINDENT
+.INDENT 0.0
+.TP
+.B port: \fI<port number>\fP
+The port number on which the server responds to queries.
+.sp
+Default: 53
+.UNINDENT
+.INDENT 0.0
+.TP
+.B interface: \fI<IP address or interface name[@port]>\fP
+Interface to use to connect to the network.
+This interface is listened to for queries from clients, and answers to
+clients are given from it.
+Can be given multiple times to work on several interfaces.
+If none are given the default is to listen on localhost.
+.sp
+If an interface name is used instead of an IP address, the list of IP
+addresses on that interface are used.
+The interfaces are not changed on a reload (\fBkill \-HUP\fP) but only on
+restart.
+.sp
+A port number can be specified with @port (without spaces between interface
+and port number), if not specified the default port (from
+\fI\%port\fP) is used.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ip\-address: \fI<IP address or interface name[@port]>\fP
+Same as \fI\%interface\fP (for ease of
+compatibility with \fI\%nsd.conf(5)\fP).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B interface\-automatic: \fI<yes or no>\fP
Listen on all addresses on all (current and future) interfaces, detect the
-source interface on UDP queries and copy them to replies. This is a lot like
-ip\-transparent, but this option services all interfaces whilst with
-ip\-transparent you can select which (future) interfaces Unbound provides
-service on. This feature is experimental, and needs support in your OS for
-particular socket options. Default value is no.
-.TP
-.B interface\-automatic\-ports: \fI<string>
-List the port numbers that interface-automatic listens on. If empty, the
-default port is listened on. The port numbers are separated by spaces in the
-string. Default is "".
-.IP
+source interface on UDP queries and copy them to replies.
+This is a lot like \fI\%ip\-transparent\fP, but
+this option services all interfaces whilst with
+\fI\%ip\-transparent\fP you can select which
+(future) interfaces Unbound provides service on.
+This feature is experimental, and needs support in your OS for particular
+socket options.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B interface\-automatic\-ports: \fI\(dq<string>\(dq\fP
+List the port numbers that
+\fI\%interface\-automatic\fP listens on.
+If empty, the default port is listened on.
+The port numbers are separated by spaces in the string.
+.sp
This can be used to have interface automatic to deal with the interface,
and listen on the normal port number, by including it in the list, and
-also https or dns over tls port numbers by putting them in the list as well.
-.TP
-.B outgoing\-interface: \fI<ip address or ip6 netblock>
-Interface to use to connect to the network. This interface is used to send
-queries to authoritative servers and receive their replies. Can be given
-multiple times to work on several interfaces. If none are given the
-default (all) is used. You can specify the same interfaces in
-.B interface:
-and
-.B outgoing\-interface:
-lines, the interfaces are then used for both purposes. Outgoing queries are
-sent via a random outgoing interface to counter spoofing.
-.IP
+also HTTPS or DNS\-over\-TLS port numbers by putting them in the list as
+well.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B outgoing\-interface: \fI<IPv4/IPv6 address or IPv6 netblock>\fP
+Interface to use to connect to the network.
+This interface is used to send queries to authoritative servers and receive
+their replies.
+Can be given multiple times to work on several interfaces.
+If none are given the default (all) is used.
+You can specify the same interfaces in
+\fI\%interface\fP and
+\fI\%outgoing\-interface\fP lines, the
+interfaces are then used for both purposes.
+Outgoing queries are sent via a random outgoing interface to counter
+spoofing.
+.sp
If an IPv6 netblock is specified instead of an individual IPv6 address,
outgoing UDP queries will use a randomised source address taken from the
-netblock to counter spoofing. Requires the IPv6 netblock to be routed to the
-host running Unbound, and requires OS support for unprivileged non-local binds
-(currently only supported on Linux). Several netblocks may be specified with
-multiple
-.B outgoing\-interface:
-options, but do not specify both an individual IPv6 address and an IPv6
-netblock, or the randomisation will be compromised. Consider combining with
-.B prefer\-ip6: yes
-to increase the likelihood of IPv6 nameservers being selected for queries.
+netblock to counter spoofing.
+Requires the IPv6 netblock to be routed to the host running Unbound, and
+requires OS support for unprivileged non\-local binds (currently only
+supported on Linux).
+Several netblocks may be specified with multiple
+\fI\%outgoing\-interface\fP options, but do
+not specify both an individual IPv6 address and an IPv6 netblock, or the
+randomisation will be compromised.
+Consider combining with \fI\%prefer\-ip6: yes\fP to
+increase the likelihood of IPv6 nameservers being selected for queries.
On Linux you need these two commands to be able to use the freebind socket
option to receive traffic for the ip6 netblock:
-ip \-6 addr add mynetblock/64 dev lo &&
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ip \-6 addr add mynetblock/64 dev lo && \e
ip \-6 route add local mynetblock/64 dev lo
-.TP
-.B outgoing\-range: \fI<number>
-Number of ports to open. This number of file descriptors can be opened per
-thread. Must be at least 1. Default depends on compile options. Larger
-numbers need extra resources from the operating system. For performance a
-very large value is best, use libevent to make this possible.
-.TP
-.B outgoing\-port\-permit: \fI<port number or range>
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B outgoing\-range: \fI<number>\fP
+Number of ports to open.
+This number of file descriptors can be opened per thread.
+Must be at least 1.
+Default depends on compile options.
+Larger numbers need extra resources from the operating system.
+For performance a very large value is best, use libevent to make this
+possible.
+.sp
+Default: 4096 (libevent) / 960 (minievent) / 48 (windows)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B outgoing\-port\-permit: \fI<port number or range>\fP
Permit Unbound to open this port or range of ports for use to send queries.
A larger number of permitted outgoing ports increases resilience against
-spoofing attempts. Make sure these ports are not needed by other daemons.
-By default only ports above 1024 that have not been assigned by IANA are used.
-Give a port number or a range of the form "low\-high", without spaces.
-.IP
-The \fBoutgoing\-port\-permit\fR and \fBoutgoing\-port\-avoid\fR statements
-are processed in the line order of the config file, adding the permitted ports
-and subtracting the avoided ports from the set of allowed ports. The
-processing starts with the non IANA allocated ports above 1024 in the set
-of allowed ports.
-.TP
-.B outgoing\-port\-avoid: \fI<port number or range>
+spoofing attempts.
+Make sure these ports are not needed by other daemons.
+By default only ports above 1024 that have not been assigned by IANA are
+used.
+Give a port number or a range of the form \(dqlow\-high\(dq, without spaces.
+.sp
+The \fI\%outgoing\-port\-permit\fP and
+\fI\%outgoing\-port\-avoid\fP statements
+are processed in the line order of the config file, adding the permitted
+ports and subtracting the avoided ports from the set of allowed ports.
+The processing starts with the non IANA allocated ports above 1024 in the
+set of allowed ports.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B outgoing\-port\-avoid: \fI<port number or range>\fP
Do not permit Unbound to open this port or range of ports for use to send
-queries. Use this to make sure Unbound does not grab a port that another
-daemon needs. The port is avoided on all outgoing interfaces, both IP4 and IP6.
-By default only ports above 1024 that have not been assigned by IANA are used.
-Give a port number or a range of the form "low\-high", without spaces.
-.TP
-.B outgoing\-num\-tcp: \fI<number>
-Number of outgoing TCP buffers to allocate per thread. Default is 10. If
-set to 0, or if do\-tcp is "no", no TCP queries to authoritative servers
-are done. For larger installations increasing this value is a good idea.
-.TP
-.B incoming\-num\-tcp: \fI<number>
-Number of incoming TCP buffers to allocate per thread. Default is
-10. If set to 0, or if do\-tcp is "no", no TCP queries from clients are
-accepted. For larger installations increasing this value is a good idea.
-.TP
-.B edns\-buffer\-size: \fI<number>
+queries.
+Use this to make sure Unbound does not grab a port that another daemon
+needs.
+The port is avoided on all outgoing interfaces, both IPv4 and IPv6.
+By default only ports above 1024 that have not been assigned by IANA are
+used.
+Give a port number or a range of the form \(dqlow\-high\(dq, without spaces.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B outgoing\-num\-tcp: \fI<number>\fP
+Number of outgoing TCP buffers to allocate per thread.
+If set to 0, or if \fI\%do\-tcp: no\fP is set, no TCP
+queries to authoritative servers are done.
+For larger installations increasing this value is a good idea.
+.sp
+Default: 10
+.UNINDENT
+.INDENT 0.0
+.TP
+.B incoming\-num\-tcp: \fI<number>\fP
+Number of incoming TCP buffers to allocate per thread.
+If set to 0, or if \fI\%do\-tcp: no\fP is set, no TCP
+queries from clients are accepted.
+For larger installations increasing this value is a good idea.
+.sp
+Default: 10
+.UNINDENT
+.INDENT 0.0
+.TP
+.B edns\-buffer\-size: \fI<number>\fP
Number of bytes size to advertise as the EDNS reassembly buffer size.
-This is the value put into datagrams over UDP towards peers. The actual
-buffer size is determined by msg\-buffer\-size (both for TCP and UDP). Do
-not set higher than that value. Default is 1232 which is the DNS Flag Day 2020
-recommendation. Setting to 512 bypasses even the most stringent path MTU
-problems, but is seen as extreme, since the amount of TCP fallback generated is
-excessive (probably also for this resolver, consider tuning the outgoing tcp
-number).
-.TP
-.B max\-udp\-size: \fI<number>
-Maximum UDP response size (not applied to TCP response). 65536 disables the
-udp response size maximum, and uses the choice from the client, always.
-Suggested values are 512 to 4096. Default is 1232. The default value is the
-same as the default for edns\-buffer\-size.
-.TP
-.B stream\-wait\-size: \fI<number>
-Number of bytes size maximum to use for waiting stream buffers. Default is
-4 megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes,
-megabytes or gigabytes (1024*1024 bytes in a megabyte). As TCP and TLS streams
-queue up multiple results, the amount of memory used for these buffers does
-not exceed this number, otherwise the responses are dropped. This manages
-the total memory usage of the server (under heavy use), the number of requests
-that can be queued up per connection is also limited, with further requests
-waiting in TCP buffers.
-.TP
-.B msg\-buffer\-size: \fI<number>
-Number of bytes size of the message buffers. Default is 65552 bytes, enough
-for 64 Kb packets, the maximum DNS message size. No message larger than this
-can be sent or received. Can be reduced to use less memory, but some requests
-for DNS data, such as for huge resource records, will result in a SERVFAIL
-reply to the client.
-.TP
-.B msg\-cache\-size: \fI<number>
-Number of bytes size of the message cache. Default is 4 megabytes.
-A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+This is the value put into datagrams over UDP towards peers.
+The actual buffer size is determined by
+\fI\%msg\-buffer\-size\fP (both for TCP and
+UDP).
+Do not set higher than that value.
+Setting to 512 bypasses even the most stringent path MTU problems, but is
+seen as extreme, since the amount of TCP fallback generated is excessive
+(probably also for this resolver, consider tuning
+\fI\%outgoing\-num\-tcp\fP).
+.sp
+Default: 1232 (\fI\%DNS Flag Day 2020 recommendation\fP)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B max\-udp\-size: \fI<number>\fP
+Maximum UDP response size (not applied to TCP response).
+65536 disables the UDP response size maximum, and uses the choice from the
+client, always.
+Suggested values are 512 to 4096.
+.sp
+Default: 1232 (same as \fI\%edns\-buffer\-size\fP)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stream\-wait\-size: \fI<number>\fP
+Number of bytes size maximum to use for waiting stream buffers.
+A plain number is in bytes, append \(aqk\(aq, \(aqm\(aq or \(aqg\(aq for kilobytes, megabytes
+or gigabytes (1024*1024 bytes in a megabyte).
+As TCP and TLS streams queue up multiple results, the amount of memory used
+for these buffers does not exceed this number, otherwise the responses are
+dropped.
+This manages the total memory usage of the server (under heavy use), the
+number of requests that can be queued up per connection is also limited,
+with further requests waiting in TCP buffers.
+.sp
+Default: 4m
+.UNINDENT
+.INDENT 0.0
+.TP
+.B msg\-buffer\-size: \fI<number>\fP
+Number of bytes size of the message buffers.
+Default is 65552 bytes, enough for 64 Kb packets, the maximum DNS message
+size.
+No message larger than this can be sent or received.
+Can be reduced to use less memory, but some requests for DNS data, such as
+for huge resource records, will result in a SERVFAIL reply to the client.
+.sp
+Default: 65552
+.UNINDENT
+.INDENT 0.0
+.TP
+.B msg\-cache\-size: \fI<number>\fP
+Number of bytes size of the message cache.
+A plain number is in bytes, append \(aqk\(aq, \(aqm\(aq or \(aqg\(aq for kilobytes, megabytes
or gigabytes (1024*1024 bytes in a megabyte).
+.sp
+Default: 4m
+.UNINDENT
+.INDENT 0.0
.TP
-.B msg\-cache\-slabs: \fI<number>
+.B msg\-cache\-slabs: \fI<number>\fP
Number of slabs in the message cache.
Slabs reduce lock contention by threads.
Must be set to a power of 2.
Setting (close) to the number of cpus is a fairly good setting.
-If left unconfigured, it will be configured automatically to be a power of 2
-close to the number of configured threads in multi-threaded environments.
-.TP
-.B num\-queries\-per\-thread: \fI<number>
+If left unconfigured, it will be configured automatically to be a power of
+2 close to the number of configured threads in multi\-threaded environments.
+.sp
+Default: (unconfigured)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B num\-queries\-per\-thread: \fI<number>\fP
The number of queries that every thread will service simultaneously.
-If more queries arrive that need servicing, and no queries can be jostled out
-(see \fIjostle\-timeout\fR), then the queries are dropped. This forces
-the client to resend after a timeout; allowing the server time to work on
-the existing queries. Default depends on compile options, 512 or 2048.
-.TP
-.B jostle\-timeout: \fI<msec>
-Timeout used when the server is very busy. Set to a value that usually
-results in one roundtrip to the authority servers. If too many queries
-arrive, then 50% of the queries are allowed to run to completion, and
-the other 50% are replaced with the new incoming query if they have already
-spent more than their allowed time. This protects against denial of
-service by slow queries or high query rates. Default 200 milliseconds.
-The effect is that the qps for long-lasting queries is about
-(numqueriesperthread / 2) / (average time for such long queries) qps.
-The qps for short queries can be about (numqueriesperthread / 2)
-/ (jostletimeout in whole seconds) qps per thread, about (2048/2)*5 = 5120
-qps by default.
-.TP
-.B delay\-close: \fI<msec>
+If more queries arrive that need servicing, and no queries can be jostled
+out (see \fI\%jostle\-timeout\fP), then the
+queries are dropped.
+This forces the client to resend after a timeout; allowing the server time
+to work on the existing queries.
+Default depends on compile options.
+.sp
+Default: 2048 (libevent) / 512 (minievent) / 24 (windows)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B jostle\-timeout: \fI<msec>\fP
+Timeout used when the server is very busy.
+Set to a value that usually results in one roundtrip to the authority
+servers.
+.sp
+If too many queries arrive, then 50% of the queries are allowed to run to
+completion, and the other 50% are replaced with the new incoming query if
+they have already spent more than their allowed time.
+This protects against denial of service by slow queries or high query
+rates.
+.sp
+The effect is that the qps for long\-lasting queries is about:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+(num\-queries\-per\-thread / 2) / (average time for such long queries) qps
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The qps for short queries can be about:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+(num\-queries\-per\-thread / 2) / (jostle\-timeout in whole seconds) qps per thread
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+about (2048/2)*5 = 5120 qps by default.
+.sp
+Default: 200
+.UNINDENT
+.INDENT 0.0
+.TP
+.B delay\-close: \fI<msec>\fP
Extra delay for timeouted UDP ports before they are closed, in msec.
-Default is 0, and that disables it. This prevents very delayed answer
-packets from the upstream (recursive) servers from bouncing against
-closed ports and setting off all sort of close-port counters, with
-eg. 1500 msec. When timeouts happen you need extra sockets, it checks
-the ID and remote IP of packets, and unwanted packets are added to the
-unwanted packet counter.
-.TP
-.B udp\-connect: \fI<yes or no>
-Perform connect for UDP sockets that mitigates ICMP side channel leakage.
-Default is yes.
-.TP
-.B unknown\-server\-time\-limit: \fI<msec>
+This prevents very delayed answer packets from the upstream (recursive)
+servers from bouncing against closed ports and setting off all sort of
+close\-port counters, with eg. 1500 msec.
+When timeouts happen you need extra sockets, it checks the ID and remote IP
+of packets, and unwanted packets are added to the unwanted packet counter.
+.sp
+Default: 0 (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B udp\-connect: \fI<yes or no>\fP
+Perform \fIconnect(2)\fP for UDP sockets that mitigates ICMP side channel
+leakage.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B unknown\-server\-time\-limit: \fI<msec>\fP
The wait time in msec for waiting for an unknown server to reply.
Increase this if you are behind a slow satellite link, to eg. 1128.
That would then avoid re\-querying every initial query because it times out.
-Default is 376 msec.
-.TP
-.B discard\-timeout: \fI<msec>
-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. It is nice to be a bit
-larger than serve\-expired\-client\-timeout if that is enabled.
-A value of 1900 msec is suggested. The value 0 disables it.
-Default 1900 msec.
-.TP
-.B wait\-limit: \fI<number>
+.sp
+Default: 376
+.UNINDENT
+.INDENT 0.0
+.TP
+.B discard\-timeout: \fI<msec>\fP
+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.
+It is nice to be a bit larger than
+\fI\%serve\-expired\-client\-timeout\fP
+if that is enabled.
+A value of \fB1900\fP msec is suggested.
+The value \fB0\fP disables it.
+.sp
+Default: 1900
+.UNINDENT
+.INDENT 0.0
+.TP
+.B wait\-limit: \fI<number>\fP
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 0 disables wait limits. Default is 1000.
+destination.
+The value \fB0\fP disables wait limits.
+.sp
+Default: 1000
+.UNINDENT
+.INDENT 0.0
.TP
-.B wait\-limit\-cookie: \fI<number>
+.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, the limit can be higher. Default is 10000.
-.TP
-.B wait\-limit\-netblock: \fI<netblock> <number>
-The wait limit for the netblock. If not given the wait\-limit value is
-used. The most specific netblock is used to determine the limit. Useful for
-overriding the default for a specific, group or individual, server.
-The value -1 disables wait limits for the netblock.
-By default the loopback has a wait limit netblock of -1, it is not limited,
-because it is separated from the rest of network for spoofed packets.
-The loopback addresses 127.0.0.0/8 and ::1/128 are default at -1.
-.TP
-.B wait\-limit\-cookie\-netblock: \fI<netblock> <number>
-The wait limit for the netblock, when the query has a DNS cookie.
-If not given, the wait\-limit\-cookie value is used.
-The value -1 disables wait limits for the netblock.
-The loopback addresses 127.0.0.0/8 and ::1/128 are default at -1.
-.TP
-.B so\-rcvbuf: \fI<number>
-If not 0, then set the SO_RCVBUF socket option to get more buffer
-space on UDP port 53 incoming queries. So that short spikes on busy
-servers do not drop packets (see counter in netstat \-su). Default is
-0 (use system value). Otherwise, the number of bytes to ask for, try
-"4m" on a busy server. The OS caps it at a maximum, on linux Unbound
-needs root permission to bypass the limit, or the admin can use sysctl
-net.core.rmem_max. On BSD change kern.ipc.maxsockbuf in /etc/sysctl.conf.
-On OpenBSD change header and recompile kernel. On Solaris ndd \-set
-/dev/udp udp_max_buf 8388608.
-.TP
-.B so\-sndbuf: \fI<number>
+that sent the query with a valid DNS Cookie.
+Since the cookie validates the client address, this limit can be higher.
+.sp
+Default: 10000
+.UNINDENT
+.INDENT 0.0
+.TP
+.B wait\-limit\-netblock: \fI<netblock>\fP \fI<number>\fP
+The wait limit for the netblock.
+If not given the
+\fI\%wait\-limit\fP
+value is used.
+The most specific netblock is used to determine the limit.
+Useful for overriding the default for a specific, group or individual,
+server.
+The value \fB\-1\fP disables wait limits for the netblock.
+By default the loopback has a wait limit netblock of \fB\-1\fP, it is not
+limited, because it is separated from the rest of network for spoofed
+packets.
+The loopback addresses \fB127.0.0.0/8\fP and \fB::1/128\fP are default at \fB\-1\fP\&.
+.sp
+Default: (none)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B wait\-limit\-cookie\-netblock: \fI<netblock>\fP \fI<number>\fP
+The wait limit for the netblock, when the query has a DNS Cookie.
+If not given, the
+\fI\%wait\-limit\-cookie\fP
+value is used.
+The value \fB\-1\fP disables wait limits for the netblock.
+The loopback addresses \fB127.0.0.0/8\fP and \fB::1/128\fP are default at \fB\-1\fP\&.
+.sp
+Default: (none)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B so\-rcvbuf: \fI<number>\fP
+If not 0, then set the SO_RCVBUF socket option to get more buffer space on
+UDP port 53 incoming queries.
+So that short spikes on busy servers do not drop packets (see counter in
+\fBnetstat \-su\fP).
+Otherwise, the number of bytes to ask for, try \(dq4m\(dq on a busy server.
+.sp
+The OS caps it at a maximum, on linux Unbound needs root permission to
+bypass the limit, or the admin can use \fBsysctl net.core.rmem_max\fP\&.
+.sp
+On BSD change \fBkern.ipc.maxsockbuf\fP in \fB/etc/sysctl.conf\fP\&.
+.sp
+On OpenBSD change header and recompile kernel.
+.sp
+On Solaris \fBndd \-set /dev/udp udp_max_buf 8388608\fP\&.
+.sp
+Default: 0 (use system value)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B so\-sndbuf: \fI<number>\fP
If not 0, then set the SO_SNDBUF socket option to get more buffer space on
-UDP port 53 outgoing queries. This for very busy servers handles spikes
-in answer traffic, otherwise 'send: resource temporarily unavailable'
-can get logged, the buffer overrun is also visible by netstat \-su.
-Default is 4m. If set to 0 it uses the system value. Specify the number
-of bytes to ask for, try "8m" on a very busy server. It needs some space
-to be able to deal with packets that wait for local address resolution,
-from like ARP and NDP discovery, before they are sent out, hence
-it is elevated above the system default by default. The OS caps it at
-a maximum, on linux Unbound needs root permission to bypass the limit,
-or the admin can use sysctl net.core.wmem_max. On BSD, Solaris changes
-are similar to so\-rcvbuf.
-.TP
-.B so\-reuseport: \fI<yes or no>
+UDP port 53 outgoing queries.
+This for very busy servers handles spikes in answer traffic, otherwise:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+send: resource temporarily unavailable
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+can get logged, the buffer overrun is also visible by \fBnetstat \-su\fP\&.
+If set to 0 it uses the system value.
+Specify the number of bytes to ask for, try \(dq8m\(dq on a very busy server.
+.sp
+It needs some space to be able to deal with packets that wait for local
+address resolution, from like ARP and NDP discovery, before they are sent
+out, hence it is elevated above the system default by default.
+.sp
+The OS caps it at a maximum, on linux Unbound needs root permission to
+bypass the limit, or the admin can use \fBsysctl net.core.wmem_max\fP\&.
+.sp
+On BSD, Solaris changes are similar to
+\fI\%so\-rcvbuf\fP\&.
+.sp
+Default: 4m
+.UNINDENT
+.INDENT 0.0
+.TP
+.B so\-reuseport: \fI<yes or no>\fP
If yes, then open dedicated listening sockets for incoming queries for each
-thread and try to set the SO_REUSEPORT socket option on each socket. May
-distribute incoming queries to threads more evenly. Default is yes.
-On Linux it is supported in kernels >= 3.9. On other systems, FreeBSD, OSX
-it may also work. You can enable it (on any platform and kernel),
-it then attempts to open the port and passes the option if it was available
-at compile time, if that works it is used, if it fails, it continues
-silently (unless verbosity 3) without the option.
+thread and try to set the SO_REUSEPORT socket option on each socket.
+May distribute incoming queries to threads more evenly.
+.sp
+On Linux it is supported in kernels >= 3.9.
+.sp
+On other systems, FreeBSD, OSX it may also work.
+.sp
+You can enable it (on any platform and kernel), it then attempts to open
+the port and passes the option if it was available at compile time, if that
+works it is used, if it fails, it continues silently (unless verbosity 3)
+without the option.
+.sp
At extreme load it could be better to turn it off to distribute the queries
evenly, reported for Linux systems (4.4.x).
-.TP
-.B ip\-transparent: \fI<yes or no>
-If yes, then use IP_TRANSPARENT socket option on sockets where Unbound
-is listening for incoming traffic. Default no. Allows you to bind to
-non\-local interfaces. For example for non\-existent IP addresses that
-are going to exist later on, with host failover configuration. This is
-a lot like interface\-automatic, but that one services all interfaces
-and with this option you can select which (future) interfaces Unbound
-provides service on. This option needs Unbound to be started with root
-permissions on some systems. The option uses IP_BINDANY on FreeBSD systems
-and SO_BINDANY on OpenBSD systems.
-.TP
-.B ip\-freebind: \fI<yes or no>
-If yes, then use IP_FREEBIND socket option on sockets where Unbound
-is listening to incoming traffic. Default no. Allows you to bind to
-IP addresses that are nonlocal or do not exist, like when the network
-interface or IP address is down. Exists only on Linux, where the similar
-ip\-transparent option is also available.
-.TP
-.B ip-dscp: \fI<number>
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ip\-transparent: \fI<yes or no>\fP
+If yes, then use IP_TRANSPARENT socket option on sockets where Unbound is
+listening for incoming traffic.
+Allows you to bind to non\-local interfaces.
+For example for non\-existent IP addresses that are going to exist later on,
+with host failover configuration.
+.sp
+This is a lot like
+\fI\%interface\-automatic\fP, but that one
+services all interfaces and with this option you can select which (future)
+interfaces Unbound provides service on.
+.sp
+This option needs Unbound to be started with root permissions on some
+systems.
+The option uses IP_BINDANY on FreeBSD systems and SO_BINDANY on OpenBSD
+systems.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ip\-freebind: \fI<yes or no>\fP
+If yes, then use IP_FREEBIND socket option on sockets where Unbound is
+listening to incoming traffic.
+Allows you to bind to IP addresses that are nonlocal or do not exist, like
+when the network interface or IP address is down.
+.sp
+Exists only on Linux, where the similar
+\fI\%ip\-transparent\fP option is also
+available.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ip\-dscp: \fI<number>\fP
The value of the Differentiated Services Codepoint (DSCP) in the
differentiated services field (DS) of the outgoing IP packet headers.
-The field replaces the outdated IPv4 Type-Of-Service field and the
-IPv6 traffic class field.
-.TP
-.B rrset\-cache\-size: \fI<number>
-Number of bytes size of the RRset cache. Default is 4 megabytes.
-A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+The field replaces the outdated IPv4 Type\-Of\-Service field and the IPv6
+traffic class field.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B rrset\-cache\-size: \fI<number>\fP
+Number of bytes size of the RRset cache.
+A plain number is in bytes, append \(aqk\(aq, \(aqm\(aq or \(aqg\(aq for kilobytes, megabytes
or gigabytes (1024*1024 bytes in a megabyte).
+.sp
+Default: 4m
+.UNINDENT
+.INDENT 0.0
.TP
-.B rrset\-cache\-slabs: \fI<number>
+.B rrset\-cache\-slabs: \fI<number>\fP
Number of slabs in the RRset cache.
Slabs reduce lock contention by threads.
Must be set to a power of 2.
Setting (close) to the number of cpus is a fairly good setting.
-If left unconfigured, it will be configured automatically to be a power of 2
-close to the number of configured threads in multi-threaded environments.
-.TP
-.B cache\-max\-ttl: \fI<seconds>
-Time to live maximum for RRsets and messages in the cache. Default is
-86400 seconds (1 day). When the TTL expires, the cache item has expired.
+If left unconfigured, it will be configured automatically to be a power of
+2 close to the number of configured threads in multi\-threaded environments.
+.sp
+Default: (unconfigured)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B cache\-max\-ttl: \fI<seconds>\fP
+Time to live maximum for RRsets and messages in the cache.
+When the TTL expires, the cache item has expired.
Can be set lower to force the resolver to query for data often, and not
-trust (very large) TTL values. Downstream clients also see the lower TTL.
-.TP
-.B cache\-min\-ttl: \fI<seconds>
-Time to live minimum for RRsets and messages in the cache. Default is 0.
+trust (very large) TTL values.
+Downstream clients also see the lower TTL.
+.sp
+Default: 86400 (1 day)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B cache\-min\-ttl: \fI<seconds>\fP
+Time to live minimum for RRsets and messages in the cache.
If the minimum kicks in, the data is cached for longer than the domain
owner intended, and thus less queries are made to look up the data.
Zero makes sure the data in the cache is as the domain owner intended,
higher values, especially more than an hour or so, can lead to trouble as
the data in the cache does not match up with the actual data any more.
+.sp
+Default: 0 (disabled)
+.UNINDENT
+.INDENT 0.0
.TP
-.B cache\-max\-negative\-ttl: \fI<seconds>
+.B cache\-max\-negative\-ttl: \fI<seconds>\fP
Time to live maximum for negative responses, these have a SOA in the
-authority section that is limited in time. Default is 3600.
-This applies to nxdomain and nodata answers.
+authority section that is limited in time.
+This applies to NXDOMAIN and NODATA answers.
+.sp
+Default: 3600
+.UNINDENT
+.INDENT 0.0
.TP
-.B cache\-min\-negative\-ttl: \fI<seconds>
+.B cache\-min\-negative\-ttl: \fI<seconds>\fP
Time to live minimum for negative responses, these have a SOA in the
authority section that is limited in time.
-Default is 0 (disabled).
-If this is disabled and \fBcache-min-ttl\fR is configured, it will take effect
-instead.
-In that case you can set this to 1 to honor the upstream TTL.
-This applies to nxdomain and nodata answers.
-.TP
-.B infra\-host\-ttl: \fI<seconds>
-Time to live for entries in the host cache. The host cache contains
-roundtrip timing, lameness and EDNS support information. Default is 900.
+If this is disabled and
+\fI\%cache\-min\-ttl\fP
+is configured, it will take effect instead.
+In that case you can set this to \fB1\fP to honor the upstream TTL.
+This applies to NXDOMAIN and NODATA answers.
+.sp
+Default: 0 (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B infra\-host\-ttl: \fI<seconds>\fP
+Time to live for entries in the host cache.
+The host cache contains roundtrip timing, lameness and EDNS support
+information.
+.sp
+Default: 900
+.UNINDENT
+.INDENT 0.0
.TP
-.B infra\-cache\-slabs: \fI<number>
+.B infra\-cache\-slabs: \fI<number>\fP
Number of slabs in the infrastructure cache.
Slabs reduce lock contention by threads.
Must be set to a power of 2.
Setting (close) to the number of cpus is a fairly good setting.
-If left unconfigured, it will be configured automatically to be a power of 2
-close to the number of configured threads in multi-threaded environments.
-.TP
-.B infra\-cache\-numhosts: \fI<number>
-Number of hosts for which information is cached. Default is 10000.
-.TP
-.B infra\-cache\-min\-rtt: \fI<msec>
+If left unconfigured, it will be configured automatically to be a power of
+2 close to the number of configured threads in multi\-threaded environments.
+.sp
+Default: (unconfigured)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B infra\-cache\-numhosts: \fI<number>\fP
+Number of hosts for which information is cached.
+.sp
+Default: 10000
+.UNINDENT
+.INDENT 0.0
+.TP
+.B infra\-cache\-min\-rtt: \fI<msec>\fP
Lower limit for dynamic retransmit timeout calculation in infrastructure
-cache. Default is 50 milliseconds. Increase this value if using forwarders
-needing more time to do recursive name resolution.
-.TP
-.B infra\-cache\-max\-rtt: \fI<msec>
+cache.
+Increase this value if using forwarders needing more time to do recursive
+name resolution.
+.sp
+Default: 50
+.UNINDENT
+.INDENT 0.0
+.TP
+.B infra\-cache\-max\-rtt: \fI<msec>\fP
Upper limit for dynamic retransmit timeout calculation in infrastructure
-cache. Default is 2 minutes.
+cache.
+.sp
+Default: 120000 (2 minutes)
+.UNINDENT
+.INDENT 0.0
.TP
-.B infra\-keep\-probing: \fI<yes or no>
+.B infra\-keep\-probing: \fI<yes or no>\fP
If enabled the server keeps probing hosts that are down, in the one probe
-at a time regime. Default is no. Hosts that are down, eg. they did
-not respond during the one probe at a time period, are marked as down and
-it may take \fBinfra\-host\-ttl\fR time to get probed again.
-.TP
-.B define\-tag: \fI<"list of tags">
-Define the tags that can be used with local\-zone and access\-control.
-Enclose the list between quotes ("") and put spaces between tags.
-.TP
-.B do\-ip4: \fI<yes or no>
-Enable or disable whether ip4 queries are answered or issued. Default is yes.
-.TP
-.B do\-ip6: \fI<yes or no>
-Enable or disable whether ip6 queries are answered or issued. Default is yes.
+at a time regime.
+Hosts that are down, eg. they did not respond during the one probe at a
+time period, are marked as down and it may take
+\fI\%infra\-host\-ttl\fP time to get probed
+again.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B define\-tag: \fI\(dq<list of tags>\(dq\fP
+Define the tags that can be used with
+\fI\%local\-zone\fP and
+\fI\%access\-control\fP\&.
+Enclose the list between quotes (\fB\(dq\(dq\fP) and put spaces between tags.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B do\-ip4: \fI<yes or no>\fP
+Enable or disable whether IPv4 queries are answered or issued.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B do\-ip6: \fI<yes or no>\fP
+Enable or disable whether IPv6 queries are answered or issued.
If disabled, queries are not answered on IPv6, and queries are not sent on
-IPv6 to the internet nameservers. With this option you can disable the
-IPv6 transport for sending DNS traffic, it does not impact the contents of
-the DNS traffic, which may have ip4 and ip6 addresses in it.
-.TP
-.B prefer\-ip4: \fI<yes or no>
+IPv6 to the internet nameservers.
+With this option you can disable the IPv6 transport for sending DNS
+traffic, it does not impact the contents of the DNS traffic, which may have
+IPv4 (A) and IPv6 (AAAA) addresses in it.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B prefer\-ip4: \fI<yes or no>\fP
If enabled, prefer IPv4 transport for sending DNS queries to internet
-nameservers. Default is no. Useful if the IPv6 netblock the server has,
-the entire /64 of that is not owned by one operator and the reputation of
-the netblock /64 is an issue, using IPv4 then uses the IPv4 filters that
-the upstream servers have.
-.TP
-.B prefer\-ip6: \fI<yes or no>
+nameservers.
+Useful if the IPv6 netblock the server has, the entire /64 of that is not
+owned by one operator and the reputation of the netblock /64 is an issue,
+using IPv4 then uses the IPv4 filters that the upstream servers have.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B prefer\-ip6: \fI<yes or no>\fP
If enabled, prefer IPv6 transport for sending DNS queries to internet
-nameservers. Default is no.
-.TP
-.B do\-udp: \fI<yes or no>
-Enable or disable whether UDP queries are answered or issued. Default is yes.
-.TP
-.B do\-tcp: \fI<yes or no>
-Enable or disable whether TCP queries are answered or issued. Default is yes.
-.TP
-.B tcp\-mss: \fI<number>
-Maximum segment size (MSS) of TCP socket on which the server responds
-to queries. Value lower than common MSS on Ethernet
-(1220 for example) will address path MTU problem.
+nameservers.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B do\-udp: \fI<yes or no>\fP
+Enable or disable whether UDP queries are answered or issued.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B do\-tcp: \fI<yes or no>\fP
+Enable or disable whether TCP queries are answered or issued.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tcp\-mss: \fI<number>\fP
+Maximum segment size (MSS) of TCP socket on which the server responds to
+queries.
+Value lower than common MSS on Ethernet (1220 for example) will address
+path MTU problem.
Note that not all platform supports socket option to set MSS (TCP_MAXSEG).
-Default is system default MSS determined by interface MTU and
-negotiation between server and client.
-.TP
-.B outgoing\-tcp\-mss: \fI<number>
-Maximum segment size (MSS) of TCP socket for outgoing queries
-(from Unbound to other servers). Value lower than
-common MSS on Ethernet (1220 for example) will address path MTU problem.
+Default is system default MSS determined by interface MTU and negotiation
+between server and client.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B outgoing\-tcp\-mss: \fI<number>\fP
+Maximum segment size (MSS) of TCP socket for outgoing queries (from Unbound
+to other servers).
+Value lower than common MSS on Ethernet (1220 for example) will address
+path MTU problem.
Note that not all platform supports socket option to set MSS (TCP_MAXSEG).
-Default is system default MSS determined by interface MTU and
-negotiation between Unbound and other servers.
+Default is system default MSS determined by interface MTU and negotiation
+between Unbound and other servers.
+.UNINDENT
+.INDENT 0.0
.TP
-.B tcp-idle-timeout: \fI<msec>\fR
+.B tcp\-idle\-timeout: \fI<msec>\fP
The period Unbound will wait for a query on a TCP connection.
If this timeout expires Unbound closes the connection.
-This option defaults to 30000 milliseconds.
-When the number of free incoming TCP buffers falls below 50% of the
-total number configured, the option value used is progressively
-reduced, first to 1% of the configured value, then to 0.2% of the
-configured value if the number of free buffers falls below 35% of the
-total number configured, and finally to 0 if the number of free buffers
-falls below 20% of the total number configured. A minimum timeout of
-200 milliseconds is observed regardless of the option value used.
-It will be overridden by \fBedns\-tcp\-keepalive\-timeout\fR if
-\fBedns\-tcp\-keepalive\fR is enabled.
-.TP
-.B tcp-reuse-timeout: \fI<msec>\fR
-The period Unbound will keep TCP persistent connections open to
-authority servers. This option defaults to 60000 milliseconds.
-.TP
-.B max-reuse-tcp-queries: \fI<number>\fR
+When the number of free incoming TCP buffers falls below 50% of the total
+number configured, the option value used is progressively reduced, first to
+1% of the configured value, then to 0.2% of the configured value if the
+number of free buffers falls below 35% of the total number configured, and
+finally to 0 if the number of free buffers falls below 20% of the total
+number configured.
+A minimum timeout of 200 milliseconds is observed regardless of the option
+value used.
+It will be overridden by
+\fI\%edns\-tcp\-keepalive\-timeout\fP
+if
+\fI\%edns\-tcp\-keepalive\fP
+is enabled.
+.sp
+Default: 30000 (30 seconds)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tcp\-reuse\-timeout: \fI<msec>\fP
+The period Unbound will keep TCP persistent connections open to authority
+servers.
+.sp
+Default: 60000 (60 seconds)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B max\-reuse\-tcp\-queries: \fI<number>\fP
The maximum number of queries that can be sent on a persistent TCP
connection.
-This option defaults to 200 queries.
+.sp
+Default: 200
+.UNINDENT
+.INDENT 0.0
.TP
-.B tcp-auth-query-timeout: \fI<number>\fR
+.B tcp\-auth\-query\-timeout: \fI<number>\fP
Timeout in milliseconds for TCP queries to auth servers.
-This option defaults to 3000 milliseconds.
-.TP
-.B edns-tcp-keepalive: \fI<yes or no>\fR
-Enable or disable EDNS TCP Keepalive. Default is no.
-.TP
-.B edns-tcp-keepalive-timeout: \fI<msec>\fR
-Overrides \fBtcp\-idle\-timeout\fR when \fBedns\-tcp\-keepalive\fR is enabled.
+.sp
+Default: 3000 (3 seconds)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B edns\-tcp\-keepalive: \fI<yes or no>\fP
+Enable or disable EDNS TCP Keepalive.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B edns\-tcp\-keepalive\-timeout: \fI<msec>\fP
+Overrides
+\fI\%tcp\-idle\-timeout\fP
+when
+\fI\%edns\-tcp\-keepalive\fP
+is enabled.
If the client supports the EDNS TCP Keepalive option,
-Unbound sends the timeout value to the client to encourage it to
-close the connection before the server times out.
-This option defaults to 120000 milliseconds.
-.TP
-.B sock\-queue\-timeout: \fI<sec>\fR
+If the client supports the EDNS TCP Keepalive option, Unbound sends the
+timeout value to the client to encourage it to close the connection before
+the server times out.
+.sp
+Default: 120000 (2 minutes)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B sock\-queue\-timeout: \fI<sec>\fP
UDP queries that have waited in the socket buffer for a long time can be
-dropped. Default is 0, disabled. The time is set in seconds, 3 could be a
-good value to ignore old queries that likely the client does not need a reply
-for any more. This could happen if the host has not been able to service
-the queries for a while, i.e. Unbound is not running, and then is enabled
-again. It uses timestamp socket options.
-.TP
-.B tcp\-upstream: \fI<yes or no>
+dropped.
+The time is set in seconds, 3 could be a good value to ignore old queries
+that likely the client does not need a reply for any more.
+This could happen if the host has not been able to service the queries for
+a while, i.e. Unbound is not running, and then is enabled again.
+It uses timestamp socket options.
+.sp
+Default: 0 (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tcp\-upstream: \fI<yes or no>\fP
Enable or disable whether the upstream queries use TCP only for transport.
-Default is no. Useful in tunneling scenarios. If set to no you can specify
-TCP transport only for selected forward or stub zones using forward-tcp-upstream
-or stub-tcp-upstream respectively.
-.TP
-.B udp\-upstream\-without\-downstream: \fI<yes or no>
-Enable udp upstream even if do-udp is no. Default is no, and this does not
-change anything. Useful for TLS service providers, that want no udp downstream
-but use udp to fetch data upstream.
-.TP
-.B tls\-upstream: \fI<yes or no>
+Useful in tunneling scenarios.
+If set to no you can specify TCP transport only for selected forward or
+stub zones using
+\fI\%forward\-tcp\-upstream\fP or
+\fI\%stub\-tcp\-upstream\fP
+respectively.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B udp\-upstream\-without\-downstream: \fI<yes or no>\fP
+Enable UDP upstream even if \fI\%do\-udp: no\fP is set.
+Useful for TLS service providers, that want no UDP downstream but use UDP
+to fetch data upstream.
+.sp
+Default: no (no changes)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tls\-upstream: \fI<yes or no>\fP
Enabled or disable whether the upstream queries use TLS only for transport.
-Default is no. Useful in tunneling scenarios. The TLS contains plain DNS in
-TCP wireformat. The other server must support this (see
-\fBtls\-service\-key\fR).
-If you enable this, also configure a tls\-cert\-bundle or use tls\-win\-cert or
-tls\-system\-cert to load CA certs, otherwise the connections cannot be
-authenticated. This option enables TLS for all of them, but if you do not set
-this you can configure TLS specifically for some forward zones with
-forward\-tls\-upstream. And also with stub\-tls\-upstream.
-If the tls\-upstream option is enabled, it is for all the forwards and stubs,
-where the forward\-tls\-upstream and stub\-tls\-upstream options are ignored,
-as if they had been set to yes.
-.TP
-.B ssl\-upstream: \fI<yes or no>
-Alternate syntax for \fBtls\-upstream\fR. If both are present in the config
-file the last is used.
-.TP
-.B tls\-service\-key: \fI<file>
-If enabled, the server provides DNS-over-TLS or DNS-over-HTTPS service on the
-TCP ports marked implicitly or explicitly for these services with tls\-port or
-https\-port. The file must contain the private key for the TLS session, the
-public certificate is in the tls\-service\-pem file and it must also be
-specified if tls\-service\-key is specified. The default is "", turned off.
-Enabling or disabling this service requires a restart (a reload is not enough),
-because the key is read while root permissions are held and before chroot (if any).
-The ports enabled implicitly or explicitly via \fBtls\-port:\fR and
-\fBhttps\-port:\fR do not provide normal DNS TCP service. Unbound needs to be
-compiled with libnghttp2 in order to provide DNS-over-HTTPS.
-.TP
-.B ssl\-service\-key: \fI<file>
-Alternate syntax for \fBtls\-service\-key\fR.
-.TP
-.B tls\-service\-pem: \fI<file>
-The public key certificate pem file for the tls service. Default is "",
-turned off.
-.TP
-.B ssl\-service\-pem: \fI<file>
-Alternate syntax for \fBtls\-service\-pem\fR.
-.TP
-.B tls\-port: \fI<number>
-The port number on which to provide TCP TLS service, default 853, only
-interfaces configured with that port number as @number get the TLS service.
-.TP
-.B ssl\-port: \fI<number>
-Alternate syntax for \fBtls\-port\fR.
-.TP
-.B tls\-cert\-bundle: \fI<file>
-If null or "", no file is used. Set it to the certificate bundle file,
-for example "/etc/pki/tls/certs/ca\-bundle.crt". These certificates are used
-for authenticating connections made to outside peers. For example auth\-zone
-urls, and also DNS over TLS connections. It is read at start up before
-permission drop and chroot.
-.TP
-.B ssl\-cert\-bundle: \fI<file>
-Alternate syntax for \fBtls\-cert\-bundle\fR.
-.TP
-.B tls\-win\-cert: \fI<yes or no>
-Add the system certificates to the cert bundle certificates for authentication.
-If no cert bundle, it uses only these certificates. Default is no.
-On windows this option uses the certificates from the cert store. Use
-the tls\-cert\-bundle option on other systems. On other systems, this option
-enables the system certificates.
-.TP
-.B tls\-system\-cert: \fI<yes or no>
-This the same setting as the tls\-win\-cert setting, under a different name.
+Useful in tunneling scenarios.
+The TLS contains plain DNS in TCP wireformat.
+The other server must support this (see
+\fI\%tls\-service\-key\fP).
+.sp
+If you enable this, also configure a
+\fI\%tls\-cert\-bundle\fP or use
+\fI\%tls\-win\-cert\fP or
+\fI\%tls\-system\-cert\fP to load CA certs,
+otherwise the connections cannot be authenticated.
+.sp
+This option enables TLS for all of them, but if you do not set this you can
+configure TLS specifically for some forward zones with
+\fI\%forward\-tls\-upstream\fP\&.
+And also with
+\fI\%stub\-tls\-upstream\fP\&.
+If the
+\fI\%tls\-upstream\fP
+option is enabled, it is for all the forwards and stubs, where the
+\fI\%forward\-tls\-upstream\fP
+and
+\fI\%stub\-tls\-upstream\fP
+options are ignored, as if they had been set to yes.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ssl\-upstream: \fI<yes or no>\fP
+Alternate syntax for \fI\%tls\-upstream\fP\&.
+If both are present in the config file the last is used.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tls\-service\-key: \fI<file>\fP
+If enabled, the server provides DNS\-over\-TLS or DNS\-over\-HTTPS service on
+the TCP ports marked implicitly or explicitly for these services with
+\fI\%tls\-port\fP or
+\fI\%https\-port\fP\&.
+The file must contain the private key for the TLS session, the public
+certificate is in the \fI\%tls\-service\-pem\fP
+file and it must also be specified if
+\fI\%tls\-service\-key\fP is specified.
+Enabling or disabling this service requires a restart (a reload is not
+enough), because the key is read while root permissions are held and before
+chroot (if any).
+The ports enabled implicitly or explicitly via
+\fI\%tls\-port\fP and
+\fI\%https\-port\fP do not provide normal DNS TCP
+service.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+Unbound needs to be compiled with libnghttp2 in order to provide
+DNS\-over\-HTTPS.
+.UNINDENT
+.UNINDENT
+.sp
+Default: \(dq\(dq (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ssl\-service\-key: \fI<file>\fP
+Alternate syntax for \fI\%tls\-service\-key\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tls\-service\-pem: \fI<file>\fP
+The public key certificate pem file for the tls service.
+.sp
+Default: \(dq\(dq (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ssl\-service\-pem: \fI<file>\fP
+Alternate syntax for \fI\%tls\-service\-pem\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tls\-port: \fI<number>\fP
+The port number on which to provide TCP TLS service.
+Only interfaces configured with that port number as @number get the TLS
+service.
+.sp
+Default: 853
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ssl\-port: \fI<number>\fP
+Alternate syntax for \fI\%tls\-port\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tls\-cert\-bundle: \fI<file>\fP
+If null or \fB\(dq\(dq\fP, no file is used.
+Set it to the certificate bundle file, for example
+\fB/etc/pki/tls/certs/ca\-bundle.crt\fP\&.
+These certificates are used for authenticating connections made to outside
+peers.
+For example \fI\%auth\-zone urls\fP, and also
+DNS\-over\-TLS connections.
+It is read at start up before permission drop and chroot.
+.sp
+Default: \(dq\(dq (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ssl\-cert\-bundle: \fI<file>\fP
+Alternate syntax for \fI\%tls\-cert\-bundle\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tls\-win\-cert: \fI<yes or no>\fP
+Add the system certificates to the cert bundle certificates for
+authentication.
+If no cert bundle, it uses only these certificates.
+On windows this option uses the certificates from the cert store.
+Use the \fI\%tls\-cert\-bundle\fP option on
+other systems.
+On other systems, this option enables the system certificates.
+.sp
+Default: no
+.UNINDENT
+.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
+different name.
Because it is not windows specific.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tls\-additional\-port: \fI<portnr>\fP
+List port numbers as
+\fI\%tls\-additional\-port\fP, and when
+interfaces are defined, eg. with the @port suffix, as this port number,
+they provide DNS\-over\-TLS service.
+Can list multiple, each on a new statement.
+.UNINDENT
+.INDENT 0.0
.TP
-.B tls\-additional\-port: \fI<portnr>
-List portnumbers as tls\-additional\-port, and when interfaces are defined,
-eg. with the @port suffix, as this port number, they provide dns over TLS
-service. Can list multiple, each on a new statement.
-.TP
-.B tls-session-ticket-keys: \fI<file>
-If not "", lists files with 80 bytes of random contents that are used to
-perform TLS session resumption for clients using the Unbound server.
+.B tls\-session\-ticket\-keys: \fI<file>\fP
+If not \fB\(dq\(dq\fP, lists files with 80 bytes of random contents that are used
+to perform TLS session resumption for clients using the Unbound server.
These files contain the secret key for the TLS session tickets.
First key use to encrypt and decrypt TLS session tickets.
-Other keys use to decrypt only. With this you can roll over to new keys,
-by generating a new first file and allowing decrypt of the old file by
-listing it after the first file for some time, after the wait clients are not
-using the old key any more and the old key can be removed.
-One way to create the file is dd if=/dev/random bs=1 count=80 of=ticket.dat
-The first 16 bytes should be different from the old one if you create a second key, that is the name used to identify the key. Then there is 32 bytes random
-data for an AES key and then 32 bytes random data for the HMAC key.
-.TP
-.B tls\-ciphers: \fI<string with cipher list>
-Set the list of ciphers to allow when serving TLS. Use "" for defaults,
-and that is the default.
-.TP
-.B tls\-ciphersuites: \fI<string with ciphersuites list>
-Set the list of ciphersuites to allow when serving TLS. This is for newer
-TLS 1.3 connections. Use "" for defaults, and that is the default.
-.TP
-.B pad\-responses: \fI<yes or no>
+Other keys use to decrypt only.
+.sp
+With this you can roll over to new keys, by generating a new first file and
+allowing decrypt of the old file by listing it after the first file for
+some time, after the wait clients are not using the old key any more and
+the old key can be removed.
+One way to create the file is:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+dd if=/dev/random bs=1 count=80 of=ticket.dat
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The first 16 bytes should be different from the old one if you create a
+second key, that is the name used to identify the key.
+Then there is 32 bytes random data for an AES key and then 32 bytes random
+data for the HMAC key.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tls\-ciphers: \fI<string with cipher list>\fP
+Set the list of ciphers to allow when serving TLS.
+Use \fB\(dq\(dq\fP for default ciphers.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tls\-ciphersuites: \fI<string with ciphersuites list>\fP
+Set the list of ciphersuites to allow when serving TLS.
+This is for newer TLS 1.3 connections.
+Use \fB\(dq\(dq\fP for default ciphersuites.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B pad\-responses: \fI<yes or no>\fP
If enabled, TLS serviced queries that contained an EDNS Padding option will
cause responses padded to the closest multiple of the size specified in
-\fBpad\-responses\-block\-size\fR.
-Default is yes.
-.TP
-.B pad\-responses\-block\-size: \fI<number>
-The block size with which to pad responses serviced over TLS. Only responses
-to padded queries will be padded.
-Default is 468.
-.TP
-.B pad\-queries: \fI<yes or no>
-If enabled, all queries sent over TLS upstreams will be padded to the closest
-multiple of the size specified in \fBpad\-queries\-block\-size\fR.
-Default is yes.
-.TP
-.B pad\-queries\-block\-size: \fI<number>
+\fI\%pad\-responses\-block\-size\fP\&.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B pad\-responses\-block\-size: \fI<number>\fP
+The block size with which to pad responses serviced over TLS.
+Only responses to padded queries will be padded.
+.sp
+Default: 468
+.UNINDENT
+.INDENT 0.0
+.TP
+.B pad\-queries: \fI<yes or no>\fP
+If enabled, all queries sent over TLS upstreams will be padded to the
+closest multiple of the size specified in
+\fI\%pad\-queries\-block\-size\fP\&.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B pad\-queries\-block\-size: \fI<number>\fP
The block size with which to pad queries sent over TLS upstreams.
-Default is 128.
+.sp
+Default: 128
+.UNINDENT
+.INDENT 0.0
.TP
-.B tls\-use\-sni: \fI<yes or no>
+.B tls\-use\-sni: \fI<yes or no>\fP
Enable or disable sending the SNI extension on TLS connections.
-Default is yes.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
Changing the value requires a reload.
-.TP
-.B https\-port: \fI<number>
-The port number on which to provide DNS-over-HTTPS service, default 443, only
-interfaces configured with that port number as @number get the HTTPS service.
-.TP
-.B http\-endpoint: \fI<endpoint string>
-The HTTP endpoint to provide DNS-over-HTTPS service on. Default "/dns-query".
-.TP
-.B http\-max\-streams: \fI<number of streams>
+.UNINDENT
+.UNINDENT
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B https\-port: \fI<number>\fP
+The port number on which to provide DNS\-over\-HTTPS service.
+Only interfaces configured with that port number as @number get the HTTPS
+service.
+.sp
+Default: 443
+.UNINDENT
+.INDENT 0.0
+.TP
+.B http\-endpoint: \fI<endpoint string>\fP
+The HTTP endpoint to provide DNS\-over\-HTTPS service on.
+.sp
+Default: /dns\-query
+.UNINDENT
+.INDENT 0.0
+.TP
+.B http\-max\-streams: \fI<number of streams>\fP
Number used in the SETTINGS_MAX_CONCURRENT_STREAMS parameter in the HTTP/2
-SETTINGS frame for DNS-over-HTTPS connections. Default 100.
-.TP
-.B http\-query\-buffer\-size: \fI<size in bytes>
-Maximum number of bytes used for all HTTP/2 query buffers combined. These
-buffers contain (partial) DNS queries waiting for request stream completion.
-An RST_STREAM frame will be send to streams exceeding this limit. Default is 4
-megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes,
-megabytes or gigabytes (1024*1024 bytes in a megabyte).
-.TP
-.B http\-response\-buffer\-size: \fI<size in bytes>
-Maximum number of bytes used for all HTTP/2 response buffers combined. These
-buffers contain DNS responses waiting to be written back to the clients.
-An RST_STREAM frame will be send to streams exceeding this limit. Default is 4
-megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes,
-megabytes or gigabytes (1024*1024 bytes in a megabyte).
-.TP
-.B http\-nodelay: \fI<yes or no>
-Set TCP_NODELAY socket option on sockets used to provide DNS-over-HTTPS service.
-Ignored if the option is not available. Default is yes.
-.TP
-.B http\-notls\-downstream: \fI<yes or no>
-Disable use of TLS for the downstream DNS-over-HTTP connections. Useful for
-local back end servers. Default is no.
-.TP
-.B proxy\-protocol\-port: \fI<portnr>
-List port numbers as proxy\-protocol\-port, and when interfaces are defined,
-eg. with the @port suffix, as this port number, they support and expect PROXYv2.
-In this case the proxy address will only be used for the network communication
-and initial ACL (check if the proxy itself is denied/refused by configuration).
-The proxied address (if any) will then be used as the true client address and
-will be used where applicable for logging, ACL, DNSTAP, RPZ and IP ratelimiting.
+SETTINGS frame for DNS\-over\-HTTPS connections.
+.sp
+Default: 100
+.UNINDENT
+.INDENT 0.0
+.TP
+.B http\-query\-buffer\-size: \fI<size in bytes>\fP
+Maximum number of bytes used for all HTTP/2 query buffers combined.
+These buffers contain (partial) DNS queries waiting for request stream
+completion.
+An RST_STREAM frame will be send to streams exceeding this limit.
+A plain number is in bytes, append \(aqk\(aq, \(aqm\(aq or \(aqg\(aq for kilobytes, megabytes
+or gigabytes (1024*1024 bytes in a megabyte).
+.sp
+Default: 4m
+.UNINDENT
+.INDENT 0.0
+.TP
+.B http\-response\-buffer\-size: \fI<size in bytes>\fP
+Maximum number of bytes used for all HTTP/2 response buffers combined.
+These buffers contain DNS responses waiting to be written back to the
+clients.
+An RST_STREAM frame will be send to streams exceeding this limit.
+A plain number is in bytes, append \(aqk\(aq, \(aqm\(aq or \(aqg\(aq for kilobytes, megabytes
+or gigabytes (1024*1024 bytes in a megabyte).
+.sp
+Default: 4m
+.UNINDENT
+.INDENT 0.0
+.TP
+.B http\-nodelay: \fI<yes or no>\fP
+Set TCP_NODELAY socket option on sockets used to provide DNS\-over\-HTTPS
+service.
+Ignored if the option is not available.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B http\-notls\-downstream: \fI<yes or no>\fP
+Disable use of TLS for the downstream DNS\-over\-HTTP connections.
+Useful for local back end servers.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B proxy\-protocol\-port: \fI<portnr>\fP
+List port numbers as
+\fI\%proxy\-protocol\-port\fP, and when
+interfaces are defined, eg. with the @port suffix, as this port number,
+they support and expect PROXYv2.
+.sp
+In this case the proxy address will only be used for the network
+communication and initial ACL (check if the proxy itself is denied/refused
+by configuration).
+.sp
+The proxied address (if any) will then be used as the true client address
+and will be used where applicable for logging, ACL, DNSTAP, RPZ and IP
+ratelimiting.
+.sp
PROXYv2 is supported for UDP and TCP/TLS listening interfaces.
+.sp
There is no support for PROXYv2 on a DoH, DoQ or DNSCrypt listening interface.
+.sp
Can list multiple, each on a new statement.
+.UNINDENT
+.INDENT 0.0
.TP
-.B quic\-port: \fI<number>
-The port number on which to provide DNS-over-QUIC service, default 853, only
-interfaces configured with that port number as @number get the QUIC service.
+.B quic\-port: \fI<number>\fP
+The port number on which to provide DNS\-over\-QUIC service.
+Only interfaces configured with that port number as @number get the QUIC
+service.
The interface uses QUIC for the UDP traffic on that port number.
-.TP
-.B quic\-size: \fI<size in bytes>
-Maximum number of bytes for all QUIC buffers and data combined. Default is 8
-megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes,
-megabytes or gigabytes (1024*1024 bytes in a megabyte). New connections receive
-connection refused when the limit is exceeded. New streams are reset when the
-limit is exceeded.
-.TP
-.B use\-systemd: \fI<yes or no>
+.sp
+Default: 853
+.UNINDENT
+.INDENT 0.0
+.TP
+.B quic\-size: \fI<size in bytes>\fP
+Maximum number of bytes for all QUIC buffers and data combined.
+A plain number is in bytes, append \(aqk\(aq, \(aqm\(aq or \(aqg\(aq for kilobytes, megabytes
+or gigabytes (1024*1024 bytes in a megabyte).
+New connections receive connection refused when the limit is exceeded.
+New streams are reset when the limit is exceeded.
+.sp
+Default: 8m
+.UNINDENT
+.INDENT 0.0
+.TP
+.B use\-systemd: \fI<yes or no>\fP
Enable or disable systemd socket activation.
-Default is no.
-.TP
-.B do\-daemonize: \fI<yes or no>
-Enable or disable whether the Unbound server forks into the background as
-a daemon. Set the value to \fIno\fR when Unbound runs as systemd service.
-Default is yes.
-.TP
-.B tcp\-connection\-limit: \fI<IP netblock> <limit>
-Allow up to \fIlimit\fR simultaneous TCP connections from the given netblock.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B do\-daemonize: \fI<yes or no>\fP
+Enable or disable whether the Unbound server forks into the background as a
+daemon.
+Set the value to no when Unbound runs as systemd service.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B tcp\-connection\-limit: \fI<IP netblock> <limit>\fP
+Allow up to limit simultaneous TCP connections from the given netblock.
When at the limit, further connections are accepted but closed immediately.
This option is experimental at this time.
+.sp
+Default: (disabled)
+.UNINDENT
+.INDENT 0.0
.TP
-.B access\-control: \fI<IP netblock> <action>
+.B access\-control: \fI<IP netblock> <action>\fP
Specify treatment of incoming queries from their originating IP address.
Queries can be allowed to have access to this server that gives DNS
-answers, or refused, with other actions possible. The IP address range
-can be specified as a netblock, it is possible to give the statement
-several times in order to specify the treatment of different netblocks.
-.IP
-The netblock is given as an IP4 or IP6 address with /size appended for a
-classless network block. The action can be \fIdeny\fR, \fIrefuse\fR,
-\fIallow\fR, \fIallow_setrd\fR, \fIallow_snoop\fR, \fIallow_cookie\fR,
-\fIdeny_non_local\fR or \fIrefuse_non_local\fR.
-The most specific netblock match is used, if none match \fIrefuse\fR is used.
+answers, or refused, with other actions possible.
+The IP address range can be specified as a netblock, it is possible to give
+the statement several times in order to specify the treatment of different
+netblocks.
+The netblock is given as an IPv4 or IPv6 address with /size appended for a
+classless network block.
+The most specific netblock match is used, if none match
+\fI\%refuse\fP is used.
The order of the access\-control statements therefore does not matter.
-.IP
-The \fIdeny\fR action stops queries from hosts from that netblock.
-.IP
-The \fIrefuse\fR action stops queries too, but sends a DNS rcode REFUSED
-error message back.
-.IP
-The \fIallow\fR action gives access to clients from that netblock.
-It gives only access for recursion clients (which is
-what almost all clients need). Nonrecursive queries are refused.
-.IP
-The \fIallow\fR action does allow nonrecursive queries to access the
-local\-data that is configured. The reason is that this does not involve
-the Unbound server recursive lookup algorithm, and static data is served
-in the reply. This supports normal operations where nonrecursive queries
-are made for the authoritative data. For nonrecursive queries any replies
-from the dynamic cache are refused.
-.IP
-The \fIallow_setrd\fR action ignores the recursion desired (RD) bit and
-treats all requests as if the recursion desired bit is set. Note that this
-behavior violates RFC 1034 which states that a name server should never perform
-recursive service unless asked via the RD bit since this interferes with
-trouble shooting of name servers and their databases. This prohibited behavior
-may be useful if another DNS server must forward requests for specific
-zones to a resolver DNS server, but only supports stub domains and
-sends queries to the resolver DNS server with the RD bit cleared.
-.IP
-The \fIallow_snoop\fR action gives nonrecursive access too. This give
-both recursive and non recursive access. The name \fIallow_snoop\fR refers
-to cache snooping, a technique to use nonrecursive queries to examine
-the cache contents (for malicious acts). However, nonrecursive queries can
-also be a valuable debugging tool (when you want to examine the cache
-contents). In that case use \fIallow_snoop\fR for your administration host.
-.IP
-The \fIallow_cookie\fR action allows access only to UDP queries that contain a
-valid DNS Cookie as specified in RFC 7873 and RFC 9018, when the
-\fBanswer\-cookie\fR option is enabled.
-UDP queries containing only a DNS Client Cookie and no Server Cookie, or an
-invalid DNS Cookie, will receive a BADCOOKIE response including a newly
-generated DNS Cookie, allowing clients to retry with that DNS Cookie.
-The \fIallow_cookie\fR action will also accept requests over stateful
-transports, regardless of the presence of an DNS Cookie and regardless of the
-\fBanswer\-cookie\fR setting.
-UDP queries without a DNS Cookie receive REFUSED responses with the TC flag set,
-that may trigger fall back to TCP for those clients.
-.IP
+The action can be
+\fI\%deny\fP,
+\fI\%refuse\fP,
+\fI\%allow\fP,
+\fI\%allow_setrd\fP,
+\fI\%allow_snoop\fP,
+\fI\%allow_cookie\fP,
+\fI\%deny_non_local\fP or
+\fI\%refuse_non_local\fP\&.
+.INDENT 7.0
+.TP
+.B deny
+Stops queries from hosts from that netblock.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B refuse
+Stops queries too, but sends a DNS rcode REFUSED error message back.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B allow
+Gives access to clients from that netblock.
+It gives only access for recursion clients (which is what almost all
+clients need).
+Non\-recursive queries are refused.
+.sp
+The \fI\%allow\fP action does
+allow non\-recursive queries to access the local\-data that is
+configured.
+The reason is that this does not involve the Unbound server recursive
+lookup algorithm, and static data is served in the reply.
+This supports normal operations where non\-recursive queries are made
+for the authoritative data.
+For non\-recursive queries any replies from the dynamic cache are
+refused.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B allow_setrd
+Ignores the recursion desired (RD) bit and treats all requests as if
+the recursion desired bit is set.
+.sp
+Note that this behavior violates \fI\%RFC 1034\fP which states that a name
+server should never perform recursive service unless asked via the RD
+bit since this interferes with trouble shooting of name servers and
+their databases.
+This prohibited behavior may be useful if another DNS server must
+forward requests for specific zones to a resolver DNS server, but only
+supports stub domains and sends queries to the resolver DNS server with
+the RD bit cleared.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B allow_snoop
+Gives non\-recursive access too.
+This gives both recursive and non recursive access.
+The name \fIallow_snoop\fP refers to cache snooping, a technique to use
+non\-recursive queries to examine the cache contents (for malicious
+acts).
+However, non\-recursive queries can also be a valuable debugging tool
+(when you want to examine the cache contents).
+.sp
+In that case use
+\fI\%allow_snoop\fP for
+your administration host.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B allow_cookie
+Allows access only to UDP queries that contain a valid DNS Cookie as
+specified in RFC 7873 and RFC 9018, when the
+\fI\%answer\-cookie\fP option is enabled.
+UDP queries containing only a DNS Client Cookie and no Server Cookie,
+or an invalid DNS Cookie, will receive a BADCOOKIE response including a
+newly generated DNS Cookie, allowing clients to retry with that DNS
+Cookie.
+The \fIallow_cookie\fP action will also accept requests over stateful
+transports, regardless of the presence of an DNS Cookie and regardless
+of the \fI\%answer\-cookie\fP setting.
+UDP queries without a DNS Cookie receive REFUSED responses with the TC
+flag set, that may trigger fall back to TCP for those clients.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B deny_non_local
+The
+\fI\%deny_non_local\fP
+action is for hosts that are only allowed to query for the
+authoritative \fI\%local\-data\fP, they are not
+allowed full recursion but only the static data.
+Messages that are disallowed are dropped.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B refuse_non_local
+The
+\fI\%refuse_non_local\fP
+action is for hosts that are only allowed to query for the
+authoritative \fI\%local\-data\fP, they are not
+allowed full recursion but only the static data.
+Messages that are disallowed receive error code REFUSED.
+.UNINDENT
+.sp
By default only localhost (the 127.0.0.0/8 IP netblock, not the loopback
-interface) is implicitly \fIallow\fRed, the rest is \fIrefuse\fRd.
-The default is \fIrefuse\fRd, because that is protocol\-friendly. The DNS
-protocol is not designed to handle dropped packets due to policy, and
-dropping may result in (possibly excessive) retried queries.
-.IP
-The deny_non_local and refuse_non_local settings are for hosts that are
-only allowed to query for the authoritative local\-data, they are not
-allowed full recursion but only the static data. With deny_non_local,
-messages that are disallowed are dropped, with refuse_non_local they
-receive error code REFUSED.
-.TP
-.B access\-control\-tag: \fI<IP netblock> <"list of tags">
-Assign tags to access-control elements. Clients using this access control
-element use localzones that are tagged with one of these tags. Tags must be
-defined in \fIdefine\-tags\fR. Enclose list of tags in quotes ("") and put
-spaces between tags. If access\-control\-tag is configured for a netblock that
-does not have an access\-control, an access\-control element with action
-\fIallow\fR is configured for this netblock.
-.TP
-.B access\-control\-tag\-action: \fI<IP netblock> <tag> <action>
-Set action for particular tag for given access control element. If you have
-multiple tag values, the tag used to lookup the action is the first tag match
-between access\-control\-tag and local\-zone\-tag where "first" comes from the
-order of the define-tag values.
-.TP
-.B access\-control\-tag\-data: \fI<IP netblock> <tag> <"resource record string">
+interface) is implicitly \fIallowed\fP, the rest is refused.
+The default is \fIrefused\fP, because that is protocol\-friendly.
+The DNS protocol is not designed to handle dropped packets due to policy,
+and dropping may result in (possibly excessive) retried queries.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B access\-control\-tag: \fI<IP netblock> \(dq<list of tags>\(dq\fP
+Assign tags to \fI\%access\-control\fP
+elements.
+Clients using this access control element use localzones that are tagged
+with one of these tags.
+.sp
+Tags must be defined in \fI\%define\-tag\fP\&.
+Enclose list of tags in quotes (\fB\(dq\(dq\fP) and put spaces between tags.
+.sp
+If \fI\%access\-control\-tag\fP is
+configured for a netblock that does not have an
+\fI\%access\-control\fP, an access\-control
+element with action \fI\%allow\fP
+is configured for this netblock.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B access\-control\-tag\-action: \fI<IP netblock> <tag> <action>\fP
+Set action for particular tag for given access control element.
+If you have multiple tag values, the tag used to lookup the action is the
+first tag match between
+\fI\%access\-control\-tag\fP and
+\fI\%local\-zone\-tag\fP where \(dqfirst\(dq comes
+from the order of the \fI\%define\-tag\fP values.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B access\-control\-tag\-data: \fI<IP netblock> <tag> \(dq<resource record string>\(dq\fP
Set redirect data for particular tag for given access control element.
+.UNINDENT
+.INDENT 0.0
.TP
-.B access\-control\-view: \fI<IP netblock> <view name>
+.B access\-control\-view: \fI<IP netblock> <view name>\fP
Set view for given access control element.
-.TP
-.B interface\-action: \fI<ip address or interface name [@port]> <action>
-Similar to \fBaccess\-control:\fR but for interfaces.
-.IP
-The action is the same as the ones defined under \fBaccess\-control:\fR.
-Interfaces are \fIrefuse\fRd by default.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B interface\-action: \fI<ip address or interface name [@port]> <action>\fP
+Similar to \fI\%access\-control\fP but for
+interfaces.
+.sp
+The action is the same as the ones defined under
+\fI\%access\-control\fP\&.
+.sp
+Default action for interfaces is
+\fI\%refuse\fP\&.
By default only localhost (the 127.0.0.0/8 IP netblock, not the loopback
-interface) is implicitly \fIallow\fRed through the default
-\fBaccess\-control:\fR behavior.
-This also means that any attempt to use the \fBinterface-*:\fR options for the
-loopback interface will not work as they will be overridden by the implicit
-default "\fBaccess\-control:\fR 127.0.0.0/8 allow" option.
-.IP
-Note that the interface needs to be already specified with \fBinterface:\fR
-and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR
-settings for targeted clients.
-.TP
-.B interface\-tag: \fI<ip address or interface name [@port]> <"list of tags">
-Similar to \fBaccess\-control-tag:\fR but for interfaces.
-.IP
-Note that the interface needs to be already specified with \fBinterface:\fR
-and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR
-settings for targeted clients.
-.TP
-.B interface\-tag\-action: \fI<ip address or interface name [@port]> <tag> <action>
-Similar to \fBaccess\-control-tag-action:\fR but for interfaces.
-.IP
-Note that the interface needs to be already specified with \fBinterface:\fR
-and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR
-settings for targeted clients.
-.TP
-.B interface\-tag\-data: \fI<ip address or interface name [@port]> <tag> <"resource record string">
-Similar to \fBaccess\-control-tag-data:\fR but for interfaces.
-.IP
-Note that the interface needs to be already specified with \fBinterface:\fR
-and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR
-settings for targeted clients.
-.TP
-.B interface\-view: \fI<ip address or interface name [@port]> <view name>
-Similar to \fBaccess\-control-view:\fR but for interfaces.
-.IP
-Note that the interface needs to be already specified with \fBinterface:\fR
-and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR
-settings for targeted clients.
-.TP
-.B chroot: \fI<directory>
-If chroot is enabled, you should pass the configfile (from the
-commandline) as a full path from the original root. After the
-chroot has been performed the now defunct portion of the config
+interface) is implicitly allowed through the default
+\fI\%access\-control\fP behavior.
+This also means that any attempt to use the \fBinterface\-*:\fP options for
+the loopback interface will not work as they will be overridden by the
+implicit default \(dqaccess\-control: 127.0.0.0/8 allow\(dq option.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.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.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B interface\-tag: \fI<ip address or interface name [@port]> <\(dqlist of tags\(dq>\fP
+Similar to \fI\%access\-control\-tag\fP but
+for interfaces.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.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.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B interface\-tag\-action: \fI<ip address or interface name [@port]> <tag> <action>\fP
+Similar to
+\fI\%access\-control\-tag\-action\fP
+but for interfaces.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.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.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B interface\-tag\-data: \fI<ip address or interface name [@port]> <tag> <\(dqresource record string\(dq>\fP
+Similar to
+\fI\%access\-control\-tag\-data\fP but
+for interfaces.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.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.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B interface\-view: \fI<ip address or interface name [@port]> <view name>\fP
+Similar to \fI\%access\-control\-view\fP
+but for interfaces.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.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.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B chroot: \fI<directory>\fP
+If \fI\%chroot\fP is enabled, you should pass the
+configfile (from the commandline) as a full path from the original root.
+After the chroot has been performed the now defunct portion of the config
file path is removed to be able to reread the config after a reload.
-.IP
-All other file paths (working dir, logfile, roothints, and
-key files) can be specified in several ways:
-as an absolute path relative to the new root,
-as a relative path to the working directory, or
-as an absolute path relative to the original root.
+.sp
+All other file paths (working dir, logfile, roothints, and key files) can
+be specified in several ways: as an absolute path relative to the new root,
+as a relative path to the working directory, or as an absolute path
+relative to the original root.
In the last case the path is adjusted to remove the unused portion.
-.IP
-The pidfile can be either a relative path to the working directory, or
-an absolute path relative to the original root. It is written just prior
-to chroot and dropping permissions. This allows the pidfile to be
-/var/run/unbound.pid and the chroot to be /var/unbound, for example. Note that
-Unbound is not able to remove the pidfile after termination when it is located
-outside of the chroot directory.
-.IP
-Additionally, Unbound may need to access /dev/urandom (for entropy)
+.sp
+The pidfile can be either a relative path to the working directory, or an
+absolute path relative to the original root.
+It is written just prior to chroot and dropping permissions.
+This allows the pidfile to be \fB/var/run/unbound.pid\fP and the chroot
+to be \fB/var/unbound\fP, for example.
+Note that Unbound is not able to remove the pidfile after termination when
+it is located outside of the chroot directory.
+.sp
+Additionally, Unbound may need to access \fB/dev/urandom\fP (for entropy)
from inside the chroot.
-.IP
-If given a chroot is done to the given directory. The chroot is by default
-set to "@UNBOUND_CHROOT_DIR@". If you give "" no chroot is performed.
-.TP
-.B username: \fI<name>
-If given, after binding the port the user privileges are dropped. Default is
-"@UNBOUND_USERNAME@". If you give username: "" no user change is performed.
-.IP
-If this user is not capable of binding the
-port, reloads (by signal HUP) will still retain the opened ports.
+.sp
+If given, a \fIchroot(2)\fP is done to the given directory.
+If you give \fB\(dq\(dq\fP no \fIchroot(2)\fP is performed.
+.sp
+Default: @UNBOUND_CHROOT_DIR@
+.UNINDENT
+.INDENT 0.0
+.TP
+.B username: \fI<name>\fP
+If given, after binding the port the user privileges are dropped.
+If you give username: \fB\(dq\(dq\fP no user change is performed.
+.sp
+If this user is not capable of binding the port, reloads (by signal HUP)
+will still retain the opened ports.
If you change the port number in the config file, and that new port number
requires privileges, then a reload will fail; a restart is needed.
-.TP
-.B directory: \fI<directory>
-Sets the working directory for the program. Default is "@UNBOUND_RUN_DIR@".
-On Windows the string "%EXECUTABLE%" tries to change to the directory
-that unbound.exe resides in.
-If you give a server: directory: dir before include: file statements
-then those includes can be relative to the working directory.
-.TP
-.B logfile: \fI<filename>
-If "" is given, logging goes to stderr, or nowhere once daemonized.
+.sp
+Default: @UNBOUND_USERNAME@
+.UNINDENT
+.INDENT 0.0
+.TP
+.B directory: \fI<directory>\fP
+Sets the working directory for the program.
+On Windows the string \(dq%EXECUTABLE%\(dq tries to change to the directory that
+\fBunbound.exe\fP resides in.
+If you give a \fI\%server: directory:
+<directory>\fP before
+\fI\%include\fP file statements then those includes
+can be relative to the working directory.
+.sp
+Default: @UNBOUND_RUN_DIR@
+.UNINDENT
+.INDENT 0.0
+.TP
+.B logfile: \fI<filename>\fP
+If \fB\(dq\(dq\fP is given, logging goes to stderr, or nowhere once daemonized.
The logfile is appended to, in the following format:
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
+.ft C
[seconds since 1970] unbound[pid:tid]: type: message.
+.ft P
.fi
-If this option is given, the use\-syslog is option is set to "no".
+.UNINDENT
+.UNINDENT
+.sp
+If this option is given, the \fI\%use\-syslog\fP
+attribute is internally set to \fBno\fP\&.
+.sp
The logfile is reopened (for append) when the config file is reread, on
SIGHUP.
-.TP
-.B use\-syslog: \fI<yes or no>
-Sets Unbound to send log messages to the syslogd, using
-\fIsyslog\fR(3).
-The log facility LOG_DAEMON is used, with identity "unbound".
-The logfile setting is overridden when use\-syslog is turned on.
-The default is to log to syslog.
-.TP
-.B log\-identity: \fI<string>
-If "" is given (default), then the name of the executable, usually "unbound"
-is used to report to the log. Enter a string to override it
-with that, which is useful on systems that run more than one instance of
-Unbound, with different configurations, so that the logs can be easily
-distinguished against.
-.TP
-.B log\-time\-ascii: \fI<yes or no>
-Sets logfile lines to use a timestamp in UTC ascii. Default is no, which
-prints the seconds since 1970 in brackets. No effect if using syslog, in
-that case syslog formats the timestamp printed into the log files.
-.TP
-.B log\-time\-iso:\fR <yes or no>
-Log time in ISO8601 format, if \fBlog\-time\-ascii:\fR yes is also set.
-Default is no.
-.TP
-.B log\-queries: \fI<yes or no>
-Prints one line per query to the log, with the log timestamp and IP address,
-name, type and class. Default is no. Note that it takes time to print these
-lines which makes the server (significantly) slower. Odd (nonprintable)
-characters in names are printed as '?'.
-.TP
-.B log\-replies: \fI<yes or no>
-Prints one line per reply to the log, with the log timestamp and IP address,
-name, type, class, return code, time to resolve, from cache and response size.
-Default is no. Note that it takes time to print these
-lines which makes the server (significantly) slower. Odd (nonprintable)
-characters in names are printed as '?'.
-.TP
-.B log\-tag\-queryreply: \fI<yes or no>
-Prints the word 'query' and 'reply' with log\-queries and log\-replies.
-This makes filtering logs easier. The default is off (for backwards
-compatibility).
-.TP
-.B log\-destaddr: \fI<yes or no>
-Prints the destination address, port and type in the log\-replies output.
-This disambiguates what type of traffic, eg. udp or tcp, and to what local
+.sp
+Default: \(dq\(dq (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B use\-syslog: \fI<yes or no>\fP
+Sets Unbound to send log messages to the syslogd, using \fIsyslog(3)\fP\&.
+The log facility LOG_DAEMON is used, with identity \(dqunbound\(dq.
+The logfile setting is overridden when
+\fI\%use\-syslog: yes\fP is set.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B log\-identity: \fI<string>\fP
+If \fB\(dq\(dq\fP is given, then the name of the executable, usually
+\(dqunbound\(dq is used to report to the log.
+Enter a string to override it with that, which is useful on systems that
+run more than one instance of Unbound, with different configurations, so
+that the logs can be easily distinguished against.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B log\-time\-ascii: \fI<yes or no>\fP
+Sets logfile lines to use a timestamp in UTC ASCII.
+No effect if using syslog, in that case syslog formats the timestamp
+printed into the log files.
+.sp
+Default: no (prints the seconds since 1970 in brackets)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B log\-time\-iso: \fI<yes or no>\fP
+Log time in ISO8601 format, if
+\fI\%log\-time\-ascii: yes\fP
+is also set.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B log\-queries: \fI<yes or no>\fP
+Prints one line per query to the log, with the log timestamp and IP
+address, name, type and class.
+Note that it takes time to print these lines which makes the server
+(significantly) slower.
+Odd (nonprintable) characters in names are printed as \fB\(aq?\(aq\fP\&.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B log\-replies: \fI<yes or no>\fP
+Prints one line per reply to the log, with the log timestamp and IP
+address, name, type, class, return code, time to resolve, from cache and
+response size.
+Note that it takes time to print these lines which makes the server
+(significantly) slower.
+Odd (nonprintable) characters in names are printed as \fB\(aq?\(aq\fP\&.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B log\-tag\-queryreply: \fI<yes or no>\fP
+Prints the word \(aqquery\(aq and \(aqreply\(aq with
+\fI\%log\-queries\fP and
+\fI\%log\-replies\fP\&.
+This makes filtering logs easier.
+.sp
+Default: no (backwards compatible)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B log\-destaddr: \fI<yes or no>\fP
+Prints the destination address, port and type in the
+\fI\%log\-replies\fP output.
+This disambiguates what type of traffic, eg. UDP or TCP, and to what local
port the traffic was sent to.
-.TP
-.B log\-local\-actions: \fI<yes or no>
-Print log lines to inform about local zone actions. These lines are like the
-local\-zone type inform prints out, but they are also printed for the other
-types of local zones.
-.TP
-.B log\-servfail: \fI<yes or no>
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B log\-local\-actions: \fI<yes or no>\fP
+Print log lines to inform about local zone actions.
+These lines are like the \fI\%local\-zone type
+inform\fP print outs, but they are also
+printed for the other types of local zones.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B log\-servfail: \fI<yes or no>\fP
Print log lines that say why queries return SERVFAIL to clients.
This is separate from the verbosity debug logs, much smaller, and printed
at the error level, not the info level of debug info from verbosity.
-.TP
-.B pidfile: \fI<filename>
-The process id is written to the file. Default is "@UNBOUND_PIDFILE@".
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B pidfile: \fI<filename>\fP
+The process id is written to the file.
+Default is \fB\(dq@UNBOUND_PIDFILE@\(dq\fP\&.
So,
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-kill \-HUP `cat @UNBOUND_PIDFILE@`
+.ft C
+kill \-HUP \(gacat @UNBOUND_PIDFILE@\(ga
+.ft P
.fi
+.UNINDENT
+.UNINDENT
+.sp
triggers a reload,
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-kill \-TERM `cat @UNBOUND_PIDFILE@`
+.ft C
+kill \-TERM \(gacat @UNBOUND_PIDFILE@\(ga
+.ft P
.fi
+.UNINDENT
+.UNINDENT
+.sp
gracefully terminates.
-.TP
-.B root\-hints: \fI<filename>
-Read the root hints from this file. Default is nothing, using builtin hints
-for the IN class. The file has the format of zone files, with root
-nameserver names and addresses only. The default may become outdated,
-when servers change, therefore it is good practice to use a root\-hints file.
-.TP
-.B hide\-identity: \fI<yes or no>
-If enabled id.server and hostname.bind queries are refused.
-.TP
-.B identity: \fI<string>
-Set the identity to report. If set to "", the default, then the hostname
-of the server is returned.
-.TP
-.B hide\-version: \fI<yes or no>
-If enabled version.server and version.bind queries are refused.
-.TP
-.B version: \fI<string>
-Set the version to report. If set to "", the default, then the package
-version is returned.
-.TP
-.B hide\-http\-user\-agent: \fI<yes or no>
-If enabled the HTTP header User-Agent is not set. Use with caution as some
-webserver configurations may reject HTTP requests lacking this header.
+.sp
+Default: @UNBOUND_PIDFILE@
+.UNINDENT
+.INDENT 0.0
+.TP
+.B root\-hints: \fI<filename>\fP
+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.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B hide\-identity: \fI<yes or no>\fP
+If enabled \(aqid.server\(aq and \(aqhostname.bind\(aq queries are REFUSED.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B identity: \fI<string>\fP
+Set the identity to report.
+If set to \fB\(dq\(dq\fP, then the hostname of the server is returned.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B hide\-version: \fI<yes or no>\fP
+If enabled \(aqversion.server\(aq and \(aqversion.bind\(aq queries are REFUSED.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B version: \fI<string>\fP
+Set the version to report.
+If set to \fB\(dq\(dq\fP, then the package version is returned.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B hide\-http\-user\-agent: \fI<yes or no>\fP
+If enabled the HTTP header User\-Agent is not set.
+Use with caution as some webserver configurations may reject HTTP requests
+lacking this header.
If needed, it is better to explicitly set the
-.B http\-user\-agent
-below.
-.TP
-.B http\-user\-agent: \fI<string>
-Set the HTTP User-Agent header for outgoing HTTP requests. If set to "",
-the default, then the package name and version are used.
-.TP
-.B nsid:\fR <string>
-Add the specified nsid to the EDNS section of the answer when queried
-with an NSID EDNS enabled packet. As a sequence of hex characters or
-with ascii_ prefix and then an ascii string.
-.TP
-.B hide\-trustanchor: \fI<yes or no>
-If enabled trustanchor.unbound queries are refused.
-.TP
-.B target\-fetch\-policy: \fI<"list of numbers">
+\fI\%http\-user\-agent\fP below.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B http\-user\-agent: \fI<string>\fP
+Set the HTTP User\-Agent header for outgoing HTTP requests.
+If set to \fB\(dq\(dq\fP, then the package name and version are used.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B nsid: \fI<string>\fP
+Add the specified nsid to the EDNS section of the answer when queried with
+an NSID EDNS enabled packet.
+As a sequence of hex characters or with \(aqascii_\(aq prefix and then an ASCII
+string.
+.sp
+Default: (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B hide\-trustanchor: \fI<yes or no>\fP
+If enabled \(aqtrustanchor.unbound\(aq queries are REFUSED.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B target\-fetch\-policy: \fI<\(dqlist of numbers\(dq>\fP
Set the target fetch policy used by Unbound to determine if it should fetch
-nameserver target addresses opportunistically. The policy is described per
+nameserver target addresses opportunistically.
+The policy is described per dependency depth.
+.sp
+The number of values determines the maximum dependency depth that Unbound
+will pursue in answering a query.
+A value of \-1 means to fetch all targets opportunistically for that
dependency depth.
-.IP
-The number of values determines the maximum dependency depth
-that Unbound will pursue in answering a query.
-A value of \-1 means to fetch all targets opportunistically for that dependency
-depth. A value of 0 means to fetch on demand only. A positive value fetches
-that many targets opportunistically.
-.IP
-Enclose the list between quotes ("") and put spaces between numbers.
-The default is "3 2 1 0 0". Setting all zeroes, "0 0 0 0 0" gives behaviour
-closer to that of BIND 9, while setting "\-1 \-1 \-1 \-1 \-1" gives behaviour
-rumoured to be closer to that of BIND 8.
-.TP
-.B harden\-short\-bufsize: \fI<yes or no>
-Very small EDNS buffer sizes from queries are ignored. Default is yes, as
-described in the standard.
-.TP
-.B harden\-large\-queries: \fI<yes or no>
-Very large queries are ignored. Default is no, since it is legal protocol
-wise to send these, and could be necessary for operation if TSIG or EDNS
-payload is very large.
-.TP
-.B harden\-glue: \fI<yes or no>
-Will trust glue only if it is within the servers authority. Default is yes.
-.TP
-.B harden\-unverified\-glue: \fI<yes or no>
-Will trust only in-zone glue. Will try to resolve all out of zone
-(\fI<unverfied>) glue. Will fallback to the original glue if unable to resolve.
-Default is no.
-.TP
-.B harden\-dnssec\-stripped: \fI<yes or no>
-Require DNSSEC data for trust\-anchored zones, if such data is absent,
-the zone becomes bogus. If turned off, and no DNSSEC data is received
-(or the DNSKEY data fails to validate), then the zone is made insecure,
-this behaves like there is no trust anchor. You could turn this off if
-you are sometimes behind an intrusive firewall (of some sort) that
-removes DNSSEC data from packets, or a zone changes from signed to
-unsigned to badly signed often. If turned off you run the risk of a
-downgrade attack that disables security for a zone. Default is yes.
-.TP
-.B harden\-below\-nxdomain: \fI<yes or no>
-From RFC 8020 (with title "NXDOMAIN: There Really Is Nothing Underneath"),
-returns nxdomain to queries for a name
-below another name that is already known to be nxdomain. DNSSEC mandates
-noerror for empty nonterminals, hence this is possible. Very old software
-might return nxdomain for empty nonterminals (that usually happen for reverse
-IP address lookups), and thus may be incompatible with this. To try to avoid
-this only DNSSEC-secure nxdomains are used, because the old software does not
-have DNSSEC. Default is yes.
-The nxdomain must be secure, this means nsec3 with optout is insufficient.
-.TP
-.B harden\-referral\-path: \fI<yes or no>
+A value of 0 means to fetch on demand only.
+A positive value fetches that many targets opportunistically.
+.sp
+Enclose the list between quotes (\fB\(dq\(dq\fP) and put spaces between numbers.
+Setting all zeroes, \(dq0 0 0 0 0\(dq gives behaviour closer to that of BIND 9,
+while setting \(dq\-1 \-1 \-1 \-1 \-1\(dq gives behaviour rumoured to be closer to
+that of BIND 8.
+.sp
+Default: \(dq3 2 1 0 0\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B harden\-short\-bufsize: \fI<yes or no>\fP
+Very small EDNS buffer sizes from queries are ignored.
+.sp
+Default: yes (as described in the standard)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B harden\-large\-queries: \fI<yes or no>\fP
+Very large queries are ignored.
+Default is no, since it is legal protocol wise to send these, and could be
+necessary for operation if TSIG or EDNS payload is very large.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B harden\-glue: \fI<yes or no>\fP
+Will trust glue only if it is within the servers authority.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B harden\-unverified\-glue: \fI<yes or no>\fP
+Will trust only in\-zone glue.
+Will try to resolve all out of zone (\fIunverified\fP) glue.
+Will fallback to the original glue if unable to resolve.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B harden\-dnssec\-stripped: \fI<yes or no>\fP
+Require DNSSEC data for trust\-anchored zones, if such data is absent, the
+zone becomes bogus.
+If turned off, and no DNSSEC data is received (or the DNSKEY data fails to
+validate), then the zone is made insecure, this behaves like there is no
+trust anchor.
+You could turn this off if you are sometimes behind an intrusive firewall
+(of some sort) that removes DNSSEC data from packets, or a zone changes
+from signed to unsigned to badly signed often.
+If turned off you run the risk of a downgrade attack that disables security
+for a zone.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B harden\-below\-nxdomain: \fI<yes or no>\fP
+From \fI\%RFC 8020\fP (with title \(dqNXDOMAIN: There Really Is Nothing
+Underneath\(dq), returns NXDOMAIN to queries for a name below another name
+that is already known to be NXDOMAIN.
+DNSSEC mandates NOERROR for empty nonterminals, hence this is possible.
+Very old software might return NXDOMAIN for empty nonterminals (that
+usually happen for reverse IP address lookups), and thus may be
+incompatible with this.
+To try to avoid this only DNSSEC\-secure NXDOMAINs are used, because the old
+software does not have DNSSEC.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+The NXDOMAIN must be secure, this means NSEC3 with optout is
+insufficient.
+.UNINDENT
+.UNINDENT
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B harden\-referral\-path: \fI<yes or no>\fP
Harden the referral path by performing additional queries for
-infrastructure data. Validates the replies if trust anchors are configured
-and the zones are signed. This enforces DNSSEC validation on nameserver
-NS sets and the nameserver addresses that are encountered on the referral
-path to the answer.
-Default no, because it burdens the authority servers, and it is
-not RFC standard, and could lead to performance problems because of the
-extra query load that is generated. Experimental option.
-If you enable it consider adding more numbers after the target\-fetch\-policy
-to increase the max depth that is checked to.
-.TP
-.B harden\-algo\-downgrade: \fI<yes or no>
-Harden against algorithm downgrade when multiple algorithms are
-advertised in the DS record.
-This works by first choosing only the strongest DS digest type as per RFC 4509
-(Unbound treats the highest algorithm as the strongest) and then
-expecting signatures from all the advertised signing algorithms from the chosen
-DS(es) to be present.
-If no, allows any one supported algorithm to validate the zone, even if other advertised algorithms are broken.
-Default is no.
-RFC 6840 mandates that zone signers must produce zones signed with all
+infrastructure data.
+Validates the replies if trust anchors are configured and the zones are
+signed.
+This enforces DNSSEC validation on nameserver NS sets and the nameserver
+addresses that are encountered on the referral path to the answer.
+Default is off, because it burdens the authority servers, and it is not RFC
+standard, and could lead to performance problems because of the extra query
+load that is generated.
+Experimental option.
+If you enable it consider adding more numbers after the
+\fI\%target\-fetch\-policy\fP to increase
+the max depth that is checked to.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B harden\-algo\-downgrade: \fI<yes or no>\fP
+Harden against algorithm downgrade when multiple algorithms are advertised
+in the DS record.
+This works by first choosing only the strongest DS digest type as per
+\fI\%RFC 4509\fP (Unbound treats the highest algorithm as the strongest) and
+then expecting signatures from all the advertised signing algorithms from
+the chosen DS(es) to be present.
+If no, allows any one supported algorithm to validate the zone, even if
+other advertised algorithms are broken.
+\fI\%RFC 6840\fP mandates that zone signers must produce zones signed with all
advertised algorithms, but sometimes they do not.
-RFC 6840 also clarifies that this requirement is not for validators and
+\fI\%RFC 6840\fP also clarifies that this requirement is not for validators and
validators should accept any single valid path.
-It should thus be explicitly noted that this option violates RFC 6840 for
-DNSSEC validation and should only be used to perform a signature
+It should thus be explicitly noted that this option violates \fI\%RFC 6840\fP
+for DNSSEC validation and should only be used to perform a signature
completeness test to support troubleshooting.
-Using this option may break DNSSEC resolution with non-RFC6840-conforming
-signers and/or in multi-signer configurations that don't send all the
-advertised signatures.
-.TP
-.B harden\-unknown\-additional: \fI<yes or no>
+.sp
+\fBWARNING:\fP
+.INDENT 7.0
+.INDENT 3.5
+Using this option may break DNSSEC resolution with non \fI\%RFC 6840\fP
+conforming signers and/or in multi\-signer configurations that don\(aqt
+send all the advertised signatures.
+.UNINDENT
+.UNINDENT
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B harden\-unknown\-additional: \fI<yes or no>\fP
Harden against unknown records in the authority section and additional
-section. Default is no. If no, such records are copied from the upstream
-and presented to the client together with the answer. If yes, it could
-hamper future protocol developments that want to add records.
-.TP
-.B use\-caps\-for\-id: \fI<yes or no>
+section.
+If no, such records are copied from the upstream and presented to the
+client together with the answer.
+If yes, it could hamper future protocol developments that want to add
+records.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B use\-caps\-for\-id: \fI<yes or no>\fP
Use 0x20\-encoded random bits in the query to foil spoof attempts.
-This perturbs the lowercase and uppercase of query names sent to
-authority servers and checks if the reply still has the correct casing.
-Disabled by default.
+This perturbs the lowercase and uppercase of query names sent to authority
+servers and checks if the reply still has the correct casing.
This feature is an experimental implementation of draft dns\-0x20.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
.TP
-.B caps\-exempt: \fI<domain>
+.B caps\-exempt: \fI<domain>\fP
Exempt the domain so that it does not receive caps\-for\-id perturbed
-queries. For domains that do not support 0x20 and also fail with fallback
-because they keep sending different answers, like some load balancers.
+queries.
+For domains that do not support 0x20 and also fail with fallback because
+they keep sending different answers, like some load balancers.
Can be given multiple times, for different domains.
+.UNINDENT
+.INDENT 0.0
.TP
-.B caps\-whitelist: \fI<domain>
-Alternate syntax for \fBcaps\-exempt\fR.
+.B caps\-whitelist: \fI<domain>\fP
+Alternate syntax for \fI\%caps\-exempt\fP\&.
+.UNINDENT
+.INDENT 0.0
.TP
-.B qname\-minimisation: \fI<yes or no>
+.B qname\-minimisation: \fI<yes or no>\fP
Send minimum amount of information to upstream servers to enhance privacy.
Only send minimum required labels of the QNAME and set QTYPE to A when
-possible. Best effort approach; full QNAME and original QTYPE will be sent when
+possible.
+Best effort approach; full QNAME and original QTYPE will be sent when
upstream replies with a RCODE other than NOERROR, except when receiving
-NXDOMAIN from a DNSSEC signed zone. Default is yes.
-.TP
-.B qname\-minimisation\-strict: \fI<yes or no>
-QNAME minimisation in strict mode. Do not fall-back to sending full QNAME to
-potentially broken nameservers. A lot of domains will not be resolvable when
-this option in enabled. Only use if you know what you are doing.
-This option only has effect when qname-minimisation is enabled. Default is no.
-.TP
-.B aggressive\-nsec: \fI<yes or no>
-Aggressive NSEC uses the DNSSEC NSEC chain to synthesize NXDOMAIN
-and other denials, using information from previous NXDOMAINs answers.
-Default is yes. It helps to reduce the query rate towards targets that get
-a very high nonexistent name lookup rate.
-.TP
-.B private\-address: \fI<IP address or subnet>
-Give IPv4 of IPv6 addresses or classless subnets. These are addresses
-on your private network, and are not allowed to be returned for
-public internet names. Any occurrence of such addresses are removed
-from DNS answers. Additionally, the DNSSEC validator may mark the
-answers bogus. This protects against so\-called DNS Rebinding, where
-a user browser is turned into a network proxy, allowing remote access
-through the browser to other parts of your private network. Some names
-can be allowed to contain your private addresses, by default all the
-\fBlocal\-data\fR that you configured is allowed to, and you can specify
-additional names using \fBprivate\-domain\fR. No private addresses are
-enabled by default. We consider to enable this for the RFC1918 private
-IP address space by default in later releases. That would enable private
-addresses for 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16
-fd00::/8 and fe80::/10, since the RFC standards say these addresses
-should not be visible on the public internet. Turning on 127.0.0.0/8
-would hinder many spamblocklists as they use that. Adding ::ffff:0:0/96
-stops IPv4-mapped IPv6 addresses from bypassing the filter.
-.TP
-.B private\-domain: \fI<domain name>
+NXDOMAIN from a DNSSEC signed zone.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B qname\-minimisation\-strict: \fI<yes or no>\fP
+QNAME minimisation in strict mode.
+Do not fall\-back to sending full QNAME to potentially broken nameservers.
+A lot of domains will not be resolvable when this option in enabled.
+Only use if you know what you are doing.
+This option only has effect when
+\fI\%qname\-minimisation\fP is enabled.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B aggressive\-nsec: \fI<yes or no>\fP
+Aggressive NSEC uses the DNSSEC NSEC chain to synthesize NXDOMAIN and other
+denials, using information from previous NXDOMAINs answers.
+It helps to reduce the query rate towards targets that get a very high
+nonexistent name lookup rate.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B private\-address: \fI<IP address or subnet>\fP
+Give IPv4 of IPv6 addresses or classless subnets.
+These are addresses on your private network, and are not allowed to be
+returned for public internet names.
+Any occurrence of such addresses are removed from DNS answers.
+Additionally, the DNSSEC validator may mark the answers bogus.
+This protects against so\-called DNS Rebinding, where a user browser is
+turned into a network proxy, allowing remote access through the browser to
+other parts of your private network.
+.sp
+Some names can be allowed to contain your private addresses, by default all
+the \fI\%local\-data\fP that you configured is
+allowed to, and you can specify additional names using
+\fI\%private\-domain\fP\&.
+No private addresses are enabled by default.
+.sp
+We consider to enable this for the \fI\%RFC 1918\fP private IP address space by
+default in later releases.
+That would enable private addresses for \fB10.0.0.0/8\fP, \fB172.16.0.0/12\fP,
+\fB192.168.0.0/16\fP, \fB169.254.0.0/16\fP, \fBfd00::/8\fP and \fBfe80::/10\fP,
+since the RFC standards say these addresses should not be visible on the
+public internet.
+.sp
+Turning on \fB127.0.0.0/8\fP would hinder many spamblocklists as they use
+that.
+Adding \fB::ffff:0:0/96\fP stops IPv4\-mapped IPv6 addresses from bypassing
+the filter.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B private\-domain: \fI<domain name>\fP
Allow this domain, and all its subdomains to contain private addresses.
Give multiple times to allow multiple domain names to contain private
-addresses. Default is none.
-.TP
-.B unwanted\-reply\-threshold: \fI<number>
-If set, a total number of unwanted replies is kept track of in every thread.
-When it reaches the threshold, a defensive action is taken and a warning
-is printed to the log. The defensive action is to clear the rrset and
-message caches, hopefully flushing away any poison. A value of 10 million
-is suggested. Default is 0 (turned off).
-.TP
-.B do\-not\-query\-address: \fI<IP address>
-Do not query the given IP address. Can be IP4 or IP6. Append /num to
-indicate a classless delegation netblock, for example like
-10.2.3.4/24 or 2001::11/64.
-.TP
-.B do\-not\-query\-localhost: \fI<yes or no>
-If yes, localhost is added to the do\-not\-query\-address entries, both
-IP6 ::1 and IP4 127.0.0.1/8. If no, then localhost can be used to send
-queries to. Default is yes.
-.TP
-.B prefetch: \fI<yes or no>
-If yes, cache hits on message cache elements that are on their last 10 percent
-of their TTL value trigger a prefetch to keep the cache up to date.
-Default is no.
-Turning it on gives about 10 percent more traffic and load on the machine, but
-popular items do not expire from the cache.
-.TP
-.B prefetch\-key: \fI<yes or no>
+addresses.
+.sp
+Default: (none)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B unwanted\-reply\-threshold: \fI<number>\fP
+If set, a total number of unwanted replies is kept track of in every
+thread.
+When it reaches the threshold, a defensive action is taken and a warning is
+printed to the log.
+The defensive action is to clear the rrset and message caches, hopefully
+flushing away any poison.
+A value of 10 million is suggested.
+.sp
+Default: 0 (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B do\-not\-query\-address: \fI<IP address>\fP
+Do not query the given IP address.
+Can be IPv4 or IPv6.
+Append /num to indicate a classless delegation netblock, for example like
+\fB10.2.3.4/24\fP or \fB2001::11/64\fP\&.
+.sp
+Default: (none)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B do\-not\-query\-localhost: \fI<yes or no>\fP
+If yes, localhost is added to the
+\fI\%do\-not\-query\-address\fP entries,
+both IPv6 \fB::1\fP and IPv4 \fB127.0.0.1/8\fP\&.
+If no, then localhost can be used to send queries to.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B prefetch: \fI<yes or no>\fP
+If yes, cache hits on message cache elements that are on their last 10
+percent of their TTL value trigger a prefetch to keep the cache up to date.
+Turning it on gives about 10 percent more traffic and load on the machine,
+but popular items do not expire from the cache.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B prefetch\-key: \fI<yes or no>\fP
If yes, fetch the DNSKEYs earlier in the validation process, when a DS
-record is encountered. This lowers the latency of requests. It does use
-a little more CPU. Also if the cache is set to 0, it is no use. Default is no.
-.TP
-.B deny\-any: \fI<yes or no>
-If yes, deny queries of type ANY with an empty response. Default is no.
+record is encountered.
+This lowers the latency of requests.
+It does use a little more CPU.
+Also if the cache is set to 0, it is no use.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B deny\-any: \fI<yes or no>\fP
+If yes, deny queries of type ANY with an empty response.
If disabled, Unbound responds with a short list of resource records if some
can be found in the cache and makes the upstream type ANY query if there
are none.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
.TP
-.B rrset\-roundrobin: \fI<yes or no>
+.B rrset\-roundrobin: \fI<yes or no>\fP
If yes, Unbound rotates RRSet order in response (the random number is taken
-from the query ID, for speed and thread safety). Default is yes.
+from the query ID, for speed and thread safety).
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
.TP
-.B minimal-responses: \fI<yes or no>
+.B minimal\-responses: \fI<yes or no>\fP
If yes, Unbound does not insert authority/additional sections into response
-messages when those sections are not required. This reduces response
-size significantly, and may avoid TCP fallback for some responses which may
-cause a slight speedup. The default is yes, even though the DNS
-protocol RFCs mandate these sections, and the additional content could
-save roundtrips for clients that use the additional content.
+messages when those sections are not required.
+This reduces response size significantly, and may avoid TCP fallback for
+some responses which may cause a slight speedup.
+The default is yes, even though the DNS protocol RFCs mandate these
+sections, and the additional content could save roundtrips for clients that
+use the additional content.
However these sections are hardly used by clients.
Enabling prefetch can benefit clients that need the additional content
by trying to keep that content fresh in the cache.
-.TP
-.B disable-dnssec-lame-check: \fI<yes or no>
-If true, disables the DNSSEC lameness check in the iterator. This check
-sees if RRSIGs are present in the answer, when dnssec is expected,
-and retries another authority if RRSIGs are unexpectedly missing.
-The validator will insist in RRSIGs for DNSSEC signed domains regardless
-of this setting, if a trust anchor is loaded.
-.TP
-.B module\-config: \fI<"module names">
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B disable\-dnssec\-lame\-check: \fI<yes or no>\fP
+If true, disables the DNSSEC lameness check in the iterator.
+This check sees if RRSIGs are present in the answer, when dnssec is
+expected, and retries another authority if RRSIGs are unexpectedly missing.
+The validator will insist in RRSIGs for DNSSEC signed domains regardless of
+this setting, if a trust anchor is loaded.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B module\-config: \fI\(dq<module names>\(dq\fP
Module configuration, a list of module names separated by spaces, surround
-the string with quotes (""). The modules can be \fIrespip\fR,
-\fIvalidator\fR, or \fIiterator\fR (and possibly more, see below).
-Setting this to just "\fIiterator\fR" will result in a non\-validating
-server.
-Setting this to "\fIvalidator iterator\fR" will turn on DNSSEC validation.
-The ordering of the modules is significant, the order decides the
-order of processing.
-You must also set \fItrust\-anchors\fR for validation to be useful.
-Adding \fIrespip\fR to the front will cause RPZ processing to be done on
-all queries.
-The default is "\fIvalidator iterator\fR".
-.IP
+the string with quotes (\fB\(dq\(dq\fP).
+The modules can be \fBrespip\fP, \fBvalidator\fP, or \fBiterator\fP (and possibly
+more, see below).
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+The ordering of the modules is significant, the order decides the order
+of processing.
+.UNINDENT
+.UNINDENT
+.sp
+Setting this to just \(dqiterator\(dq will result in a non\-validating server.
+Setting this to \(dqvalidator iterator\(dq will turn on DNSSEC validation.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+You must also set trust\-anchors for validation to be useful.
+.UNINDENT
+.UNINDENT
+.sp
+Adding \fBrespip\fP to the front will cause RPZ processing to be done on all
+queries.
+.sp
Most modules that need to be listed here have to be listed at the beginning
-of the line. The subnetcachedb module has to be listed just before
-the iterator.
-The python module can be listed in different places, it then processes the
-output of the module it is just before. The dynlib module can be listed pretty
-much anywhere, it is only a very thin wrapper that allows dynamic libraries to
-run in its place.
-.TP
-.B trust\-anchor\-file: \fI<filename>
-File with trusted keys for validation. Both DS and DNSKEY entries can appear
-in the file. The format of the file is the standard DNS Zone file format.
-Default is "", or no trust anchor file.
-.TP
-.B auto\-trust\-anchor\-file: \fI<filename>
-File with trust anchor for one zone, which is tracked with RFC5011 probes.
+of the line.
+.sp
+The \fBsubnetcache\fP module has to be listed just before the iterator.
+.sp
+The \fBpython\fP module can be listed in different places, it then processes
+the output of the module it is just before.
+.sp
+The \fBdynlib\fP module can be listed pretty much anywhere, it is only a very
+thin wrapper that allows dynamic libraries to run in its place.
+.sp
+Default: \(dqvalidator iterator\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B trust\-anchor\-file: \fI<filename>\fP
+File with trusted keys for validation.
+Both DS and DNSKEY entries can appear in the file.
+The format of the file is the standard DNS Zone file format.
+.sp
+Default: \(dq\(dq (no trust anchor file)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B auto\-trust\-anchor\-file: \fI<filename>\fP
+File with trust anchor for one zone, which is tracked with \fI\%RFC 5011\fP
+probes.
The probes are run several times per month, thus the machine must be online
-frequently. The initial file can be one with contents as described in
-\fBtrust\-anchor\-file\fR. The file is written to when the anchor is updated,
-so the Unbound user must have write permission. Write permission to the file,
-but also to the directory it is in (to create a temporary file, which is
-necessary to deal with filesystem full events), it must also be inside the
-chroot (if that is used).
-.TP
-.B trust\-anchor: \fI<"Resource Record">
-A DS or DNSKEY RR for a key to use for validation. Multiple entries can be
-given to specify multiple trusted keys, in addition to the trust\-anchor\-files.
-The resource record is entered in the same format as 'dig' or 'drill' prints
-them, the same format as in the zone file. Has to be on a single line, with
-"" around it. A TTL can be specified for ease of cut and paste, but is ignored.
+frequently.
+The initial file can be one with contents as described in
+\fI\%trust\-anchor\-file\fP\&.
+The file is written to when the anchor is updated, so the Unbound user must
+have write permission.
+Write permission to the file, but also to the directory it is in (to create
+a temporary file, which is necessary to deal with filesystem full events),
+it must also be inside the \fI\%chroot\fP (if that is
+used).
+.sp
+Default: \(dq\(dq (no auto trust anchor file)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B trust\-anchor: \fI\(dq<Resource Record>\(dq\fP
+A DS or DNSKEY RR for a key to use for validation.
+Multiple entries can be given to specify multiple trusted keys, in addition
+to the \fI\%trust\-anchor\-file\fP\&.
+The resource record is entered in the same format as \fIdig(1)\fP or \fIdrill(1)\fP
+prints them, the same format as in the zone file.
+Has to be on a single line, with \fB\(dq\(dq\fP around it.
+A TTL can be specified for ease of cut and paste, but is ignored.
A class can be specified, but class IN is default.
-.TP
-.B trusted\-keys\-file: \fI<filename>
-File with trusted keys for validation. Specify more than one file
-with several entries, one file per entry. Like \fBtrust\-anchor\-file\fR
-but has a different file format. Format is BIND\-9 style format,
-the trusted\-keys { name flag proto algo "key"; }; clauses are read.
+.sp
+Default: (none)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B trusted\-keys\-file: \fI<filename>\fP
+File with trusted keys for validation.
+Specify more than one file with several entries, one file per entry.
+Like \fI\%trust\-anchor\-file\fP but has a
+different file format.
+Format is BIND\-9 style format, the \fBtrusted\-keys { name flag proto algo
+\(dqkey\(dq; };\fP clauses are read.
It is possible to use wildcards with this statement, the wildcard is
expanded on start and on reload.
-.TP
-.B trust\-anchor\-signaling: \fI<yes or no>
-Send RFC8145 key tag query after trust anchor priming. Default is yes.
-.TP
-.B root\-key\-sentinel: \fI<yes or no>
-Root key trust anchor sentinel. Default is yes.
-.TP
-.B domain\-insecure: \fI<domain name>
-Sets domain name to be insecure, DNSSEC chain of trust is ignored towards
-the domain name. So a trust anchor above the domain name can not make the
-domain secure with a DS record, such a DS record is then ignored.
-Can be given multiple times
-to specify multiple domains that are treated as if unsigned. If you set
-trust anchors for the domain they override this setting (and the domain
-is secured).
-.IP
+.sp
+Default: \(dq\(dq (no trusted keys file)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B trust\-anchor\-signaling: \fI<yes or no>\fP
+Send \fI\%RFC 8145\fP key tag query after trust anchor priming.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B root\-key\-sentinel: \fI<yes or no>\fP
+Root key trust anchor sentinel.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B domain\-insecure: \fI<domain name>\fP
+Sets \fI<domain name>\fP to be insecure, DNSSEC chain of trust is ignored
+towards the \fI<domain name>\fP\&.
+So a trust anchor above the domain name can not make the domain secure with
+a DS record, such a DS record is then ignored.
+Can be given multiple times to specify multiple domains that are treated as
+if unsigned.
+If you set trust anchors for the domain they override this setting (and the
+domain is secured).
+.sp
This can be useful if you want to make sure a trust anchor for external
-lookups does not affect an (unsigned) internal domain. A DS record
-externally can create validation failures for that internal domain.
-.TP
-.B val\-override\-date: \fI<rrsig\-style date spec>
-Default is "" or "0", which disables this debugging feature. If enabled by
-giving a RRSIG style date, that date is used for verifying RRSIG inception
-and expiration dates, instead of the current date. Do not set this unless
-you are debugging signature inception and expiration. The value \-1 ignores
-the date altogether, useful for some special applications.
-.TP
-.B val\-sig\-skew\-min: \fI<seconds>
+lookups does not affect an (unsigned) internal domain.
+A DS record externally can create validation failures for that internal
+domain.
+.sp
+Default: (none)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B val\-override\-date: \fI<rrsig\-style date spec>\fP
+.sp
+\fBWARNING:\fP
+.INDENT 7.0
+.INDENT 3.5
+Debugging feature!
+.UNINDENT
+.UNINDENT
+.sp
+If enabled by giving a RRSIG style date, that date is used for verifying
+RRSIG inception and expiration dates, instead of the current date.
+Do not set this unless you are debugging signature inception and
+expiration.
+The value \-1 ignores the date altogether, useful for some special
+applications.
+.sp
+Default: 0 (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B val\-sig\-skew\-min: \fI<seconds>\fP
Minimum number of seconds of clock skew to apply to validated signatures.
-A value of 10% of the signature lifetime (expiration \- inception) is
-used, capped by this setting. Default is 3600 (1 hour) which allows for
-daylight savings differences. Lower this value for more strict checking
-of short lived signatures.
-.TP
-.B val\-sig\-skew\-max: \fI<seconds>
+A value of 10% of the signature lifetime (expiration \- inception) is used,
+capped by this setting.
+Default is 3600 (1 hour) which allows for daylight savings differences.
+Lower this value for more strict checking of short lived signatures.
+.sp
+Default: 3600 (1 hour)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B val\-sig\-skew\-max: \fI<seconds>\fP
Maximum number of seconds of clock skew to apply to validated signatures.
-A value of 10% of the signature lifetime (expiration \- inception)
-is used, capped by this setting. Default is 86400 (24 hours) which
-allows for timezone setting problems in stable domains. Setting both
-min and max very low disables the clock skew allowances. Setting both
-min and max very high makes the validator check the signature timestamps
-less strictly.
-.TP
-.B val\-max\-restart: \fI<number>
-The maximum number the validator should restart validation with
-another authority in case of failed validation. Default is 5.
-.TP
-.B val\-bogus\-ttl: \fI<number>
-The time to live for bogus data. This is data that has failed validation;
-due to invalid signatures or other checks. The TTL from that data cannot be
-trusted, and this value is used instead. The value is in seconds, default 60.
+A value of 10% of the signature lifetime (expiration \- inception) is used,
+capped by this setting.
+Default is 86400 (24 hours) which allows for timezone setting problems in
+stable domains.
+Setting both min and max very low disables the clock skew allowances.
+Setting both min and max very high makes the validator check the signature
+timestamps less strictly.
+.sp
+Default: 86400 (24 hours)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B val\-max\-restart: \fI<number>\fP
+The maximum number the validator should restart validation with another
+authority in case of failed validation.
+.sp
+Default: 5
+.UNINDENT
+.INDENT 0.0
+.TP
+.B val\-bogus\-ttl: \fI<seconds>\fP
+The time to live for bogus data.
+This is data that has failed validation; due to invalid signatures or other
+checks.
+The TTL from that data cannot be trusted, and this value is used instead.
The time interval prevents repeated revalidation of bogus data.
+.sp
+Default: 60
+.UNINDENT
+.INDENT 0.0
.TP
-.B val\-clean\-additional: \fI<yes or no>
+.B val\-clean\-additional: \fI<yes or no>\fP
Instruct the validator to remove data from the additional section of secure
-messages that are not signed properly. Messages that are insecure, bogus,
-indeterminate or unchecked are not affected. Default is yes. Use this setting
-to protect the users that rely on this validator for authentication from
-potentially bad data in the additional section.
-.TP
-.B val\-log\-level: \fI<number>
-Have the validator print validation failures to the log. Regardless of
-the verbosity setting. Default is 0, off. At 1, for every user query
-that fails a line is printed to the logs. This way you can monitor what
-happens with validation. Use a diagnosis tool, such as dig or drill,
-to find out why validation is failing for these queries. At 2, not only
-the query that failed is printed but also the reason why Unbound thought
-it was wrong and which server sent the faulty data.
-.TP
-.B val\-permissive\-mode: \fI<yes or no>
-Instruct the validator to mark bogus messages as indeterminate. The security
-checks are performed, but if the result is bogus (failed security), the
-reply is not withheld from the client with SERVFAIL as usual. The client
-receives the bogus data. For messages that are found to be secure the AD bit
-is set in replies. Also logging is performed as for full validation.
-The default value is "no".
-.TP
-.B ignore\-cd\-flag: \fI<yes or no>
-Instruct Unbound to ignore the CD flag from clients and refuse to
-return bogus answers to them. Thus, the CD (Checking Disabled) flag
-does not disable checking any more. This is useful if legacy (w2008)
-servers that set the CD flag but cannot validate DNSSEC themselves are
-the clients, and then Unbound provides them with DNSSEC protection.
-The default value is "no".
-.TP
-.B disable\-edns\-do: \fI<yes or no>
+messages that are not signed properly.
+Messages that are insecure, bogus, indeterminate or unchecked are not
+affected.
+Use this setting to protect the users that rely on this validator for
+authentication from potentially bad data in the additional section.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B val\-log\-level: \fI<number>\fP
+Have the validator print validation failures to the log.
+Regardless of the verbosity setting.
+.sp
+At 1, for every user query that fails a line is printed to the logs.
+This way you can monitor what happens with validation.
+Use a diagnosis tool, such as dig or drill, to find out why validation is
+failing for these queries.
+.sp
+At 2, not only the query that failed is printed but also the reason why
+Unbound thought it was wrong and which server sent the faulty data.
+.sp
+Default: 0 (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B val\-permissive\-mode: \fI<yes or no>\fP
+Instruct the validator to mark bogus messages as indeterminate.
+The security checks are performed, but if the result is bogus (failed
+security), the reply is not withheld from the client with SERVFAIL as
+usual.
+The client receives the bogus data.
+For messages that are found to be secure the AD bit is set in replies.
+Also logging is performed as for full validation.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ignore\-cd\-flag: \fI<yes or no>\fP
+Instruct Unbound to ignore the CD flag from clients and refuse to return
+bogus answers to them.
+Thus, the CD (Checking Disabled) flag does not disable checking any more.
+This is useful if legacy (w2008) servers that set the CD flag but cannot
+validate DNSSEC themselves are the clients, and then Unbound provides them
+with DNSSEC protection.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B disable\-edns\-do: \fI<yes or no>\fP
Disable the EDNS DO flag in upstream requests.
-It breaks DNSSEC validation for Unbound's clients.
+It breaks DNSSEC validation for Unbound\(aqs clients.
This results in the upstream name servers to not include DNSSEC records in
their replies and could be helpful for devices that cannot handle DNSSEC
information.
validation (i.e., the validator module is enabled; default) this option is
implicitly turned off with a warning as to not break DNSSEC validation in
Unbound.
-Default is no.
-.TP
-.B serve\-expired: \fI<yes or no>
-If enabled, Unbound attempts to serve old responses from cache with a
-TTL of \fBserve\-expired\-reply\-ttl\fR in the response.
-By default the expired answer will be used after a resolution attempt errored
-out or is taking more than serve\-expired\-client\-timeout to resolve.
-Default is "no".
-.TP
-.B serve\-expired\-ttl: \fI<seconds>
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B serve\-expired: \fI<yes or no>\fP
+If enabled, Unbound attempts to serve old responses from cache with a TTL
+of \fI\%serve\-expired\-reply\-ttl\fP in
+the response.
+By default the expired answer will be used after a resolution attempt
+errored out or is taking more than
+\fI\%serve\-expired\-client\-timeout\fP
+to resolve.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B serve\-expired\-ttl: \fI<seconds>\fP
Limit serving of expired responses to configured seconds after expiration.
-0 disables the limit.
-This option only applies when \fBserve\-expired\fR is enabled.
+\fB0\fP disables the limit.
+This option only applies when
+\fI\%serve\-expired\fP is enabled.
A suggested value per RFC 8767 is between 86400 (1 day) and 259200 (3 days).
The default is 86400.
-.TP
-.B serve\-expired\-ttl\-reset: \fI<yes or no>
-Set the TTL of expired records to the \fBserve\-expired\-ttl\fR value after a
-failed attempt to retrieve the record from upstream. This makes sure that the
-expired records will be served as long as there are queries for it. Default is
-"no".
-.TP
-.B serve\-expired\-reply\-ttl: \fI<seconds>
-TTL value to use when replying with expired data. If
-\fBserve\-expired\-client\-timeout\fR is also used then it is RECOMMENDED to
-use 30 as the value (RFC 8767). The default is 30.
-.TP
-.B serve\-expired\-client\-timeout: \fI<msec>
+.sp
+Default: 86400
+.UNINDENT
+.INDENT 0.0
+.TP
+.B serve\-expired\-ttl\-reset: \fI<yes or no>\fP
+Set the TTL of expired records to the
+\fI\%serve\-expired\-ttl\fP value after a
+failed attempt to retrieve the record from upstream.
+This makes sure that the expired records will be served as long as there
+are queries for it.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B serve\-expired\-reply\-ttl: \fI<seconds>\fP
+TTL value to use when replying with expired data.
+If
+\fI\%serve\-expired\-client\-timeout\fP
+is also used then it is RECOMMENDED to use 30 as the value (\fI\%RFC 8767\fP).
+.sp
+Default: 30
+.UNINDENT
+.INDENT 0.0
+.TP
+.B serve\-expired\-client\-timeout: \fI<msec>\fP
Time in milliseconds before replying to the client with expired data.
-This essentially enables the serve-stale behavior as specified in
-RFC 8767 that first tries to resolve before immediately
-responding with expired data.
-Setting this to 0 will disable this behavior and instead serve the expired
-record immediately from the cache before attempting to refresh it via
-resolution.
-Default is 1800.
-.TP
-.B serve\-original\-ttl: \fI<yes or no>
+This essentially enables the serve\-stale behavior as specified in
+\fI\%RFC 8767\fP that first tries to resolve before immediately responding with
+expired data.
+Setting this to \fB0\fP will disable this behavior and instead serve the
+expired record immediately from the cache before attempting to refresh it
+via resolution.
+.sp
+Default: 1800
+.UNINDENT
+.INDENT 0.0
+.TP
+.B serve\-original\-ttl: \fI<yes or no>\fP
If enabled, Unbound will always return the original TTL as received from
-the upstream name server rather than the decrementing TTL as
-stored in the cache. This feature may be useful if Unbound serves as a
-front-end to a hidden authoritative name server. Enabling this feature does
-not impact cache expiry, it only changes the TTL Unbound embeds in responses to
-queries. Note that enabling this feature implicitly disables enforcement of
-the configured minimum and maximum TTL, as it is assumed users who enable this
-feature do not want Unbound to change the TTL obtained from an upstream server.
-Thus, the values set using \fBcache\-min\-ttl\fR and \fBcache\-max\-ttl\fR are
-ignored.
-Default is "no".
-.TP
-.B val\-nsec3\-keysize\-iterations: \fI<"list of values">
+the upstream name server rather than the decrementing TTL as stored in the
+cache.
+This feature may be useful if Unbound serves as a front\-end to a hidden
+authoritative name server.
+.sp
+Enabling this feature does not impact cache expiry, it only changes the TTL
+Unbound embeds in responses to queries.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+Enabling this feature implicitly disables enforcement of the configured
+minimum and maximum TTL, as it is assumed users who enable this feature
+do not want Unbound to change the TTL obtained from an upstream server.
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+The values set using \fI\%cache\-min\-ttl\fP
+and \fI\%cache\-max\-ttl\fP are ignored.
+.UNINDENT
+.UNINDENT
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B val\-nsec3\-keysize\-iterations: <\(dqlist of values\(dq>
List of keysize and iteration count values, separated by spaces, surrounded
-by quotes. Default is "1024 150 2048 150 4096 150". This determines the
-maximum allowed NSEC3 iteration count before a message is simply marked
-insecure instead of performing the many hashing iterations. The list must
-be in ascending order and have at least one entry. If you set it to
-"1024 65535" there is no restriction to NSEC3 iteration values.
-This table must be kept short; a very long list could cause slower operation.
-.TP
-.B zonemd\-permissive\-mode: \fI<yes or no>
-If enabled the ZONEMD verification failures are only logged and do not cause
-the zone to be blocked and only return servfail. Useful for testing out
-if it works, or if the operator only wants to be notified of a problem without
-disrupting service. Default is no.
-.TP
-.B add\-holddown: \fI<seconds>
-Instruct the \fBauto\-trust\-anchor\-file\fR probe mechanism for RFC5011
-autotrust updates to add new trust anchors only after they have been
-visible for this time. Default is 30 days as per the RFC.
-.TP
-.B del\-holddown: \fI<seconds>
-Instruct the \fBauto\-trust\-anchor\-file\fR probe mechanism for RFC5011
-autotrust updates to remove revoked trust anchors after they have been
-kept in the revoked list for this long. Default is 30 days as per
-the RFC.
-.TP
-.B keep\-missing: \fI<seconds>
-Instruct the \fBauto\-trust\-anchor\-file\fR probe mechanism for RFC5011
-autotrust updates to remove missing trust anchors after they have been
-unseen for this long. This cleans up the state file if the target zone
-does not perform trust anchor revocation, so this makes the auto probe
-mechanism work with zones that perform regular (non\-5011) rollovers.
-The default is 366 days. The value 0 does not remove missing anchors,
-as per the RFC.
-.TP
-.B permit\-small\-holddown: \fI<yes or no>
-Debug option that allows the autotrust 5011 rollover timers to assume
-very small values. Default is no.
-.TP
-.B key\-cache\-size: \fI<number>
-Number of bytes size of the key cache. Default is 4 megabytes.
-A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+by quotes.
+This determines the maximum allowed NSEC3 iteration count before a message
+is simply marked insecure instead of performing the many hashing
+iterations.
+The list must be in ascending order and have at least one entry.
+If you set it to \(dq1024 65535\(dq there is no restriction to NSEC3 iteration
+values.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This table must be kept short; a very long list could cause slower
+operation.
+.UNINDENT
+.UNINDENT
+.sp
+Default: \(dq1024 150 2048 150 4096 150\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B zonemd\-permissive\-mode: \fI<yes or no>\fP
+If enabled the ZONEMD verification failures are only logged and do not
+cause the zone to be blocked and only return servfail.
+Useful for testing out if it works, or if the operator only wants to be
+notified of a problem without disrupting service.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B add\-holddown: \fI<seconds>\fP
+Instruct the
+\fI\%auto\-trust\-anchor\-file\fP probe
+mechanism for \fI\%RFC 5011\fP autotrust updates to add new trust anchors only
+after they have been visible for this time.
+.sp
+Default: 2592000 (30 days as per the RFC)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B del\-holddown: \fI<seconds>\fP
+Instruct the
+\fI\%auto\-trust\-anchor\-file\fP probe
+mechanism for \fI\%RFC 5011\fP autotrust updates to remove revoked trust anchors
+after they have been kept in the revoked list for this long.
+.sp
+Default: 2592000 (30 days as per the RFC)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B keep\-missing: \fI<seconds>\fP
+Instruct the
+\fI\%auto\-trust\-anchor\-file\fP probe
+mechanism for \fI\%RFC 5011\fP autotrust updates to remove missing trust anchors
+after they have been unseen for this long.
+This cleans up the state file if the target zone does not perform trust
+anchor revocation, so this makes the auto probe mechanism work with zones
+that perform regular (non\-5011) rollovers.
+The value 0 does not remove missing anchors, as per the RFC.
+.sp
+Default: 31622400 (366 days)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B permit\-small\-holddown: \fI<yes or no>\fP
+Debug option that allows the autotrust 5011 rollover timers to assume very
+small values.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B key\-cache\-size: \fI<number>\fP
+Number of bytes size of the key cache.
+A plain number is in bytes, append \(aqk\(aq, \(aqm\(aq or \(aqg\(aq for kilobytes, megabytes
or gigabytes (1024*1024 bytes in a megabyte).
+.sp
+Default: 4m
+.UNINDENT
+.INDENT 0.0
.TP
-.B key\-cache\-slabs: \fI<number>
+.B key\-cache\-slabs: \fI<number>\fP
Number of slabs in the key cache.
Slabs reduce lock contention by threads.
Must be set to a power of 2.
Setting (close) to the number of cpus is a fairly good setting.
-If left unconfigured, it will be configured automatically to be a power of 2
-close to the number of configured threads in multi-threaded environments.
-.TP
-.B neg\-cache\-size: \fI<number>
-Number of bytes size of the aggressive negative cache. Default is 1 megabyte.
-A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+If left unconfigured, it will be configured automatically to be a power of
+2 close to the number of configured threads in multi\-threaded environments.
+.sp
+Default: (unconfigured)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B neg\-cache\-size: \fI<number>\fP
+Number of bytes size of the aggressive negative cache.
+A plain number is in bytes, append \(aqk\(aq, \(aqm\(aq or \(aqg\(aq for kilobytes, megabytes
or gigabytes (1024*1024 bytes in a megabyte).
-.TP
-.B unblock\-lan\-zones: \fI<yes or no>
-Default is disabled. If enabled, then for private address space,
-the reverse lookups are no longer filtered. This allows Unbound when
-running as dns service on a host where it provides service for that host,
-to put out all of the queries for the 'lan' upstream. When enabled,
-only localhost, 127.0.0.1 reverse and ::1 reverse zones are configured
-with default local zones. Disable the option when Unbound is running
-as a (DHCP-) DNS network resolver for a group of machines, where such
-lookups should be filtered (RFC compliance), this also stops potential
-data leakage about the local network to the upstream DNS servers.
-.TP
-.B insecure\-lan\-zones: \fI<yes or no>
-Default is disabled. If enabled, then reverse lookups in private
-address space are not validated. This is usually required whenever
-\fIunblock\-lan\-zones\fR is used.
-.TP
-.B local\-zone: \fI<zone> <type>
-Configure a local zone. The type determines the answer to give if
-there is no match from local\-data. The types are deny, refuse, static,
-transparent, redirect, nodefault, typetransparent, inform, inform_deny,
-inform_redirect, always_transparent, block_a, always_refuse, always_nxdomain,
-always_null, noview, and are explained below. After that the default settings
-are listed. Use local\-data: to enter data into the local zone. Answers for
-local zones are authoritative DNS answers. By default the zones are class IN.
-.IP
-If you need more complicated authoritative data, with referrals, wildcards,
-CNAME/DNAME support, or DNSSEC authoritative service, setup a stub\-zone for
-it as detailed in the stub zone section below. A stub\-zone can be used to
-have unbound send queries to another server, an authoritative server, to
-fetch the information. With a forward\-zone, unbound sends queries to a server
-that is a recursive server to fetch the information. With an auth\-zone a
-zone can be loaded from file and used, it can be used like a local\-zone
-for users downstream, or the auth\-zone information can be used to fetch
-information from when resolving like it is an upstream server. The
-forward\-zone and auth\-zone options are described in their sections below.
-If you want to perform filtering of the information that the users can fetch,
-the local\-zone and local\-data statements allow for this, but also the
-rpz functionality can be used, described in the RPZ section.
-.TP 10
-\h'5'\fIdeny\fR
+.sp
+Default: 1m
+.UNINDENT
+.INDENT 0.0
+.TP
+.B unblock\-lan\-zones: \fI<yes or no>\fP
+If enabled, then for private address space, the reverse lookups are no
+longer filtered.
+This allows Unbound when running as dns service on a host where it provides
+service for that host, to put out all of the queries for the \(aqlan\(aq
+upstream.
+When enabled, only localhost, \fB127.0.0.1\fP reverse and \fB::1\fP reverse
+zones are configured with default local zones.
+Disable the option when Unbound is running as a (DHCP\-) DNS network
+resolver for a group of machines, where such lookups should be filtered
+(RFC compliance), this also stops potential data leakage about the local
+network to the upstream DNS servers.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B insecure\-lan\-zones: \fI<yes or no>\fP
+If enabled, then reverse lookups in private address space are not
+validated.
+This is usually required whenever
+\fI\%unblock\-lan\-zones\fP is used.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local\-zone: \fI<zone> <type>\fP
+Configure a local zone.
+The type determines the answer to give if there is no match from
+\fI\%local\-data\fP\&.
+The types are
+\fI\%deny\fP,
+\fI\%refuse\fP,
+\fI\%static\fP,
+\fI\%transparent\fP,
+\fI\%redirect\fP,
+\fI\%nodefault\fP,
+\fI\%typetransparent\fP,
+\fI\%inform\fP,
+\fI\%inform_deny\fP,
+\fI\%inform_redirect\fP,
+\fI\%always_transparent\fP,
+\fI\%block_a\fP,
+\fI\%always_refuse\fP,
+\fI\%always_nxdomain\fP,
+\fI\%always_null\fP,
+\fI\%noview\fP,
+and are explained below.
+After that the default settings are listed.
+Use \fI\%local\-data\fP to enter data into the
+local zone.
+Answers for local zones are authoritative DNS answers.
+By default the zones are class IN.
+.sp
+If you need more complicated authoritative data, with referrals,
+wildcards, CNAME/DNAME support, or DNSSEC authoritative service,
+setup a \fI\%stub\-zone\fP for it as detailed in the
+stub zone section below.
+A \fI\%stub\-zone\fP can be used to have unbound
+send queries to another server, an authoritative server, to fetch the
+information.
+With a \fI\%forward\-zone\fP, unbound sends
+queries to a server that is a recursive server to fetch the information.
+With an \fI\%auth\-zone\fP a zone can be loaded from
+file and used, it can be used like a local zone for users downstream, or
+the \fI\%auth\-zone\fP information can be used to fetch
+information from when resolving like it is an upstream server.
+The \fI\%forward\-zone\fP and
+\fI\%auth\-zone\fP options are described in their
+sections below.
+If you want to perform filtering of the information that the users can
+fetch, the \fI\%local\-zone\fP and
+\fI\%local\-data\fP statements allow for this, but
+also the \fI\%rpz\fP functionality can be used, described
+in the RPZ section.
+.INDENT 7.0
+.TP
+.B deny
Do not send an answer, drop the query.
If there is a match from local data, the query is answered.
-.TP 10
-\h'5'\fIrefuse\fR
+.UNINDENT
+.INDENT 7.0
+.TP
+.B refuse
Send an error message reply, with rcode REFUSED.
If there is a match from local data, the query is answered.
-.TP 10
-\h'5'\fIstatic\fR
-If there is a match from local data, the query is answered.
-Otherwise, the query is answered with nodata or nxdomain.
-For a negative answer a SOA is included in the answer if present
-as local\-data for the zone apex domain.
-.TP 10
-\h'5'\fItransparent\fR
+.UNINDENT
+.INDENT 7.0
+.TP
+.B static
If there is a match from local data, the query is answered.
-Otherwise if the query has a different name, the query is resolved normally.
-If the query is for a name given in localdata but no such type of data is
-given in localdata, then a noerror nodata answer is returned.
-If no local\-zone is given local\-data causes a transparent zone
+Otherwise, the query is answered with NODATA or NXDOMAIN.
+For a negative answer a SOA is included in the answer if present as
+\fI\%local\-data\fP for the zone apex domain.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B transparent
+If there is a match from \fI\%local\-data\fP,
+the query is answered.
+Otherwise if the query has a different name, the query is resolved
+normally.
+If the query is for a name given in
+\fI\%local\-data\fP but no such type of data is
+given in localdata, then a NOERROR NODATA answer is returned.
+If no \fI\%local\-zone\fP is given
+\fI\%local\-data\fP causes a transparent zone
to be created by default.
-.TP 10
-\h'5'\fItypetransparent\fR
-If there is a match from local data, the query is answered. If the query
-is for a different name, or for the same name but for a different type,
-the query is resolved normally. So, similar to transparent but types
-that are not listed in local data are resolved normally, so if an A record
-is in the local data that does not cause a nodata reply for AAAA queries.
-.TP 10
-\h'5'\fIredirect\fR
+.UNINDENT
+.INDENT 7.0
+.TP
+.B typetransparent
+If there is a match from local data, the query is answered.
+If the query is for a different name, or for the same name but for a
+different type, the query is resolved normally.
+So, similar to
+\fI\%transparent\fP but types
+that are not listed in local data are resolved normally, so if an A
+record is in the local data that does not cause a NODATA reply for AAAA
+queries.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B redirect
The query is answered from the local data for the zone name.
There may be no local data beneath the zone name.
-This answers queries for the zone, and all subdomains of the zone
-with the local data for the zone.
-It can be used to redirect a domain to return a different address record
-to the end user, with
-local\-zone: "example.com." redirect and
-local\-data: "example.com. A 127.0.0.1"
-queries for www.example.com and www.foo.example.com are redirected, so
-that users with web browsers cannot access sites with suffix example.com.
-.TP 10
-\h'5'\fIinform\fR
-The query is answered normally, same as transparent. The client IP
-address (@portnumber) is printed to the logfile. The log message is:
-timestamp, unbound-pid, info: zonename inform IP@port queryname type
-class. This option can be used for normal resolution, but machines
-looking up infected names are logged, eg. to run antivirus on them.
-.TP 10
-\h'5'\fIinform_deny\fR
-The query is dropped, like 'deny', and logged, like 'inform'. Ie. find
-infected machines without answering the queries.
-.TP 10
-\h'5'\fIinform_redirect\fR
-The query is redirected, like 'redirect', and logged, like 'inform'.
+This answers queries for the zone, and all subdomains of the zone with
+the local data for the zone.
+It can be used to redirect a domain to return a different address
+record to the end user, with:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+local\-zone: \(dqexample.com.\(dq redirect
+local\-data: \(dqexample.com. A 127.0.0.1\(dq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+queries for \fBwww.example.com\fP and \fBwww.foo.example.com\fP are
+redirected, so that users with web browsers cannot access sites with
+suffix example.com.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B inform
+The query is answered normally, same as
+\fI\%transparent\fP\&.
+The client IP address (@portnumber) is printed to the logfile.
+The log message is:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+timestamp, unbound\-pid, info: zonename inform IP@port queryname type class.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This option can be used for normal resolution, but machines looking up
+infected names are logged, eg. to run antivirus on them.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B inform_deny
+The query is dropped, like
+\fI\%deny\fP, and logged, like
+\fI\%inform\fP\&.
+Ie. find infected machines without answering the queries.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B inform_redirect
+The query is redirected, like
+\fI\%redirect\fP, and logged,
+like \fI\%inform\fP\&.
Ie. answer queries with fixed data and also log the machines that ask.
-.TP 10
-\h'5'\fIalways_transparent\fR
-Like transparent, but ignores local data and resolves normally.
-.TP 10
-\h'5'\fIblock_a\fR
-Like transparent, but ignores local data and resolves normally all query
-types excluding A. For A queries it unconditionally returns NODATA.
-Useful in cases when there is a need to explicitly force all apps to use
-IPv6 protocol and avoid any queries to IPv4.
-.TP 10
-\h'5'\fIalways_refuse\fR
-Like refuse, but ignores local data and refuses the query.
-.TP 10
-\h'5'\fIalways_nxdomain\fR
-Like static, but ignores local data and returns nxdomain for the query.
-.TP 10
-\h'5'\fIalways_nodata\fR
-Like static, but ignores local data and returns nodata for the query.
-.TP 10
-\h'5'\fIalways_deny\fR
-Like deny, but ignores local data and drops the query.
-.TP 10
-\h'5'\fIalways_null\fR
-Always returns 0.0.0.0 or ::0 for every name in the zone. Like redirect
-with zero data for A and AAAA. Ignores local data in the zone. Used for
-some block lists.
-.TP 10
-\h'5'\fInoview\fR
-Breaks out of that view and moves towards the global local zones for answer
-to the query. If the view first is no, it'll resolve normally. If view first
-is enabled, it'll break perform that step and check the global answers.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B always_transparent
+Like \fI\%transparent\fP, but
+ignores local data and resolves normally.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B block_a
+Like \fI\%transparent\fP, but
+ignores local data and resolves normally all query types excluding A.
+For A queries it unconditionally returns NODATA.
+Useful in cases when there is a need to explicitly force all apps to
+use IPv6 protocol and avoid any queries to IPv4.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B always_refuse
+Like \fI\%refuse\fP, but ignores
+local data and refuses the query.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B always_nxdomain
+Like \fI\%static\fP, but ignores
+local data and returns NXDOMAIN for the query.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B always_nodata
+Like \fI\%static\fP, but ignores
+local data and returns NODATA for the query.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B always_deny
+Like \fI\%deny\fP, but ignores local
+data and drops the query.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B always_null
+Always returns \fB0.0.0.0\fP or \fB::0\fP for every name in the zone.
+Like \fI\%redirect\fP with zero
+data for A and AAAA.
+Ignores local data in the zone.
+Used for some block lists.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B noview
+Breaks out of that view and moves towards the global local zones for
+answer to the query.
+If the \fI\%view\-first\fP is no, it\(aqll
+resolve normally.
+If \fI\%view\-first\fP is enabled, it\(aqll
+break perform that step and check the global answers.
For when the view has view specific overrides but some zone has to be
answered from global local zone contents.
-.TP 10
-\h'5'\fInodefault\fR
-Used to turn off default contents for AS112 zones. The other types
-also turn off default contents for the zone. The 'nodefault' option
-has no other effect than turning off default contents for the
-given zone. Use \fInodefault\fR if you use exactly that zone, if you want to
-use a subzone, use \fItransparent\fR.
-.P
-The default zones are localhost, reverse 127.0.0.1 and ::1, the home.arpa,
-the resolver.arpa, the service.arpa,
-the onion, test, invalid and the AS112 zones. The AS112 zones are reverse
-DNS zones for private use and reserved IP addresses for which the servers
-on the internet cannot provide correct answers. They are configured by
-default to give nxdomain (no reverse information) answers. The defaults
-can be turned off by specifying your own local\-zone of that name, or
-using the 'nodefault' type. Below is a list of the default zone contents.
-.TP 10
-\h'5'\fIlocalhost\fR
-The IP4 and IP6 localhost information is given. NS and SOA records are provided
-for completeness and to satisfy some DNS update tools. Default content:
+.UNINDENT
+.INDENT 7.0
+.TP
+.B nodefault
+Used to turn off default contents for AS112 zones.
+The other types also turn off default contents for the zone.
+The \fI\%nodefault\fP option has
+no other effect than turning off default contents for the given zone.
+Use \fI\%nodefault\fP if you use
+exactly that zone, if you want to use a subzone, use
+\fI\%transparent\fP\&.
+.UNINDENT
+.sp
+The default zones are localhost, reverse \fB127.0.0.1\fP and \fB::1\fP, the
+\fBhome.arpa\fP, \fBresolver.arpa\fP, \fBservice.arpa\fP, \fBonion\fP, \fBtest\fP,
+\fBinvalid\fP and the AS112 zones.
+The AS112 zones are reverse DNS zones for private use and reserved IP
+addresses for which the servers on the internet cannot provide correct
+answers.
+They are configured by default to give NXDOMAIN (no reverse information)
+answers.
+.sp
+The defaults can be turned off by specifying your own
+\fI\%local\-zone\fP of that name, or using the
+\fI\%nodefault\fP type.
+Below is a list of the default zone contents.
+.INDENT 7.0
+.TP
+.B localhost
+The IPv4 and IPv6 localhost information is given.
+NS and SOA records are provided for completeness and to satisfy some
+DNS update tools.
+Default content:
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-local\-zone: "localhost." redirect
-local\-data: "localhost. 10800 IN NS localhost."
-local\-data: "localhost. 10800 IN
- SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
-local\-data: "localhost. 10800 IN A 127.0.0.1"
-local\-data: "localhost. 10800 IN AAAA ::1"
+.ft C
+local\-zone: \(dqlocalhost.\(dq redirect
+local\-data: \(dqlocalhost. 10800 IN NS localhost.\(dq
+local\-data: \(dqlocalhost. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800\(dq
+local\-data: \(dqlocalhost. 10800 IN A 127.0.0.1\(dq
+local\-data: \(dqlocalhost. 10800 IN AAAA ::1\(dq
+.ft P
.fi
-.TP 10
-\h'5'\fIreverse IPv4 loopback\fR
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B reverse IPv4 loopback
Default content:
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-local\-zone: "127.in\-addr.arpa." static
-local\-data: "127.in\-addr.arpa. 10800 IN NS localhost."
-local\-data: "127.in\-addr.arpa. 10800 IN
- SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
-local\-data: "1.0.0.127.in\-addr.arpa. 10800 IN
- PTR localhost."
+.ft C
+local\-zone: \(dq127.in\-addr.arpa.\(dq static
+local\-data: \(dq127.in\-addr.arpa. 10800 IN NS localhost.\(dq
+local\-data: \(dq127.in\-addr.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800\(dq
+local\-data: \(dq1.0.0.127.in\-addr.arpa. 10800 IN PTR localhost.\(dq
+.ft P
.fi
-.TP 10
-\h'5'\fIreverse IPv6 loopback\fR
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B reverse IPv6 loopback
Default content:
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-local\-zone: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
- 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." static
-local\-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
- 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
- NS localhost."
-local\-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
- 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
- SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
-local\-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
- 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
- PTR localhost."
+.ft C
+local\-zone: \(dq1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa.\(dq static
+local\-data: \(dq1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN NS localhost.\(dq
+local\-data: \(dq1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800\(dq
+local\-data: \(dq1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN PTR localhost.\(dq
+.ft P
.fi
-.TP 10
-\h'5'\fIhome.arpa (RFC 8375)\fR
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+home.arpa (\fI\%RFC 8375\fP)
Default content:
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-local\-zone: "home.arpa." static
-local\-data: "home.arpa. 10800 IN NS localhost."
-local\-data: "home.arpa. 10800 IN
- SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+.ft C
+local\-zone: \(dqhome.arpa.\(dq static
+local\-data: \(dqhome.arpa. 10800 IN NS localhost.\(dq
+local\-data: \(dqhome.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800\(dq
+.ft P
.fi
-.TP 10
-\h'5'\fIresolver.arpa (RFC 9462)\fR
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+resolver.arpa (\fI\%RFC 9462\fP)
Default content:
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-local\-zone: "resolver.arpa." static
-local\-data: "resolver.arpa. 10800 IN NS localhost."
-local\-data: "resolver.arpa. 10800 IN
- SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+.ft C
+local\-zone: \(dqresolver.arpa.\(dq static
+local\-data: \(dqresolver.arpa. 10800 IN NS localhost.\(dq
+local\-data: \(dqresolver.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800\(dq
+.ft P
.fi
-.TP 10
-\h'5'\fIservice.arpa (draft-ietf-dnssd-srp-25)\fR
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B service.arpa (draft\-ietf\-dnssd\-srp\-25)
Default content:
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-local\-zone: "service.arpa." static
-local\-data: "service.arpa. 10800 IN NS localhost."
-local\-data: "service.arpa. 10800 IN
- SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+.ft C
+local\-zone: \(dqservice.arpa.\(dq static
+local\-data: \(dqservice.arpa. 10800 IN NS localhost.\(dq
+local\-data: \(dqservice.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800\(dq
+.ft P
.fi
-.TP 10
-\h'5'\fIonion (RFC 7686)\fR
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+onion (\fI\%RFC 7686\fP)
Default content:
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-local\-zone: "onion." static
-local\-data: "onion. 10800 IN NS localhost."
-local\-data: "onion. 10800 IN
- SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+.ft C
+local\-zone: \(dqonion.\(dq static
+local\-data: \(dqonion. 10800 IN NS localhost.\(dq
+local\-data: \(dqonion. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800\(dq
+.ft P
.fi
-.TP 10
-\h'5'\fItest (RFC 6761)\fR
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+test (\fI\%RFC 6761\fP)
Default content:
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-local\-zone: "test." static
-local\-data: "test. 10800 IN NS localhost."
-local\-data: "test. 10800 IN
- SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+.ft C
+local\-zone: \(dqtest.\(dq static
+local\-data: \(dqtest. 10800 IN NS localhost.\(dq
+local\-data: \(dqtest. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800\(dq
+.ft P
.fi
-.TP 10
-\h'5'\fIinvalid (RFC 6761)\fR
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+invalid (\fI\%RFC 6761\fP)
Default content:
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-local\-zone: "invalid." static
-local\-data: "invalid. 10800 IN NS localhost."
-local\-data: "invalid. 10800 IN
- SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+.ft C
+local\-zone: \(dqinvalid.\(dq static
+local\-data: \(dqinvalid. 10800 IN NS localhost.\(dq
+local\-data: \(dqinvalid. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800\(dq
+.ft P
.fi
-.TP 10
-\h'5'\fIreverse RFC1918 local use zones\fR
-Reverse data for zones 10.in\-addr.arpa, 16.172.in\-addr.arpa to
-31.172.in\-addr.arpa, 168.192.in\-addr.arpa.
-The \fBlocal\-zone:\fR is set static and as \fBlocal\-data:\fR SOA and NS
-records are provided.
-.TP 10
-\h'5'\fIreverse RFC3330 IP4 this, link\-local, testnet and broadcast\fR
-Reverse data for zones 0.in\-addr.arpa, 254.169.in\-addr.arpa,
-2.0.192.in\-addr.arpa (TEST NET 1), 100.51.198.in\-addr.arpa (TEST NET 2),
-113.0.203.in\-addr.arpa (TEST NET 3), 255.255.255.255.in\-addr.arpa.
-And from 64.100.in\-addr.arpa to 127.100.in\-addr.arpa (Shared Address Space).
-.TP 10
-\h'5'\fIreverse RFC4291 IP6 unspecified\fR
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+reverse local use zones (\fI\%RFC 1918\fP)
+Reverse data for zones \fB10.in\-addr.arpa\fP, \fB16.172.in\-addr.arpa\fP to
+\fB31.172.in\-addr.arpa\fP, \fB168.192.in\-addr.arpa\fP\&.
+The \fI\%local\-zone\fP is set static and as
+\fI\%local\-data\fP SOA and NS records are
+provided.
+.UNINDENT
+.INDENT 7.0
+.TP
+special\-use IPv4 Addresses (\fI\%RFC 3330\fP)
+Reverse data for zones \fB0.in\-addr.arpa\fP (this), \fB254.169.in\-addr.arpa\fP (link\-local),
+\fB2.0.192.in\-addr.arpa\fP (TEST NET 1), \fB100.51.198.in\-addr.arpa\fP
+(TEST NET 2), \fB113.0.203.in\-addr.arpa\fP (TEST NET 3),
+\fB255.255.255.255.in\-addr.arpa\fP (broadcast).
+And from \fB64.100.in\-addr.arpa\fP to \fB127.100.in\-addr.arpa\fP (Shared
+Address Space).
+.UNINDENT
+.INDENT 7.0
+.TP
+reverse IPv6 unspecified (\fI\%RFC 4291\fP)
Reverse data for zone
+\fB0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa.\fP
+.UNINDENT
+.INDENT 7.0
+.TP
+reverse IPv6 Locally Assigned Local Addresses (\fI\%RFC 4193\fP)
+Reverse data for zone \fBD.F.ip6.arpa\fP\&.
+.UNINDENT
+.INDENT 7.0
+.TP
+reverse IPv6 Link Local Addresses (\fI\%RFC 4291\fP)
+Reverse data for zones \fB8.E.F.ip6.arpa\fP to \fBB.E.F.ip6.arpa\fP\&.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B reverse IPv6 Example Prefix
+Reverse data for zone \fB8.B.D.0.1.0.0.2.ip6.arpa\fP\&.
+This zone is used for tutorials and examples.
+You can remove the block on this zone with:
+.INDENT 7.0
+.INDENT 3.5
+.sp
.nf
-0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
-0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa.
-.fi
-.TP 10
-\h'5'\fIreverse RFC4193 IPv6 Locally Assigned Local Addresses\fR
-Reverse data for zone D.F.ip6.arpa.
-.TP 10
-\h'5'\fIreverse RFC4291 IPv6 Link Local Addresses\fR
-Reverse data for zones 8.E.F.ip6.arpa to B.E.F.ip6.arpa.
-.TP 10
-\h'5'\fIreverse IPv6 Example Prefix\fR
-Reverse data for zone 8.B.D.0.1.0.0.2.ip6.arpa. This zone is used for
-tutorials and examples. You can remove the block on this zone with:
-.nf
- local\-zone: 8.B.D.0.1.0.0.2.ip6.arpa. nodefault
+.ft C
+local\-zone: 8.B.D.0.1.0.0.2.ip6.arpa. nodefault
+.ft P
.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
You can also selectively unblock a part of the zone by making that part
-transparent with a local\-zone statement.
+transparent with a \fI\%local\-zone\fP statement.
This also works with the other default zones.
-.\" End of local-zone listing.
-.TP 5
-.B local\-data: \fI"<resource record string>"
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local\-data: \fI\(dq<resource record string>\(dq\fP
Configure local data, which is served in reply to queries for it.
-The query has to match exactly unless you configure the local\-zone as
-redirect. If not matched exactly, the local\-zone type determines
-further processing. If local\-data is configured that is not a subdomain of
-a local\-zone, a transparent local\-zone is configured.
-For record types such as TXT, use single quotes, as in
-local\-data: 'example. TXT "text"'.
-.IP
-If you need more complicated authoritative data, with referrals, wildcards,
-CNAME/DNAME support, or DNSSEC authoritative service, setup a stub\-zone for
-it as detailed in the stub zone section below.
-.TP 5
-.B local\-data\-ptr: \fI"IPaddr name"
+The query has to match exactly unless you configure the
+\fI\%local\-zone\fP as redirect.
+If not matched exactly, the \fI\%local\-zone\fP
+type determines further processing.
+If \fI\%local\-data\fP is configured that is not a
+subdomain of a \fI\%local\-zone\fP, a
+\fI\%transparent local\-zone\fP is
+configured.
+For record types such as TXT, use single quotes, as in:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+local\-data: \(aqexample. TXT \(dqtext\(dq\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+If you need more complicated authoritative data, with referrals,
+wildcards, CNAME/DNAME support, or DNSSEC authoritative service, setup
+a \fI\%stub\-zone\fP for it as detailed in the stub
+zone section below.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local\-data\-ptr: \fI\(dqIPaddr name\(dq\fP
Configure local data shorthand for a PTR record with the reversed IPv4 or
-IPv6 address and the host name. For example "192.0.2.4 www.example.com".
-TTL can be inserted like this: "2001:DB8::4 7200 www.example.com"
-.TP 5
-.B local\-zone\-tag: \fI<zone> <"list of tags">
-Assign tags to localzones. Tagged localzones will only be applied when the
-used access-control element has a matching tag. Tags must be defined in
-\fIdefine\-tags\fR. Enclose list of tags in quotes ("") and put spaces between
-tags. When there are multiple tags it checks if the intersection of the
-list of tags for the query and local\-zone\-tag is non-empty.
-.TP 5
-.B local\-zone\-override: \fI<zone> <IP netblock> <type>
-Override the localzone type for queries from addresses matching netblock.
-Use this localzone type, regardless the type configured for the local-zone
+IPv6 address and the host name.
+For example \fB\(dq192.0.2.4 www.example.com\(dq\fP\&.
+TTL can be inserted like this: \fB\(dq2001:DB8::4 7200 www.example.com\(dq\fP
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local\-zone\-tag: \fI<zone> <\(dqlist of tags\(dq>\fP
+Assign tags to local zones.
+Tagged localzones will only be applied when the used
+\fI\%access\-control\fP element has a matching
+tag.
+Tags must be defined in \fI\%define\-tag\fP\&.
+Enclose list of tags in quotes (\fB\(dq\(dq\fP) and put spaces between tags.
+When there are multiple tags it checks if the intersection of the list of
+tags for the query and \fI\%local\-zone\-tag\fP
+is non\-empty.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local\-zone\-override: \fI<zone> <IP netblock> <type>\fP
+Override the local zone type for queries from addresses matching netblock.
+Use this localzone type, regardless the type configured for the local zone
(both tagged and untagged) and regardless the type configured using
-access\-control\-tag\-action.
-.TP 5
-.B response\-ip: \fI<IP-netblock> <action>
-This requires use of the "respip" module.
-.IP
-If the IP address in an AAAA or A RR in the answer section of a
-response matches the specified IP netblock, the specified action will
-apply.
-\fI<action>\fR has generally the same semantics as that for
-\fIaccess-control-tag-action\fR, but there are some exceptions.
-.IP
-Actions for \fIresponse-ip\fR are different from those for
-\fIlocal-zone\fR in that in case of the former there is no point of
-such conditions as "the query matches it but there is no local data".
-Because of this difference, the semantics of \fIresponse-ip\fR actions
-are modified or simplified as follows: The \fIstatic, refuse,
-transparent, typetransparent,\fR and \fInodefault\fR actions are
-invalid for \fIresponse-ip\fR.
-Using any of these will cause the configuration to be rejected as
-faulty. The \fIdeny\fR action is non-conditional, i.e. it always
-results in dropping the corresponding query.
-The resolution result before applying the deny action is still cached
-and can be used for other queries.
-.TP 5
-.B response-ip-data: \fI<IP-netblock> <"resource record string">
-This requires use of the "respip" module.
-.IP
-This specifies the action data for \fIresponse-ip\fR with action being
-to redirect as specified by "\fIresource record string\fR". "Resource
-record string" is similar to that of \fIaccess-control-tag-action\fR,
+\fI\%access\-control\-tag\-action\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B response\-ip: \fI<IP\-netblock> <action>\fP
+This requires use of the \fBrespip\fP module.
+.sp
+If the IP address in an AAAA or A RR in the answer section of a response
+matches the specified IP netblock, the specified action will apply.
+\fI<action>\fP has generally the same semantics as that for
+\fI\%access\-control\-tag\-action\fP,
+but there are some exceptions.
+.sp
+Actions for \fI\%response\-ip\fP are different
+from those for \fI\%local\-zone\fP in that in case
+of the former there is no point of such conditions as \(dqthe query matches it
+but there is no local data\(dq.
+Because of this difference, the semantics of
+\fI\%response\-ip\fP actions are modified or
+simplified as follows: The \fIstatic\fP, \fIrefuse\fP, \fItransparent\fP,
+\fItypetransparent\fP, and \fInodefault\fP actions are invalid for \fIresponse\-ip\fP\&.
+Using any of these will cause the configuration to be rejected as faulty.
+The \fIdeny\fP action is non\-conditional, i.e. it always results in dropping
+the corresponding query.
+The resolution result before applying the \fIdeny\fP action is still cached and
+can be used for other queries.
+.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
+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,
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 IP netblocks). If it is CNAME there must not be
-more than one \fIresponse-ip-data\fR for the same IP-netblock.
+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
+IP netblocks).
+If it is CNAME there must not be more than one
+\fI\%response\-ip\-data\fP for the same
+\fI<IP\-netblock>\fP\&.
Also, CNAME and other types of records must not coexist for the same
-IP-netblock, following the normal rules for CNAME records.
+\fI<IP\-netblock>\fP, following the normal rules for CNAME records.
The textual domain name for the CNAME does not have to be explicitly
-terminated with a dot ("."); the root name is assumed to be the origin
+terminated with a dot (\fB\(dq.\(dq\fP); the root name is assumed to be the origin
for the name.
-.TP 5
-.B response-ip-tag: \fI<IP-netblock> <"list of tags">
-This requires use of the "respip" module.
-.IP
-Assign tags to response IP-netblocks. If the IP address in an AAAA or
-A RR in the answer section of a response matches the specified
-IP-netblock, the specified tags are assigned to the IP address.
-Then, if an \fIaccess-control-tag\fR is defined for the client and it
-includes one of the tags for the response IP, the corresponding
-\fIaccess-control-tag-action\fR will apply.
-Tag matching rule is the same as that for \fIaccess-control-tag\fR and
-\fIlocal-zones\fR.
-Unlike \fIlocal-zone-tag\fR, \fIresponse-ip-tag\fR can be defined for
-an IP-netblock even if no \fIresponse-ip\fR is defined for that
-netblock.
-If multiple \fIresponse-ip-tag\fR options are specified for the same
-IP-netblock in different statements, all but the first will be
-ignored.
-However, this will not be flagged as a configuration error, but the
-result is probably not what was intended.
-.IP
+.UNINDENT
+.INDENT 0.0
+.TP
+.B response\-ip\-tag: \fI<IP\-netblock> <\(dqlist of tags\(dq>\fP
+This requires use of the \fBrespip\fP module.
+.sp
+Assign tags to response \fI<IP\-netblock>\fP\&.
+If the IP address in an AAAA or A RR in the answer section of a response
+matches the specified \fI<IP\-netblock>\fP, the specified tags are assigned to
+the IP address.
+Then, if an \fI\%access\-control\-tag\fP is
+defined for the client and it includes one of the tags for the response IP,
+the corresponding
+\fI\%access\-control\-tag\-action\fP
+will apply.
+Tag matching rule is the same as that for
+\fI\%access\-control\-tag\fP and
+\fI\%local\-zone\fP\&.
+Unlike \fI\%local\-zone\-tag\fP,
+\fI\%response\-ip\-tag\fP can be defined for an
+\fI<IP\-netblock>\fP even if no \fI\%response\-ip\fP is
+defined for that netblock.
+If multiple \fI\%response\-ip\-tag\fP options
+are specified for the same \fI<IP\-netblock>\fP in different statements, all but
+the first will be ignored.
+However, this will not be flagged as a configuration error, but the result
+is probably not what was intended.
+.sp
Actions specified in an
-\fIaccess-control-tag-action\fR that has a matching tag with
-\fIresponse-ip-tag\fR can be those that are "invalid" for
-\fIresponse-ip\fR listed above, since \fIaccess-control-tag-action\fRs
+\fI\%access\-control\-tag\-action\fP
+that has a matching tag with
+\fI\%response\-ip\-tag\fP can be those that are
+\(dqinvalid\(dq for \fI\%response\-ip\fP listed above,
+since
+\fI\%access\-control\-tag\-action\fP
can be shared with local zones.
-For these actions, if they behave differently depending on whether
-local data exists or not in case of local zones, the behavior for
-\fIresponse-ip-data\fR will generally result in NOERROR/NODATA instead
-of NXDOMAIN, since the \fIresponse-ip\fR data are inherently type
-specific, and non-existence of data does not indicate anything about
-the existence or non-existence of the qname itself.
-For example, if the matching tag action is \fIstatic\fR but there is
-no data for the corresponding \fIresponse-ip\fR configuration, then
-the result will be NOERROR/NODATA.
+For these actions, if they behave differently depending on whether local
+data exists or not in case of local zones, the behavior for
+\fI\%response\-ip\-data\fP will generally
+result in NOERROR/NODATA instead of NXDOMAIN, since the
+\fI\%response\-ip\fP data are inherently type
+specific, and non\-existence of data does not indicate anything about the
+existence or non\-existence of the qname itself.
+For example, if the matching tag action is static but there is no data for
+the corresponding \fI\%response\-ip\fP
+configuration, then the result will be NOERROR/NODATA.
The only case where NXDOMAIN is returned is when an
-\fIalways_nxdomain\fR action applies.
-.TP 5
-.B ratelimit: \fI<number or 0>
+\fI\%always_nxdomain\fP
+action applies.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ratelimit: \fI<number or 0>\fP
Enable ratelimiting of queries sent to nameserver for performing recursion.
-If 0, the default, it is disabled. This option is experimental at this time.
-The ratelimit is in queries per second that are allowed. More queries are
-turned away with an error (servfail). This stops recursive floods, eg. random
-query names, but not spoofed reflection floods. Cached responses are not
-ratelimited by this setting. The zone of the query is determined by examining
-the nameservers for it, the zone name is used to keep track of the rate.
+0 disables the feature.
+This option is experimental at this time.
+.sp
+The ratelimit is in queries per second that are allowed.
+More queries are turned away with an error (SERVFAIL).
+Cached responses are not ratelimited by this setting.
+.sp
+This stops recursive floods, eg. random query names, but not spoofed
+reflection floods.
+The zone of the query is determined by examining the nameservers for it,
+the zone name is used to keep track of the rate.
For example, 1000 may be a suitable value to stop the server from being
-overloaded with random names, and keeps Unbound from sending traffic to the
-nameservers for those zones. Configured forwarders are excluded from
-ratelimiting.
-.TP 5
-.B ratelimit\-size: \fI<memory size>
+overloaded with random names, and keeps unbound from sending traffic to the
+nameservers for those zones.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+Configured forwarders are excluded from ratelimiting.
+.UNINDENT
+.UNINDENT
+.sp
+Default: 0
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ratelimit\-size: \fI<memory size>\fP
Give the size of the data structure in which the current ongoing rates are
-kept track in. Default 4m. In bytes or use m(mega), k(kilo), g(giga).
-The ratelimit structure is small, so this data structure likely does
-not need to be large.
-.TP 5
-.B ratelimit\-slabs: \fI<number>
+kept track in.
+In bytes or use m(mega), k(kilo), g(giga).
+The ratelimit structure is small, so this data structure likely does not
+need to be large.
+.sp
+Default: 4m
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ratelimit\-slabs: \fI<number>\fP
Number of slabs in the ratelimit tracking data structure.
Slabs reduce lock contention by threads.
Must be set to a power of 2.
Setting (close) to the number of cpus is a fairly good setting.
-If left unconfigured, it will be configured automatically to be a power of 2
-close to the number of configured threads in multi-threaded environments.
-.TP 5
-.B ratelimit\-factor: \fI<number>
+If left unconfigured, it will be configured automatically to be a power of
+2 close to the number of configured threads in multi\-threaded environments.
+.sp
+Default: (unconfigured)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ratelimit\-factor: \fI<number>\fP
Set the amount of queries to rate limit when the limit is exceeded.
If set to 0, all queries are dropped for domains where the limit is
-exceeded. If set to another value, 1 in that number is allowed through
-to complete. Default is 10, allowing 1/10 traffic to flow normally.
-This can make ordinary queries complete (if repeatedly queried for),
-and enter the cache, whilst also mitigating the traffic flow by the
-factor given.
-.TP 5
-.B ratelimit\-backoff: \fI<yes or no>
-If enabled, the ratelimit is treated as a hard failure instead of the default
-maximum allowed constant rate. When the limit is reached, traffic is
-ratelimited and demand continues to be kept track of for a 2 second rate
-window. No traffic is allowed, except for ratelimit\-factor, until demand
-decreases below the configured ratelimit for a 2 second rate window. Useful to
-set ratelimit to a suspicious rate to aggressively limit unusually high
-traffic. Default is off.
-.TP 5
-.B ratelimit\-for\-domain: \fI<domain> <number qps or 0>
-Override the global ratelimit for an exact match domain name with the listed
-number. You can give this for any number of names. For example, for
-a top\-level\-domain you may want to have a higher limit than other names.
+exceeded.
+If set to another value, 1 in that number is allowed through to complete.
+Default is 10, allowing 1/10 traffic to flow normally.
+This can make ordinary queries complete (if repeatedly queried for), and
+enter the cache, whilst also mitigating the traffic flow by the factor
+given.
+.sp
+Default: 10
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ratelimit\-backoff: \fI<yes or no>\fP
+If enabled, the ratelimit is treated as a hard failure instead of the
+default maximum allowed constant rate.
+When the limit is reached, traffic is ratelimited and demand continues to
+be kept track of for a 2 second rate window.
+No traffic is allowed, except for
+\fI\%ratelimit\-factor\fP, until demand
+decreases below the configured ratelimit for a 2 second rate window.
+Useful to set \fI\%ratelimit\fP to a suspicious
+rate to aggressively limit unusually high traffic.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ratelimit\-for\-domain: \fI<domain> <number qps or 0>\fP
+Override the global \fI\%ratelimit\fP for an exact
+match domain name with the listed number.
+You can give this for any number of names.
+For example, for a top\-level\-domain you may want to have a higher limit
+than other names.
A value of 0 will disable ratelimiting for that domain.
-.TP 5
-.B ratelimit\-below\-domain: \fI<domain> <number qps or 0>
-Override the global ratelimit for a domain name that ends in this name.
-You can give this multiple times, it then describes different settings
-in different parts of the namespace. The closest matching suffix is used
-to determine the qps limit. The rate for the exact matching domain name
-is not changed, use ratelimit\-for\-domain to set that, you might want
-to use different settings for a top\-level\-domain and subdomains.
-A value of 0 will disable ratelimiting for domain names that end in this name.
-.TP 5
-.B ip\-ratelimit: \fI<number or 0>
-Enable global ratelimiting of queries accepted per IP address.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ratelimit\-below\-domain: \fI<domain> <number qps or 0>\fP
+Override the global \fI\%ratelimit\fP for a domain
+name that ends in this name.
+You can give this multiple times, it then describes different settings in
+different parts of the namespace.
+The closest matching suffix is used to determine the qps limit.
+The rate for the exact matching domain name is not changed, use
+\fI\%ratelimit\-for\-domain\fP to set
+that, you might want to use different settings for a top\-level\-domain and
+subdomains.
+A value of 0 will disable ratelimiting for domain names that end in this
+name.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ip\-ratelimit: \fI<number or 0>\fP
+Enable global ratelimiting of queries accepted per ip address.
This option is experimental at this time.
-The ratelimit is in queries per second that are allowed. More queries are
-completely dropped and will not receive a reply, SERVFAIL or otherwise.
-IP ratelimiting happens before looking in the cache. This may be useful for
-mitigating amplification attacks.
+The ratelimit is in queries per second that are allowed.
+More queries are completely dropped and will not receive a reply, SERVFAIL
+or otherwise.
+IP ratelimiting happens before looking in the cache.
+This may be useful for mitigating amplification attacks.
Clients with a valid DNS Cookie will bypass the ratelimit.
-If a ratelimit for such clients is still needed, \fBip\-ratelimit\-cookie\fR
+If a ratelimit for such clients is still needed,
+\fI\%ip\-ratelimit\-cookie\fP
can be used instead.
-Default is 0 (disabled).
-.TP 5
-.B ip\-ratelimit\-cookie: \fI<number or 0>
-Enable global ratelimiting of queries accepted per IP address with a valid DNS
-Cookie.
+.sp
+Default: 0 (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ip\-ratelimit\-cookie: \fI<number or 0>\fP
+Enable global ratelimiting of queries accepted per IP address with a valid
+DNS Cookie.
This option is experimental at this time.
The ratelimit is in queries per second that are allowed.
-More queries are completely dropped and will not receive a reply, SERVFAIL or
-otherwise.
+More queries are completely dropped and will not receive a reply, SERVFAIL
+or otherwise.
IP ratelimiting happens before looking in the cache.
-This option could be useful in combination with \fIallow_cookie\fR in an
+This option could be useful in combination with
+\fI\%allow_cookie\fP, in an
attempt to mitigate other amplification attacks than UDP reflections (e.g.,
-attacks targeting Unbound itself) which are already handled with DNS Cookies.
-If used, the value is suggested to be higher than \fBip\-ratelimit\fR e.g.,
-tenfold.
-Default is 0 (disabled).
-.TP 5
-.B ip\-ratelimit\-size: \fI<memory size>
+attacks targeting Unbound itself) which are already handled with DNS
+Cookies.
+If used, the value is suggested to be higher than
+\fI\%ip\-ratelimit\fP e.g., tenfold.
+.sp
+Default: 0 (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ip\-ratelimit\-size: \fI<memory size>\fP
Give the size of the data structure in which the current ongoing rates are
-kept track in. Default 4m. In bytes or use m(mega), k(kilo), g(giga).
-The ip ratelimit structure is small, so this data structure likely does
-not need to be large.
-.TP 5
-.B ip\-ratelimit\-slabs: \fI<number>
+kept track in.
+In bytes or use m(mega), k(kilo), g(giga).
+The IP ratelimit structure is small, so this data structure likely does not
+need to be large.
+.sp
+Default: 4m
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ip\-ratelimit\-slabs: \fI<number>\fP
Number of slabs in the ip ratelimit tracking data structure.
Slabs reduce lock contention by threads.
Must be set to a power of 2.
Setting (close) to the number of cpus is a fairly good setting.
-If left unconfigured, it will be configured automatically to be a power of 2
-close to the number of configured threads in multi-threaded environments.
-.TP 5
-.B ip\-ratelimit\-factor: \fI<number>
+If left unconfigured, it will be configured automatically to be a power of
+2 close to the number of configured threads in multi\-threaded environments.
+.sp
+Default: (unconfigured)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ip\-ratelimit\-factor: \fI<number>\fP
Set the amount of queries to rate limit when the limit is exceeded.
If set to 0, all queries are dropped for addresses where the limit is
-exceeded. If set to another value, 1 in that number is allowed through
-to complete. Default is 10, allowing 1/10 traffic to flow normally.
-This can make ordinary queries complete (if repeatedly queried for),
-and enter the cache, whilst also mitigating the traffic flow by the
-factor given.
-.TP 5
-.B ip\-ratelimit\-backoff: \fI<yes or no>
-If enabled, the ratelimit is treated as a hard failure instead of the default
-maximum allowed constant rate. When the limit is reached, traffic is
-ratelimited and demand continues to be kept track of for a 2 second rate
-window. No traffic is allowed, except for ip\-ratelimit\-factor, until demand
-decreases below the configured ratelimit for a 2 second rate window. Useful to
-set ip\-ratelimit to a suspicious rate to aggressively limit unusually high
-traffic. Default is off.
-.TP 5
-.B outbound\-msg\-retry: \fI<number>
-The number of retries, per upstream nameserver in a delegation, that Unbound
-will attempt in case a throwaway response is received.
+exceeded.
+If set to another value, 1 in that number is allowed through to complete.
+Default is 10, allowing 1/10 traffic to flow normally.
+This can make ordinary queries complete (if repeatedly queried for), and
+enter the cache, whilst also mitigating the traffic flow by the factor
+given.
+.sp
+Default: 10
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ip\-ratelimit\-backoff: \fI<yes or no>\fP
+If enabled, the rate limit is treated as a hard failure instead of the
+default maximum allowed constant rate.
+When the limit is reached, traffic is ratelimited and demand continues to
+be kept track of for a 2 second rate window.
+No traffic is allowed, except for
+\fI\%ip\-ratelimit\-factor\fP, until demand
+decreases below the configured ratelimit for a 2 second rate window.
+Useful to set \fI\%ip\-ratelimit\fP to a
+suspicious rate to aggressively limit unusually high traffic.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B outbound\-msg\-retry: \fI<number>\fP
+The number of retries, per upstream nameserver in a delegation, that
+Unbound will attempt in case a throwaway response is received.
No response (timeout) contributes to the retry counter.
-If a forward/stub zone is used, this is the number of retries per nameserver in
-the zone.
-Default is 5.
-.TP 5
-.B max\-sent\-count: \fI<number>
-Hard limit on the number of outgoing queries Unbound will make while resolving
-a name, making sure large NS sets do not loop.
+If a forward/stub zone is used, this is the number of retries per
+nameserver in the zone.
+.sp
+Default: 5
+.UNINDENT
+.INDENT 0.0
+.TP
+.B max\-sent\-count: \fI<number>\fP
+Hard limit on the number of outgoing queries Unbound will make while
+resolving a name, making sure large NS sets do not loop.
Results in SERVFAIL when reached.
It resets on query restarts (e.g., CNAME) and referrals.
-Default is 32.
-.TP 5
-.B max\-query\-restarts: \fI<number>
-Hard limit on the number of times Unbound is allowed to restart a query upon
-encountering a CNAME record.
+.sp
+Default: 32
+.UNINDENT
+.INDENT 0.0
+.TP
+.B max\-query\-restarts: \fI<number>\fP
+Hard limit on the number of times Unbound is allowed to restart a query
+upon encountering a CNAME record.
Results in SERVFAIL when reached.
Changing this value needs caution as it can allow long CNAME chains to be
accepted, where Unbound needs to verify (resolve) each link individually.
-Default is 11.
-.TP 5
-.B iter\-scrub\-ns: \fI<number>
+.sp
+Default: 11
+.UNINDENT
+.INDENT 0.0
+.TP
+.B iter\-scrub\-ns: \fI<number>\fP
Limit on the number of NS records allowed in an rrset of type NS, from the
-iterator scrubber. This protects the internals of the resolver from overly
-large NS sets. Default is 20.
-.TP 5
-.B iter\-scrub\-cname: \fI<number>
+iterator scrubber.
+This protects the internals of the resolver from overly large NS sets.
+.sp
+Default: 20
+.UNINDENT
+.INDENT 0.0
+.TP
+.B iter\-scrub\-cname: \fI<number>\fP
Limit on the number of CNAME, DNAME records in an answer, from the iterator
-scrubber. This protects the internals of the resolver from overly long
-indirection chains. Clips off the remainder of the reply packet at that point.
-Default is 11.
-.TP 5
-.B max\-global\-quota: \fI<number>
+scrubber.
+This protects the internals of the resolver from overly long indirection
+chains.
+Clips off the remainder of the reply packet at that point.
+.sp
+Default: 11
+.UNINDENT
+.INDENT 0.0
+.TP
+.B max\-global\-quota: \fI<number>\fP
Limit on the number of upstream queries sent out for an incoming query and
-its subqueries from recursion. It is not reset during the resolution. When
-it is exceeded the query is failed and the lookup process stops.
-Default is 200.
-.TP 5
-.B fast\-server\-permil: \fI<number>
+its subqueries from recursion.
+It is not reset during the resolution.
+When it is exceeded the query is failed and the lookup process stops.
+.sp
+Default: 200
+.UNINDENT
+.INDENT 0.0
+.TP
+.B fast\-server\-permil: \fI<number>\fP
Specify how many times out of 1000 to pick from the set of fastest servers.
-0 turns the feature off. A value of 900 would pick from the fastest
-servers 90 percent of the time, and would perform normal exploration of random
-servers for the remaining time. When prefetch is enabled (or serve\-expired),
-such prefetches are not sped up, because there is no one waiting for it, and it
-presents a good moment to perform server exploration. The
-\fBfast\-server\-num\fR option can be used to specify the size of the fastest
-servers set. The default for fast\-server\-permil is 0.
-.TP 5
-.B fast\-server\-num: \fI<number>
-Set the number of servers that should be used for fast server selection. Only
-use the fastest specified number of servers with the fast\-server\-permil
-option, that turns this on or off. The default is to use the fastest 3 servers.
-.TP 5
-.B answer\-cookie: \fI<yes or no>
+0 turns the feature off.
+A value of 900 would pick from the fastest servers 90 percent of the time,
+and would perform normal exploration of random servers for the remaining
+time.
+When \fI\%prefetch\fP is enabled (or
+\fI\%serve\-expired\fP), such prefetches are not
+sped up, because there is no one waiting for it, and it presents a good
+moment to perform server exploration.
+The \fI\%fast\-server\-num\fP option can be
+used to specify the size of the fastest servers set.
+.sp
+Default: 0
+.UNINDENT
+.INDENT 0.0
+.TP
+.B fast\-server\-num: \fI<number>\fP
+Set the number of servers that should be used for fast server selection.
+Only use the fastest specified number of servers with the
+\fI\%fast\-server\-permil\fP option, that
+turns this on or off.
+.sp
+Default: 3
+.UNINDENT
+.INDENT 0.0
+.TP
+.B answer\-cookie: \fI<yes or no>\fP
If enabled, Unbound will answer to requests containing DNS Cookies as
specified in RFC 7873 and RFC 9018.
-Default is no.
-.TP 5
-.B cookie\-secret: \fI<128 bit hex string>
-Server's secret for DNS Cookie generation.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B cookie\-secret: \fI\(dq<128 bit hex string>\(dq\fP
+Server\(aqs secret for DNS Cookie generation.
Useful to explicitly set for servers in an anycast deployment that need to
-share the secret in order to verify each other's Server Cookies.
-An example hex string would be "000102030405060708090a0b0c0d0e0f".
-Default is a 128 bits random secret generated at startup time.
-This option is ignored if a \fBcookie\-secret\-file\fR is
-present. In that case the secrets from that file are used in DNS Cookie
+share the secret in order to verify each other\(aqs Server Cookies.
+An example hex string would be \(dq000102030405060708090a0b0c0d0e0f\(dq.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This option is ignored if a
+\fI\%cookie\-secret\-file\fP is present.
+In that case the secrets from that file are used in DNS Cookie
calculations.
-.TP 5
-.B cookie\-secret\-file: \fI<filename>
-File from which the secrets are read used in DNS Cookie calculations. When this
-file exists, the secrets in this file are used and the secret specified by the
-\fBcookie-secret\fR option is ignored.
-Enable it by setting a filename, like "/usr/local/etc/unbound_cookiesecrets.txt".
-The content of this file must be manipulated with the \fBadd_cookie_secret\fR,
-\fBdrop_cookie_secret\fR and \fBactivate_cookie_secret\fR commands to the
-\fIunbound\-control\fR(8) tool. Please see that manpage on how to perform a
-safe cookie secret rollover.
-Default is "" (disabled).
-.TP 5
-.B edns\-client\-string: \fI<IP netblock> <string>
-Include an EDNS0 option containing configured ascii string in queries with
-destination address matching the configured IP netblock. This configuration
-option can be used multiple times. The most specific match will be used.
-.TP 5
-.B edns\-client\-string\-opcode: \fI<opcode>
-EDNS0 option code for the \fIedns\-client\-string\fR option, from 0 to 65535.
-A value from the `Reserved for Local/Experimental` range (65001-65534) should
-be used. Default is 65001.
-.TP 5
-.B ede: \fI<yes or no>
-If enabled, Unbound will respond with Extended DNS Error codes (RFC8914).
-These EDEs provide additional information with a response mainly for, but not
-limited to, DNS and DNSSEC errors.
-
-When the \fBval-log-level\fR option is also set to \fB2\fR, responses with
-Extended DNS Errors concerning DNSSEC failures will also contain a descriptive
-text message about the reason for the failure.
-Default is "no".
-.TP 5
-.B ede\-serve\-expired: \fI<yes or no>
-If enabled, Unbound will attach an Extended DNS Error (RFC8914) Code 3 - Stale
-Answer as EDNS0 option to the expired response.
-The \fBede\fR option needs to be enabled as well for this to work.
-Default is "no".
-.TP 5
-.B dns\-error\-reporting: \fI<yes or no>
-If enabled, Unbound will send DNS Error Reports (RFC9567).
-The name servers need to express support by attaching the Report-Channel EDNS0
-option on their replies specifying the reporting agent for the zone.
+.UNINDENT
+.UNINDENT
+.sp
+Default: 128 bits random secret generated at startup time
+.UNINDENT
+.INDENT 0.0
+.TP
+.B cookie\-secret\-file: \fI<filename>\fP
+File from which the secrets are read used in DNS Cookie calculations.
+When this file exists, the secrets in this file are used and the secret
+specified by the
+\fI\%cookie\-secret\fP option is ignored.
+Enable it by setting a filename, like
+\(dq/usr/local/etc/unbound_cookiesecrets.txt\(dq.
+The content of this file must be manipulated with the
+\fI\%add_cookie_secret\fP,
+\fI\%drop_cookie_secret\fP and
+\fI\%activate_cookie_secret\fP
+commands to the \fI\%unbound\-control(8)\fP tool.
+Please see that manpage on how to perform a safe cookie secret rollover.
+.sp
+Default: \(dq\(dq (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B edns\-client\-string: \fI<IP netblock> <string>\fP
+Include an EDNS0 option containing configured ASCII string in queries with
+destination address matching the configured \fI<IP netblock>\fP\&.
+This configuration option can be used multiple times.
+The most specific match will be used.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B edns\-client\-string\-opcode: \fI<opcode>\fP
+EDNS0 option code for the
+\fI\%edns\-client\-string\fP option, from 0
+to 65535.
+A value from the \(aqReserved for Local/Experimental\(aq range (65001\-65534)
+should be used.
+.sp
+Default: 65001
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ede: \fI<yes or no>\fP
+If enabled, Unbound will respond with Extended DNS Error codes
+(\fI\%RFC 8914\fP).
+These EDEs privide additional information with a response mainly for, but
+not limited to, DNS and DNSSEC errors.
+.sp
+When the \fI\%val\-log\-level\fP option is also
+set to \fB2\fP, responses with Extended DNS Errors concerning DNSSEC failures
+will also contain a descriptive text message about the reason for the
+failure.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ede\-serve\-expired: \fI<yes or no>\fP
+If enabled, Unbound will attach an Extended DNS Error (\fI\%RFC 8914\fP) \fICode 3
+\- Stale Answer\fP as EDNS0 option to the expired response.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+\fI\%ede: yes\fP needs to be set as well for this to
+work.
+.UNINDENT
+.UNINDENT
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dns\-error\-reporting: \fI<yes or no>\fP
+If enabled, Unbound will send DNS Error Reports (\fI\%RFC 9567\fP).
+The name servers need to express support by attaching the Report\-Channel
+EDNS0 option on their replies specifying the reporting agent for the zone.
Any errors encountered during resolution that would result in Unbound
-generating an Extended DNS Error (RFC8914) will be reported to the zone's
-reporting agent.
-The \fBede\fR option does not need to be enabled for this to work.
-It is advised that the \fBqname\-minimisation\fR option is also enabled to
-increase privacy on the outgoing reports.
-Default is "no".
-.SS "Remote Control Options"
-In the
-.B remote\-control:
-clause are the declarations for the remote control facility. If this is
-enabled, the \fIunbound\-control\fR(8) utility can be used to send
-commands to the running Unbound server. The server uses these clauses
-to setup TLSv1 security for the connection. The
-\fIunbound\-control\fR(8) utility also reads the \fBremote\-control\fR
-section for options. To setup the correct self\-signed certificates use the
-\fIunbound\-control\-setup\fR(8) utility.
-.TP 5
-.B control\-enable: \fI<yes or no>
-The option is used to enable remote control, default is "no".
+generating an Extended DNS Error (\fI\%RFC 8914\fP) will be reported to the
+zone\(aqs reporting agent.
+.sp
+The \fI\%ede\fP option does not need to be enabled for
+this to work.
+.sp
+It is advised that the
+\fI\%qname\-minimisation\fP option is also
+enabled to increase privacy on the outgoing reports.
+.sp
+Default: no
+.UNINDENT
+.SS Remote Control Options
+.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.
+To setup the correct self\-signed certificates use the
+\fIunbound\-control\-setup(8)\fP utility.
+.INDENT 0.0
+.TP
+.B control\-enable: \fI<yes or no>\fP
+The option is used to enable remote control.
If turned off, the server does not listen for control commands.
-.TP 5
-.B control\-interface: \fI<ip address or interface name or path>
-Give IPv4 or IPv6 addresses or local socket path to listen on for
-control commands.
-If an interface name is used instead of an ip address, the list of ip addresses
-on that interface are used.
-By default localhost (127.0.0.1 and ::1) is listened to.
-Use 0.0.0.0 and ::0 to listen to all interfaces.
-If you change this and permissions have been dropped, you must restart
-the server for the change to take effect.
-.IP
-If you set it to an absolute path, a unix domain socket is used. This socket
-does not use the certificates and keys, so those files need not be present.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B control\-interface: \fI<IP address or interface name or path>\fP
+Give IPv4 or IPv6 addresses or local socket path to listen on for control
+commands.
+If an interface name is used instead of an IP address, the list of IP
+addresses on that interface are used.
+.sp
+By default localhost (\fB127.0.0.1\fP and \fB::1\fP) is listened to.
+Use \fB0.0.0.0\fP and \fB::0\fP to listen to all interfaces.
+If you change this and permissions have been dropped, you must restart the
+server for the change to take effect.
+.sp
+If you set it to an absolute path, a unix domain socket is used.
+This socket does not use the certificates and keys, so those files need not
+be present.
To restrict access, Unbound sets permissions on the file to the user and
-group that is configured, the access bits are set to allow the group members
-to access the control socket file. Put users that need to access the socket
-in the that group. To restrict access further, create a directory to put
-the control socket in and restrict access to that directory.
-.TP 5
-.B control\-port: \fI<port number>
-The port number to listen on for IPv4 or IPv6 control interfaces,
-default is 8953.
+group that is configured, the access bits are set to allow the group
+members to access the control socket file.
+Put users that need to access the socket in the that group.
+To restrict access further, create a directory to put the control socket in
+and restrict access to that directory.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B control\-port: \fI<port number>\fP
+The port number to listen on for IPv4 or IPv6 control interfaces.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
If you change this and permissions have been dropped, you must restart
the server for the change to take effect.
-.TP 5
-.B control\-use\-cert: \fI<yes or no>
-For localhost control-interface you can disable the use of TLS by setting
-this option to "no", default is "yes". For local sockets, TLS is disabled
-and the value of this option is ignored.
-.TP 5
-.B server\-key\-file: \fI<private key file>
-Path to the server private key, by default unbound_server.key.
-This file is generated by the \fIunbound\-control\-setup\fR utility.
-This file is used by the Unbound server, but not by \fIunbound\-control\fR.
-.TP 5
-.B server\-cert\-file: \fI<certificate file.pem>
-Path to the server self signed certificate, by default unbound_server.pem.
-This file is generated by the \fIunbound\-control\-setup\fR utility.
-This file is used by the Unbound server, and also by \fIunbound\-control\fR.
-.TP 5
-.B control\-key\-file: \fI<private key file>
-Path to the control client private key, by default unbound_control.key.
-This file is generated by the \fIunbound\-control\-setup\fR utility.
-This file is used by \fIunbound\-control\fR.
-.TP 5
-.B control\-cert\-file: \fI<certificate file.pem>
-Path to the control client certificate, by default unbound_control.pem.
+.UNINDENT
+.UNINDENT
+.sp
+Default: 8953
+.UNINDENT
+.INDENT 0.0
+.TP
+.B control\-use\-cert: \fI<yes or no>\fP
+For localhost
+\fI\%control\-interface\fP you can
+disable the use of TLS by setting this option to \(dqno\(dq.
+For local sockets, TLS is disabled and the value of this option is ignored.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B server\-key\-file: \fI<private key file>\fP
+Path to the server private key.
+This file is generated by the
+\fI\%unbound\-control\-setup(8)\fP utility.
+This file is used by the Unbound server, but not by
+\fI\%unbound\-control(8)\fP\&.
+.sp
+Default: unbound_server.key
+.UNINDENT
+.INDENT 0.0
+.TP
+.B server\-cert\-file: \fI<certificate file.pem>\fP
+Path to the server self signed certificate.
+This file is generated by the
+\fI\%unbound\-control\-setup(8)\fP utility.
+This file is used by the Unbound server, and also by
+\fI\%unbound\-control(8)\fP\&.
+.sp
+Default: unbound_server.pem
+.UNINDENT
+.INDENT 0.0
+.TP
+.B control\-key\-file: \fI<private key file>\fP
+Path to the control client private key.
+This file is generated by the
+\fI\%unbound\-control\-setup(8)\fP utility.
+This file is used by \fI\%unbound\-control(8)\fP\&.
+.sp
+Default: unbound_control.key
+.UNINDENT
+.INDENT 0.0
+.TP
+.B control\-cert\-file: \fI<certificate file.pem>\fP
+Path to the control client certificate.
This certificate has to be signed with the server certificate.
-This file is generated by the \fIunbound\-control\-setup\fR utility.
-This file is used by \fIunbound\-control\fR.
-.SS "Stub Zone Options"
-.LP
-There may be multiple
-.B stub\-zone:
-clauses. Each with a name: and zero or more hostnames or IP addresses.
-For the stub zone this list of nameservers is used. Class IN is assumed.
-The servers should be authority servers, not recursors; Unbound performs
-the recursive processing itself for stub zones.
-.P
-The stub zone can be used to configure authoritative data to be used
-by the resolver that cannot be accessed using the public internet servers.
-This is useful for company\-local data or private zones. Setup an
-authoritative server on a different host (or different port). Enter a config
-entry for Unbound with
-.B stub\-addr:
-<ip address of host[@port]>.
-The Unbound resolver can then access the data, without referring to the
-public internet for it.
-.P
-This setup allows DNSSEC signed zones to be served by that
-authoritative server, in which case a trusted key entry with the public key
-can be put in config, so that Unbound can validate the data and set the AD
-bit on replies for the private zone (authoritative servers do not set the
-AD bit). This setup makes Unbound capable of answering queries for the
-private zone, and can even set the AD bit ('authentic'), but the AA
-('authoritative') bit is not set on these replies.
-.P
-Consider adding \fBserver:\fR statements for \fBdomain\-insecure:\fR and
-for \fBlocal\-zone:\fI name nodefault\fR for the zone if it is a locally
-served zone. The insecure clause stops DNSSEC from invalidating the
-zone. The local zone nodefault (or \fItransparent\fR) clause makes the
-(reverse\-) zone bypass Unbound's filtering of RFC1918 zones.
-.TP
-.B name: \fI<domain name>
-Name of the stub zone. This is the full domain name of the zone.
-.TP
-.B stub\-host: \fI<domain name>
-Name of stub zone nameserver. Is itself resolved before it is used.
-To use a nondefault port for DNS communication append '@' with the port number.
-If tls is enabled, then you can append a '#' and a name, then it'll check the
-tls authentication certificates with that name. If you combine the '@'
-and '#', the '@' comes first. If only '#' is used the default port is the
-configured tls\-port.
-.TP
-.B stub\-addr: \fI<IP address>
-IP address of stub zone nameserver. Can be IP 4 or IP 6.
-To use a nondefault port for DNS communication append '@' with the port number.
-If tls is enabled, then you can append a '#' and a name, then it'll check the
-tls authentication certificates with that name. If you combine the '@'
-and '#', the '@' comes first. If only '#' is used the default port is the
-configured tls\-port.
-.TP
-.B stub\-prime: \fI<yes or no>
-This option is by default no. If enabled it performs NS set priming,
-which is similar to root hints, where it starts using the list of nameservers
-currently published by the zone. Thus, if the hint list is slightly outdated,
-the resolver picks up a correct list online.
-.TP
-.B stub\-first: \fI<yes or no>
+This file is generated by the
+\fI\%unbound\-control\-setup(8)\fP utility.
+This file is used by \fI\%unbound\-control(8)\fP\&.
+.sp
+Default: unbound_control.pem
+.UNINDENT
+.SS Stub Zone Options
+.sp
+There may be multiple \fBstub\-zone:\fP clauses.
+Each with a \fI\%name\fP and zero or more hostnames or
+IP addresses.
+For the stub zone this list of nameservers is used.
+Class IN is assumed.
+The servers should be authority servers, not recursors; Unbound performs the
+recursive processing itself for stub zones.
+.sp
+The stub zone can be used to configure authoritative data to be used by the
+resolver that cannot be accessed using the public internet servers.
+This is useful for company\-local data or private zones.
+Setup an authoritative server on a different host (or different port).
+Enter a config entry for Unbound with:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+stub\-addr: <ip address of host[@port]>
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The Unbound resolver can then access the data, without referring to the public
+internet for it.
+.sp
+This setup allows DNSSEC signed zones to be served by that authoritative
+server, in which case a trusted key entry with the public key can be put in
+config, so that Unbound can validate the data and set the AD bit on replies for
+the private zone (authoritative servers do not set the AD bit).
+This setup makes Unbound capable of answering queries for the private zone, and
+can even set the AD bit (\(aqauthentic\(aq), but the AA (\(aqauthoritative\(aq) bit is not
+set on these replies.
+.sp
+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\%local\-zone: nodefault\fP (or
+\fI\%transparent\fP) clause makes the
+(reverse\-) zone bypass Unbound\(aqs filtering of \fI\%RFC 1918\fP zones.
+.INDENT 0.0
+.TP
+.B name: \fI<domain name>\fP
+Name of the stub zone.
+This is the full domain name of the zone.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stub\-host: \fI<domain name>\fP
+Name of stub zone nameserver.
+Is itself resolved before it is used.
+.sp
+To use a non\-default port for DNS communication append \fB\(aq@\(aq\fP with the
+port number.
+.sp
+If TLS is enabled, then you can append a \fB\(aq#\(aq\fP and a name, then it\(aqll
+check the TLS authentication certificates with that name.
+.sp
+If you combine the \fB\(aq@\(aq\fP and \fB\(aq#\(aq\fP, the \fB\(aq@\(aq\fP comes first.
+If only \fB\(aq#\(aq\fP is used the default port is the configured
+\fI\%tls\-port\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stub\-addr: \fI<IP address>\fP
+IP address of stub zone nameserver.
+Can be IPv4 or IPv6.
+.sp
+To use a non\-default port for DNS communication append \fB\(aq@\(aq\fP with the
+port number.
+.sp
+If TLS is enabled, then you can append a \fB\(aq#\(aq\fP and a name, then it\(aqll
+check the tls authentication certificates with that name.
+.sp
+If you combine the \fB\(aq@\(aq\fP and \fB\(aq#\(aq\fP, the \fB\(aq@\(aq\fP comes first.
+If only \fB\(aq#\(aq\fP is used the default port is the configured
+\fI\%tls\-port\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stub\-prime: \fI<yes or no>\fP
+If enabled it performs NS set priming, which is similar to root hints,
+where it starts using the list of nameservers currently published by the
+zone.
+Thus, if the hint list is slightly outdated, the resolver picks up a
+correct list online.
+.sp
+Default: no
+.UNINDENT
+.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.
-The data could not be retrieved and would have caused SERVFAIL because
-the servers are unreachable, instead it is tried without this clause.
-The default is no.
-.TP
-.B stub\-tls\-upstream: \fI<yes or no>
+The data could not be retrieved and would have caused SERVFAIL because the
+servers are unreachable, instead it is tried without this clause.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stub\-tls\-upstream: \fI<yes or no>\fP
Enabled or disable whether the queries to this stub use TLS for transport.
-Default is no.
-.TP
-.B stub\-ssl\-upstream: \fI<yes or no>
-Alternate syntax for \fBstub\-tls\-upstream\fR.
-.TP
-.B stub\-tcp\-upstream: \fI<yes or no>
-If it is set to "yes" then upstream queries use TCP only for transport regardless of global flag tcp-upstream.
-Default is no.
-.TP
-.B stub\-no\-cache: \fI<yes or no>
-Default is no. If enabled, data inside the stub is not cached. This is
-useful when you want immediate changes to be visible.
-.SS "Forward Zone Options"
-.LP
-There may be multiple
-.B forward\-zone:
-clauses. Each with a \fBname:\fR and zero or more hostnames or IP
-addresses. For the forward zone this list of nameservers is used to
-forward the queries to. The servers listed as \fBforward\-host:\fR and
-\fBforward\-addr:\fR have to handle further recursion for the query. Thus,
-those servers are not authority servers, but are (just like Unbound is)
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stub\-ssl\-upstream: \fI<yes or no>\fP
+Alternate syntax for
+\fI\%stub\-tls\-upstream\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stub\-tcp\-upstream: \fI<yes or no>\fP
+If it is set to \(dqyes\(dq then upstream queries use TCP only for transport
+regardless of global flag \fI\%tcp\-upstream\fP\&.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B stub\-no\-cache: \fI<yes or no>\fP
+If enabled, data inside the stub is not cached.
+This is useful when you want immediate changes to be visible.
+.sp
+Default: no
+.UNINDENT
+.SS Forward Zone Options
+.sp
+There may be multiple \fBforward\-zone:\fP clauses.
+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
+to.
+The servers listed as \fI\%forward\-host\fP
+and \fI\%forward\-addr\fP have to handle
+further recursion for the query.
+Thus, those servers are not authority servers, but are (just like Unbound is)
recursive servers too; Unbound does not perform recursion itself for the
-forward zone, it lets the remote server do it. Class IN is assumed.
-CNAMEs are chased by Unbound itself, asking the remote server for every
-name in the indirection chain, to protect the local cache from illegal
-indirect referenced items.
-A forward\-zone entry with name "." and a forward\-addr target will
-forward all queries to that other server (unless it can answer from
-the cache).
-.TP
-.B name: \fI<domain name>
-Name of the forward zone. This is the full domain name of the zone.
-.TP
-.B forward\-host: \fI<domain name>
-Name of server to forward to. Is itself resolved before it is used.
-To use a nondefault port for DNS communication append '@' with the port number.
-If tls is enabled, then you can append a '#' and a name, then it'll check the
-tls authentication certificates with that name. If you combine the '@'
-and '#', the '@' comes first. If only '#' is used the default port is the
-configured tls\-port.
-.TP
-.B forward\-addr: \fI<IP address>
-IP address of server to forward to. Can be IP 4 or IP 6.
-To use a nondefault port for DNS communication append '@' with the port number.
-If tls is enabled, then you can append a '#' and a name, then it'll check the
-tls authentication certificates with that name. If you combine the '@'
-and '#', the '@' comes first. If only '#' is used the default port is the
-configured tls\-port.
-.IP
+forward zone, it lets the remote server do it.
+Class IN is assumed.
+CNAMEs are chased by Unbound itself, asking the remote server for every name in
+the indirection chain, to protect the local cache from illegal indirect
+referenced items.
+A \fI\%forward\-zone\fP entry with name
+\fB\(dq.\(dq\fP and a \fI\%forward\-addr\fP target
+will forward all queries to that other server (unless it can answer from the
+cache).
+.INDENT 0.0
+.TP
+.B name: \fI<domain name>\fP
+Name of the forward zone.
+This is the full domain name of the zone.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B forward\-host: \fI<domain name>\fP
+Name of server to forward to.
+Is itself resolved before it is used.
+.sp
+To use a non\-default port for DNS communication append \fB\(aq@\(aq\fP with the
+port number.
+.sp
+If TLS is enabled, then you can append a \fB\(aq#\(aq\fP and a name, then it\(aqll
+check the TLS authentication certificates with that name.
+.sp
+If you combine the \fB\(aq@\(aq\fP and \fB\(aq#\(aq\fP, the \fB\(aq@\(aq\fP comes first.
+If only \fB\(aq#\(aq\fP is used the default port is the configured
+\fI\%tls\-port\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B forward\-addr: \fI<IP address>\fP
+IP address of server to forward to.
+Can be IPv4 or IPv6.
+.sp
+To use a non\-default port for DNS communication append \fB\(aq@\(aq\fP with the
+port number.
+.sp
+If TLS is enabled, then you can append a \fB\(aq#\(aq\fP and a name, then it\(aqll
+check the tls authentication certificates with that name.
+.sp
+If you combine the \fB\(aq@\(aq\fP and \fB\(aq#\(aq\fP, the \fB\(aq@\(aq\fP comes first.
+If only \fB\(aq#\(aq\fP is used the default port is the configured
+\fI\%tls\-port\fP\&.
+.sp
At high verbosity it logs the TLS certificate, with TLS enabled.
-If you leave out the '#' and auth name from the forward\-addr, any
-name is accepted. The cert must also match a CA from the tls\-cert\-bundle.
-.TP
-.B forward\-first: \fI<yes or no>
+If you leave out the \fB\(aq#\(aq\fP and auth name from the
+\fI\%forward\-addr\fP, any name is
+accepted.
+The cert must also match a CA from the
+\fI\%tls\-cert\-bundle\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B forward\-first: \fI<yes or no>\fP
If a forwarded query is met with a SERVFAIL error, and this option is
enabled, Unbound will fall back to normal recursive resolution for this
-query as if no query forwarding had been specified. The default is "no".
-.TP
-.B forward\-tls\-upstream: \fI<yes or no>
-Enabled or disable whether the queries to this forwarder use TLS for transport.
-Default is no.
-If you enable this, also configure a tls\-cert\-bundle or use tls\-win\-cert to
-load CA certs, otherwise the connections cannot be authenticated.
-.TP
-.B forward\-ssl\-upstream: \fI<yes or no>
-Alternate syntax for \fBforward\-tls\-upstream\fR.
-.TP
-.B forward\-tcp\-upstream: \fI<yes or no>
-If it is set to "yes" then upstream queries use TCP only for transport regardless of global flag tcp-upstream.
-Default is no.
-.TP
-.B forward\-no\-cache: \fI<yes or no>
-Default is no. If enabled, data inside the forward is not cached. This is
-useful when you want immediate changes to be visible.
-.SS "Authority Zone Options"
-.LP
-Authority zones are configured with \fBauth\-zone:\fR, and each one must
-have a \fBname:\fR. There can be multiple ones, by listing multiple auth\-zone clauses, each with a different name, pertaining to that part of the namespace.
+query as if no query forwarding had been specified.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B forward\-tls\-upstream: \fI<yes or no>\fP
+Enabled or disable whether the queries to this forwarder use TLS for
+transport.
+If you enable this, also configure a
+\fI\%tls\-cert\-bundle\fP or use
+\fI\%tls\-win\-cert\fP to load CA certs, otherwise
+the connections cannot be authenticated.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B forward\-ssl\-upstream: \fI<yes or no>\fP
+Alternate syntax for
+\fI\%forward\-tls\-upstream\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B forward\-tcp\-upstream: \fI<yes or no>\fP
+If it is set to \(dqyes\(dq then upstream queries use TCP only for transport
+regardless of global flag \fI\%tcp\-upstream\fP\&.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B forward\-no\-cache: \fI<yes or no>\fP
+If enabled, data inside the forward is not cached.
+This is useful when you want immediate changes to be visible.
+.sp
+Default: no
+.UNINDENT
+.SS Authority Zone Options
+.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.
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
+Authority zones can be processed on two distinct, non\-exclusive, configurable
stages.
-.LP
-With \fBfor\-downstream:\fR \fIyes\fR (default), authority zones are processed
-after \fBlocal\-zones\fR and before cache.
+.sp
+With \fI\%for\-downstream: yes\fP (default),
+authority zones are processed after \fBlocal\-zones\fP and before cache.
When used in this manner, Unbound responds like an authority server with no
further processing other than returning an answer from the zone contents.
A notable example, in this case, is CNAME records which are returned verbatim
to downstream clients without further resolution.
-.LP
-With \fBfor\-upstream:\fR \fIyes\fR (default), authority zones are processed
-after the cache lookup, just before going to the network to fetch
-information for recursion.
+.sp
+With \fI\%for\-upstream: yes\fP (default),
+authority zones are processed after the cache lookup, just before going to the
+network to fetch information for recursion.
When used in this manner they provide a local copy of an authority server
that speeds up lookups for that data during resolving.
-.LP
+.sp
If both options are enabled (default), client queries for an authority zone are
answered authoritatively from Unbound, while internal queries that require data
from the authority zone consult the local zone data instead of going to the
network.
-.LP
-An interesting configuration is \fBfor\-downstream:\fR \fIno\fR,
-\fBfor\-upstream:\fR \fIyes\fR that allows for hyperlocal behavior where both
-client and internal queries consult the local zone data while resolving.
+.sp
+An interesting configuration is
+\fI\%for\-downstream: no\fP,
+\fI\%for\-upstream: yes\fP
+that allows for hyperlocal behavior where both client and internal queries
+consult the local zone data while resolving.
In this case, the aforementioned CNAME example will result in a thoroughly
resolved answer.
-.LP
-Authority zones can be read from 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 detect zone changes.
-.LP
+.sp
+Authority zones can be read from 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
+detect zone changes.
+.sp
If the update fetch fails, the timers in the SOA record are used to time
-another fetch attempt. Until the SOA expiry timer is reached. Then the
-zone is expired. When a zone is expired, queries are SERVFAIL, and
-any new serial number is accepted from the primary (even if older), and if
-fallback is enabled, the fallback activates to fetch from the upstream instead
-of the SERVFAIL.
-.TP
-.B name: \fI<zone name>
+another fetch attempt.
+Until the SOA expiry timer is reached.
+Then the zone is expired.
+When a zone is expired, queries are SERVFAIL, and any new serial number is
+accepted from the primary (even if older), and if fallback is enabled, the
+fallback activates to fetch from the upstream instead of the SERVFAIL.
+.INDENT 0.0
+.TP
+.B name: \fI<zone name>\fP
Name of the authority zone.
-.TP
-.B primary: \fI<IP address or host name>
-Where to download a copy of the zone from, with AXFR and IXFR. Multiple
-primaries can be specified. They are all tried if one fails.
-To use a nondefault port for DNS communication append '@' with the port number.
-You can append a '#' and a name, then AXFR over TLS can be used and the tls authentication certificates will be checked with that name. If you combine
-the '@' and '#', the '@' comes first.
-If you point it at another Unbound instance, it would not work because
-that does not support AXFR/IXFR for the zone, but if you used \fBurl:\fR to download
-the zonefile as a text file from a webserver that would work.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B primary: \fI<IP address or host name>\fP
+Where to download a copy of the zone from, with AXFR and IXFR.
+Multiple primaries can be specified.
+They are all tried if one fails.
+.sp
+To use a non\-default port for DNS communication append \fB\(aq@\(aq\fP with the
+port number.
+.sp
+You can append a \fB\(aq#\(aq\fP and a name, then AXFR over TLS can be used and the
+TLS authentication certificates will be checked with that name.
+.sp
+If you combine the \fB\(aq@\(aq\fP and \fB\(aq#\(aq\fP, the \fB\(aq@\(aq\fP comes first.
+If you point it at another Unbound instance, it would not work because that
+does not support AXFR/IXFR for the zone, but if you used
+\fI\%url\fP to download the zonefile as a text file
+from a webserver that would work.
+.sp
If you specify the hostname, you cannot use the domain from the zonefile,
because it may not have that when retrieving that data, instead use a plain
IP address to avoid a circular dependency on retrieving that IP address.
-.TP
-.B master: \fI<IP address or host name>
-Alternate syntax for \fBprimary\fR.
-.TP
-.B url: \fI<url to zonefile>
-Where to download a zonefile for the zone. With http or https. An example
-for the url is "http://www.example.com/example.org.zone". Multiple url
-statements can be given, they are tried in turn. If only urls are given
-the SOA refresh timer is used to wait for making new downloads. If also
-primaries are listed, the primaries are first probed with UDP SOA queries to
-see if the SOA serial number has changed, reducing the number of downloads.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B master: \fI<IP address or host name>\fP
+Alternate syntax for \fI\%primary\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B url: \fI<URL to zone file>\fP
+Where to download a zonefile for the zone.
+With HTTP or HTTPS.
+An example for the url is:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+http://www.example.com/example.org.zone
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Multiple url statements can be given, they are tried in turn.
+.sp
+If only urls are given the SOA refresh timer is used to wait for making new
+downloads.
+If also primaries are listed, the primaries are first probed with UDP SOA
+queries to see if the SOA serial number has changed, reducing the number of
+downloads.
If none of the urls work, the primaries are tried with IXFR and AXFR.
-For https, the \fBtls\-cert\-bundle\fR and the hostname from the url are used
-to authenticate the connection.
+.sp
+For HTTPS, the \fI\%tls\-cert\-bundle\fP and
+the hostname from the url are used to authenticate the connection.
+.sp
If you specify a hostname in the URL, you cannot use the domain from the
zonefile, because it may not have that when retrieving that data, instead
use a plain IP address to avoid a circular dependency on retrieving that IP
-address. Avoid dependencies on name lookups by using a notation like
-"http://192.0.2.1/unbound-primaries/example.com.zone", with an explicit IP address.
-.TP
-.B allow\-notify: \fI<IP address or host name or netblockIP/prefix>
-With allow\-notify you can specify additional sources of notifies.
+address.
+.sp
+Avoid dependencies on name lookups by using a notation like
+\fB\(dqhttp://192.0.2.1/unbound\-primaries/example.com.zone\(dq\fP, with an explicit
+IP address.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B allow\-notify: \fI<IP address or host name or netblockIP/prefix>\fP
+With \fI\%allow\-notify\fP you can specify
+additional sources of notifies.
When notified, the server attempts to first probe and then zone transfer.
-If the notify is from a primary, it first attempts that primary. Otherwise
-other primaries are attempted. If there are no primaries, but only urls, the
-file is downloaded when notified. The primaries from primary: and url:
-statements are allowed notify by default.
-.TP
-.B fallback\-enabled: \fI<yes or no>
-Default no. If enabled, Unbound falls back to querying the internet as
-a resolver for this zone when lookups fail. For example for DNSSEC
-validation failures.
-.TP
-.B for\-downstream: \fI<yes or no>
-Default yes. If enabled, Unbound serves authority responses to
-downstream clients for this zone. This option makes Unbound behave, for
-the queries with names in this zone, like one of the authority servers for
-that zone. Turn it off if you want Unbound to provide recursion for the
-zone but have a local copy of zone data. If for\-downstream is no and
-for\-upstream is yes, then Unbound will DNSSEC validate the contents of the
-zone before serving the zone contents to clients and store validation
-results in the cache.
-.TP
-.B for\-upstream: \fI<yes or no>
-Default yes. If enabled, Unbound fetches data from this data collection
-for answering recursion queries. Instead of sending queries over the internet
-to the authority servers for this zone, it'll fetch the data directly from
-the zone data. Turn it on when you want Unbound to provide recursion for
-downstream clients, and use the zone data as a local copy to speed up lookups.
-.TP
-.B zonemd\-check: \fI<yes or no>
-Enable this option to check ZONEMD records in the zone. Default is disabled.
-The ZONEMD record is a checksum over the zone data. This includes glue in
-the zone and data from the zone file, and excludes comments from the zone file.
+If the notify is from a primary, it first attempts that primary.
+Otherwise other primaries are attempted.
+If there are no primaries, but only urls, the file is downloaded when
+notified.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+The primaries from \fI\%primary\fP and
+\fI\%url\fP statements are allowed notify by
+default.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B fallback\-enabled: \fI<yes or no>\fP
+If enabled, Unbound falls back to querying the internet as a resolver for
+this zone when lookups fail.
+For example for DNSSEC validation failures.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B for\-downstream: \fI<yes or no>\fP
+If enabled, Unbound serves authority responses to downstream clients for
+this zone.
+This option makes Unbound behave, for the queries with names in this zone,
+like one of the authority servers for that zone.
+.sp
+Turn it off if you want Unbound to provide recursion for the zone but have
+a local copy of zone data.
+.sp
+If \fI\%for\-downstream: no\fP and
+\fI\%for\-upstream: yes\fP are set, then
+Unbound will DNSSEC validate the contents of the zone before serving the
+zone contents to clients and store validation results in the cache.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B for\-upstream: \fI<yes or no>\fP
+If enabled, Unbound fetches data from this data collection for answering
+recursion queries.
+Instead of sending queries over the internet to the authority servers for
+this zone, it\(aqll fetch the data directly from the zone data.
+.sp
+Turn it on when you want Unbound to provide recursion for downstream
+clients, and use the zone data as a local copy to speed up lookups.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B zonemd\-check: \fI<yes or no>\fP
+Enable this option to check ZONEMD records in the zone.
+The ZONEMD record is a checksum over the zone data.
+This includes glue in the zone and data from the zone file, and excludes
+comments from the zone file.
When there is a DNSSEC chain of trust, DNSSEC signatures are checked too.
-.TP
-.B zonemd\-reject\-absence: \fI<yes or no>
-Enable this option to reject the absence of the ZONEMD record. Without it,
-when zonemd is not there it is not checked. It is useful to enable for a
-nonDNSSEC signed zone where the operator wants to require the verification
-of a ZONEMD, hence a missing ZONEMD is a failure. The action upon
-failure is controlled by the \fBzonemd\-permissive\-mode\fR option, for
-log only or also block the zone. The default is no.
-.IP
-Without the option absence of a ZONEMD is only a failure when the zone is
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B zonemd\-reject\-absence: \fI<yes or no>\fP
+Enable this option to reject the absence of the ZONEMD record.
+Without it, when ZONEMD is not there it is not checked.
+.sp
+It is useful to enable for a non\-DNSSEC signed zone where the operator
+wants to require the verification of a ZONEMD, hence a missing ZONEMD is a
+failure.
+.sp
+The action upon failure is controlled by the
+\fI\%zonemd\-permissive\-mode\fP option,
+for log only or also block the zone.
+.sp
+Without the option, absence of a ZONEMD is only a failure when the zone is
DNSSEC signed, and we have a trust anchor, and the DNSSEC verification of
-the absence of the ZONEMD fails. With the option enabled, the absence of
-a ZONEMD is always a failure, also for nonDNSSEC signed zones.
-.TP
-.B zonefile: \fI<filename>
-The filename where the zone is stored. If not given then no zonefile is used.
+the absence of the ZONEMD fails.
+With the option enabled, the absence of a ZONEMD is always a failure, also
+for nonDNSSEC signed zones.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B zonefile: \fI<filename>\fP
+The filename where the zone is stored.
+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).
-.SS "View Options"
-.LP
-There may be multiple
-.B view:
-clauses. Each with a \fBname:\fR and zero or more \fBlocal\-zone\fR and
-\fBlocal\-data\fR elements. Views can also contain view\-first,
-response\-ip, response\-ip\-data and local\-data\-ptr elements.
-View can be mapped to requests by specifying the
-view name in an \fBaccess\-control\-view\fR element. 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.
-.TP
-.B name: \fI<view name>
-Name of the view. Must be unique. This name is used in access\-control\-view
-elements.
-.TP
-.B local\-zone: \fI<zone> <type>
-View specific local\-zone elements. Has the same types and behaviour as the
-global local\-zone elements. When there is at least one local\-zone specified
-and view\-first is no, the default local-zones will be added to this view.
-Defaults can be disabled using the nodefault type. When view\-first is yes or
-when a view does not have a local\-zone, the global local\-zone will be used
-including it's default zones.
-.TP
-.B local\-data: \fI"<resource record string>"
-View specific local\-data elements. Has the same behaviour as the global
-local\-data elements.
-.TP
-.B local\-data\-ptr: \fI"IPaddr name"
-View specific local\-data\-ptr elements. Has the same behaviour as the global
-local\-data\-ptr elements.
-.TP
-.B view\-first: \fI<yes or no>
-If enabled, it attempts to use the global local\-zone and local\-data if there
-is no match in the view specific options.
-The default is no.
-.SS "Python Module Options"
-.LP
-The
-.B python:
-clause gives the settings for the \fIpython\fR(1) script module. This module
-acts like the iterator and validator modules do, on queries and answers.
-To enable the script module it has to be compiled into the daemon,
-and the word "python" has to be put in the \fBmodule\-config:\fR option
-(usually first, or between the validator and iterator). Multiple instances of
-the python module are supported by adding the word "python" more than once.
-.LP
-If the \fBchroot:\fR option is enabled, you should make sure Python's
-library directory structure is bind mounted in the new root environment, see
-\fImount\fR(8). Also the \fBpython\-script:\fR path should be specified as an
-absolute path relative to the new root, or as a relative path to the working
+.UNINDENT
+.SS View Options
+.sp
+There may be multiple \fBview:\fP clauses.
+Each with a \fI\%name\fP and zero or more
+\fI\%local\-zone\fP and
+\fI\%local\-data\fP attributes.
+Views can also contain \fI\%view\-first\fP,
+\fI\%response\-ip\fP,
+\fI\%response\-ip\-data\fP and
+\fI\%local\-data\-ptr\fP attributes.
+View can be mapped to requests by specifying the view name in an
+\fI\%access\-control\-view\fP attribute.
+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.
+.INDENT 0.0
+.TP
+.B name: \fI<view name>\fP
+Name of the view.
+Must be unique.
+This name is used in the
+\fI\%access\-control\-view\fP attribute.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local\-zone: \fI<zone> <type>\fP
+View specific local zone elements.
+Has the same types and behaviour as the global
+\fI\%local\-zone\fP elements.
+When there is at least one \fIlocal\-zone:\fP specified and \fI\%view\-first:
+no\fP is set, the default local\-zones will be
+added to this view.
+Defaults can be disabled using the nodefault type.
+When \fI\%view\-first: yes\fP is set or when a
+view does not have a \fI\%local\-zone\fP, the
+global \fI\%local\-zone\fP will be used including
+it\(aqs default zones.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local\-data: \fI\(dq<resource record string>\(dq\fP
+View specific local data elements.
+Has the same behaviour as the global
+\fI\%local\-data\fP elements.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B local\-data\-ptr: \fI\(dqIPaddr name\(dq\fP
+View specific local\-data\-ptr elements.
+Has the same behaviour as the global
+\fI\%local\-data\-ptr\fP elements.
+.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
+\fI\%local\-data\fP if there is no match in the
+view specific options.
+.sp
+Default: no
+.UNINDENT
+.SS Python Module Options
+.sp
+The \fBpython:\fP clause 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
+\fBpython\fP has to be put in the
+\fI\%module\-config\fP option (usually first, or
+between the validator and iterator).
+Multiple instances of the python module are supported by adding the word
+\fBpython\fP more than once.
+.sp
+If the \fI\%chroot\fP option is enabled, you should make
+sure Python\(aqs library directory structure is bind mounted in the new root
+environment, see \fImount(8)\fP\&.
+Also the \fI\%python\-script\fP path should
+be specified as an absolute path relative to the new root, or as a relative
+path to the working directory.
+.INDENT 0.0
+.TP
+.B python\-script: \fI<python file>\fP
+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
+.sp
+The \fBdynlib:\fP clause 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.
+Multiple instances of dynamic libraries are supported by adding the word
+\fBdynlib\fP more than once.
+.sp
+The \fI\%dynlib\-file\fP path should be
+specified as an absolute path relative to the new path set by
+\fI\%chroot\fP, or as a relative path to the working
directory.
-.TP
-.B python\-script: \fI<python file>\fR
-The script file to load. Repeat this option for every python module instance
-added to the \fBmodule\-config:\fR option.
-.SS "Dynamic Library Module Options"
-.LP
-The
-.B dynlib:
-clause gives the settings for the \fIdynlib\fR 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
-\fBmodule\-config:\fR option. Multiple instances of dynamic libraries are
-supported by adding the word "dynlib" more than once.
-.LP
-The \fBdynlib\-file:\fR path should be specified as an absolute path relative
-to the new path set by \fBchroot:\fR option, or as a relative path to the
-working directory.
-.TP
-.B dynlib\-file: \fI<dynlib file>\fR
-The dynamic library file to load. Repeat this option for every dynlib module
-instance added to the \fBmodule\-config:\fR option.
-.SS "DNS64 Module Options"
-.LP
-The dns64 module must be configured in the \fBmodule\-config:\fR directive
-e.g., "dns64 validator iterator" and be compiled into the daemon to be
-enabled. These settings go in the \fBserver:\fR section.
-.TP
-.B dns64\-prefix: \fI<IPv6 prefix>\fR
+.INDENT 0.0
+.TP
+.B dynlib\-file: \fI<dynlib file>\fP
+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
+.sp
+The \fBdns64\fP module must be configured in the
+\fI\%module\-config\fP directive, e.g.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+module\-config: \(dqdns64 validator iterator\(dq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.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
+.INDENT 0.0
+.TP
+.B dns64\-prefix: \fI<IPv6 prefix>\fP
This sets the DNS64 prefix to use to synthesize AAAA records with.
-It must be /96 or shorter. The default prefix is 64:ff9b::/96.
-.TP
-.B dns64\-synthall: \fI<yes or no>\fR
-Debug option, default no. If enabled, synthesize all AAAA records
-despite the presence of actual AAAA records.
-.TP
-.B dns64\-ignore\-aaaa: \fI<name>\fR
-List domain for which the AAAA records are ignored and the A record is
-used by dns64 processing instead. Can be entered multiple times, list a
-new domain for which it applies, one per line. Applies also to names
-underneath the name given.
-.SS "NAT64 Operation"
-.LP
-NAT64 operation allows using a NAT64 prefix for outbound requests to IPv4-only
-servers. It is controlled by two options in the \fBserver:\fR section:
-.TP
-.B do\-nat64: \fI<yes or no>\fR
-Use NAT64 to reach IPv4-only servers.
-Consider also enabling \fBprefer\-ip6\fR to prefer native IPv6 connections to
-nameservers.
-Default no.
-.TP
-.B nat64\-prefix: \fI<IPv6 prefix>\fR
-Use a specific NAT64 prefix to reach IPv4-only servers. Defaults to using
-the prefix configured in \fBdns64\-prefix\fR, which in turn defaults to
-64:ff9b::/96. The prefix length must be one of /32, /40, /48, /56, /64 or /96.
-.SS "DNSCrypt Options"
-.LP
-The
-.B dnscrypt:
-clause gives the settings of the dnscrypt channel. While those options are
-available, they are only meaningful if Unbound was compiled with
-\fB\-\-enable\-dnscrypt\fR.
+It must be /96 or shorter.
+.sp
+Default: 64:ff9b::/96
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dns64\-synthall: \fI<yes or no>\fP
+.sp
+\fBWARNING:\fP
+.INDENT 7.0
+.INDENT 3.5
+Debugging feature!
+.UNINDENT
+.UNINDENT
+.sp
+If enabled, synthesize all AAAA records despite the presence of actual AAAA
+records.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dns64\-ignore\-aaaa: \fI<domain name>\fP
+List domain for which the AAAA records are ignored and the A record is used
+by DNS64 processing instead.
+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
+.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
+Use NAT64 to reach IPv4\-only servers.
+Consider also enabling \fI\%prefer\-ip6\fP
+to prefer native IPv6 connections to nameservers.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B nat64\-prefix: \fI<IPv6 prefix>\fP
+Use a specific NAT64 prefix to reach IPv4\-only servers.
+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
+.sp
+The \fBdnscrypt:\fP clause 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.
-You can use dnscrypt-wrapper to generate those: https://github.com/cofyc/\
-dnscrypt-wrapper/blob/master/README.md#usage
-.TP
-.B dnscrypt\-enable: \fI<yes or no>\fR
-Whether or not the \fBdnscrypt\fR config should be enabled. You may define
-configuration but not activate it.
-The default is no.
-.TP
-.B dnscrypt\-port: \fI<port number>
-On which port should \fBdnscrypt\fR should be activated. Note that you should
-have a matching \fBinterface\fR option defined in the \fBserver\fR section for
-this port.
-.TP
-.B dnscrypt\-provider: \fI<provider name>\fR
-The provider name to use to distribute certificates. This is of the form:
-\fB2.dnscrypt-cert.example.com.\fR. The name \fIMUST\fR end with a dot.
-.TP
-.B dnscrypt\-secret\-key: \fI<path to secret key file>\fR
-Path to the time limited secret key file. This option may be specified multiple
-times.
-.TP
-.B dnscrypt\-provider\-cert: \fI<path to cert file>\fR
-Path to the certificate related to the \fBdnscrypt\-secret\-key\fRs.
+You can use dnscrypt\-wrapper to generate those:
+\fI\%https://github.com/cofyc/dnscrypt\-wrapper/blob/master/README.md#usage\fP
+.INDENT 0.0
+.TP
+.B dnscrypt\-enable: \fI<yes or no>\fP
+Whether or not the dnscrypt config should be enabled.
+You may define configuration but not activate it.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnscrypt\-port: \fI<port number>\fP
+On which port should dnscrypt should be activated.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+There should be a matching interface option defined in the
+\fI\%server:\fP section for this port.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnscrypt\-provider: \fI<provider name>\fP
+The provider name to use to distribute certificates.
+This is of the form:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+2.dnscrypt\-cert.example.com.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBIMPORTANT:\fP
+.INDENT 7.0
+.INDENT 3.5
+The name \fIMUST\fP end with a dot.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnscrypt\-secret\-key: \fI<path to secret key file>\fP
+Path to the time limited secret key file.
This option may be specified multiple times.
+.UNINDENT
+.INDENT 0.0
.TP
-.B dnscrypt\-provider\-cert\-rotated: \fI<path to cert file>\fR
-Path to a certificate that we should be able to serve existing connection from
-but do not want to advertise over \fBdnscrypt\-provider\fR's TXT record certs
-distribution.
-A typical use case is when rotating certificates, existing clients may still use
-the client magic from the old cert in their queries until they fetch and update
-the new cert. Likewise, it would allow one to prime the new cert/key without
-distributing the new cert yet, this can be useful when using a network of
-servers using anycast and on which the configuration may not get updated at the
-exact same time. By priming the cert, the servers can handle both old and new
-certs traffic while distributing only one.
+.B dnscrypt\-provider\-cert: \fI<path to cert file>\fP
+Path to the certificate related to the
+\fI\%dnscrypt\-secret\-key\fP\&.
This option may be specified multiple times.
-.TP
-.B dnscrypt\-shared\-secret\-cache\-size: \fI<memory size>
-Give the size of the data structure in which the shared secret keys are kept
-in. Default 4m. In bytes or use m(mega), k(kilo), g(giga).
-The shared secret cache is used when a same client is making multiple queries
-using the same public key. It saves a substantial amount of CPU.
-.TP
-.B dnscrypt\-shared\-secret\-cache\-slabs: \fI<number>
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnscrypt\-provider\-cert\-rotated: \fI<path to cert file>\fP
+Path to a certificate that we should be able to serve existing connection
+from but do not want to advertise over
+\fI\%dnscrypt\-provider\fP \(aqs TXT
+record certs distribution.
+.sp
+A typical use case is when rotating certificates, existing clients may
+still use the client magic from the old cert in their queries until they
+fetch and update the new cert.
+Likewise, it would allow one to prime the new cert/key without distributing
+the new cert yet, this can be useful when using a network of servers using
+anycast and on which the configuration may not get updated at the exact
+same time.
+.sp
+By priming the cert, the servers can handle both old and new certs traffic
+while distributing only one.
+.sp
+This option may be specified multiple times.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnscrypt\-shared\-secret\-cache\-size: \fI<memory size>\fP
+Give the size of the data structure in which the shared secret keys are
+kept in.
+In bytes or use m(mega), k(kilo), g(giga).
+The shared secret cache is used when a same client is making multiple
+queries using the same public key.
+It saves a substantial amount of CPU.
+.sp
+Default: 4m
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnscrypt\-shared\-secret\-cache\-slabs: \fI<number>\fP
Number of slabs in the dnscrypt shared secrets cache.
Slabs reduce lock contention by threads.
Must be set to a power of 2.
Setting (close) to the number of cpus is a fairly good setting.
-If left unconfigured, it will be configured automatically to be a power of 2
-close to the number of configured threads in multi-threaded environments.
-.TP
-.B dnscrypt\-nonce\-cache\-size: \fI<memory size>
+If left unconfigured, it will be configured automatically to be a power of
+2 close to the number of configured threads in multi\-threaded environments.
+.sp
+Default: (unconfigured)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnscrypt\-nonce\-cache\-size: \fI<memory size>\fP
Give the size of the data structure in which the client nonces are kept in.
-Default 4m. In bytes or use m(mega), k(kilo), g(giga).
-The nonce cache is used to prevent dnscrypt message replaying. Client nonce
-should be unique for any pair of client pk/server sk.
-.TP
-.B dnscrypt\-nonce\-cache\-slabs: \fI<number>
+In bytes or use m(mega), k(kilo), g(giga).
+The nonce cache is used to prevent dnscrypt message replaying.
+Client nonce should be unique for any pair of client pk/server sk.
+.sp
+Default: 4m
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnscrypt\-nonce\-cache\-slabs: \fI<number>\fP
Number of slabs in the dnscrypt nonce cache.
Slabs reduce lock contention by threads.
Must be set to a power of 2.
Setting (close) to the number of cpus is a fairly good setting.
-If left unconfigured, it will be configured automatically to be a power of 2
-close to the number of configured threads in multi-threaded environments.
-.SS "EDNS Client Subnet Module Options"
-.LP
-The ECS module must be configured in the \fBmodule\-config:\fR directive e.g.,
-"subnetcache validator iterator" and be compiled into the daemon to be
-enabled. These settings go in the \fBserver:\fR section.
-.LP
+If left unconfigured, it will be configured automatically to be a power of
+2 close to the number of configured threads in multi\-threaded environments.
+.sp
+Default: (unconfigured)
+.UNINDENT
+.SS EDNS Client Subnet Module Options
+.sp
+The ECS module must be configured in the
+\fI\%module\-config\fP directive, e.g.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+module\-config: \(dqsubnetcache validator iterator\(dq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.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's address.
-When an answer contains the ECS option the response and the option are placed in
-a specialized cache. If the authority indicated no support, the response is
-stored in the regular cache.
-.LP
+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
+in a specialized cache.
+If the authority indicated no support, the response is stored in the regular
+cache.
+.sp
Additionally, when a client includes the option in its queries, Unbound will
forward the option when sending the query to addresses that are explicitly
-allowed in the configuration using \fBsend\-client\-subnet\fR. The option will
-always be forwarded, regardless the allowed addresses, if
-\fBclient\-subnet\-always\-forward\fR is set to yes. In this case the lookup in
-the regular cache is skipped.
-.LP
-The maximum size of the ECS cache is controlled by 'msg-cache-size' in the
-configuration file. On top of that, for each query only 100 different subnets
-are allowed to be stored for each address family. Exceeding that number, older
-entries will be purged from cache.
-.LP
+allowed in the configuration using
+\fI\%send\-client\-subnet\fP\&.
+The option will always be forwarded, regardless the allowed addresses, when
+\fI\%client\-subnet\-always\-forward: yes\fP
+is set.
+In this case the lookup in the regular cache is skipped.
+.sp
+The maximum size of the ECS cache is controlled by
+\fI\%msg\-cache\-size\fP in the configuration file.
+On top of that, for each query only 100 different subnets are allowed to be
+stored for each address family.
+Exceeding that number, older entries will be purged from cache.
+.sp
Note that due to the nature of how EDNS Client Subnet works, by segregating the
client IP space in order to try and have tailored responses for prefixes of
unknown sizes, resolution and cache response performance are impacted as a
require such functionality where the resolver and the clients belong to
different networks.
An example of that is an open resolver installation.
-.LP
-This module does not interact with the \fBserve\-expired*\fR and
-\fBprefetch:\fR options.
-.TP
-.B send\-client\-subnet: \fI<IP address>\fR
-Send client source address to this authority. Append /num to indicate a
-classless delegation netblock, for example like 10.2.3.4/24 or 2001::11/64. Can
-be given multiple times. Authorities not listed will not receive edns-subnet
-information, unless domain in query is specified in \fBclient\-subnet\-zone\fR.
-.TP
-.B client\-subnet\-zone: \fI<domain>\fR
-Send client source address in queries for this domain and its subdomains. Can be
-given multiple times. Zones not listed will not receive edns-subnet information,
-unless hosted by authority specified in \fBsend\-client\-subnet\fR.
-.TP
-.B client\-subnet\-always\-forward: \fI<yes or no>\fR
+.sp
+This module does not interact with the
+\fI\%serve\-expired*\fP and
+\fI\%prefetch\fP options.
+.INDENT 0.0
+.TP
+.B send\-client\-subnet: \fI<IP address>\fP
+Send client source address to this authority.
+Append /num to indicate a classless delegation netblock, for example like
+\fB10.2.3.4/24\fP or \fB2001::11/64\fP\&.
+Can be given multiple times.
+Authorities not listed will not receive edns\-subnet information, unless
+domain in query is specified in
+\fI\%client\-subnet\-zone\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B client\-subnet\-zone: \fI<domain>\fP
+Send client source address in queries for this domain and its subdomains.
+Can be given multiple times.
+Zones not listed will not receive edns\-subnet information, unless hosted by
+authority specified in
+\fI\%send\-client\-subnet\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B client\-subnet\-always\-forward: \fI<yes or no>\fP
Specify whether the ECS address check (configured using
-\fBsend\-client\-subnet\fR) is applied for all queries, even if the triggering
-query contains an ECS record, or only for queries for which the ECS record is
-generated using the querier address (and therefore did not contain ECS data in
-the client query). If enabled, the address check is skipped when the client
-query contains an ECS record. And the lookup in the regular cache is skipped.
-Default is no.
-.TP
-.B max\-client\-subnet\-ipv6: \fI<number>\fR
-Specifies the maximum prefix length of the client source address we are willing
-to expose to third parties for IPv6. Defaults to 56.
-.TP
-.B max\-client\-subnet\-ipv4: \fI<number>\fR
-Specifies the maximum prefix length of the client source address we are willing
-to expose to third parties for IPv4. Defaults to 24.
-.TP
-.B min\-client\-subnet\-ipv6: \fI<number>\fR
-Specifies the minimum prefix length of the IPv6 source mask we are willing to
-accept in queries. Shorter source masks result in REFUSED answers. Source mask
-of 0 is always accepted. Default is 0.
-.TP
-.B min\-client\-subnet\-ipv4: \fI<number>\fR
-Specifies the minimum prefix length of the IPv4 source mask we are willing to
-accept in queries. Shorter source masks result in REFUSED answers. Source mask
-of 0 is always accepted. Default is 0.
-.TP
-.B max\-ecs\-tree\-size\-ipv4: \fI<number>\fR
-Specifies the maximum number of subnets ECS answers kept in the ECS radix tree.
-This number applies for each qname/qclass/qtype tuple. Defaults to 100.
-.TP
-.B max\-ecs\-tree\-size\-ipv6: \fI<number>\fR
-Specifies the maximum number of subnets ECS answers kept in the ECS radix tree.
-This number applies for each qname/qclass/qtype tuple. Defaults to 100.
-.SS "Opportunistic IPsec Support Module Options"
-.LP
-The IPsec module must be configured in the \fBmodule\-config:\fR directive
-e.g., "ipsecmod validator iterator" and be compiled into Unbound by using
-\fB\-\-enable\-ipsecmod\fR to be enabled.
-These settings go in the \fBserver:\fR section.
-.LP
+\fI\%send\-client\-subnet\fP) is applied
+for all queries, even if the triggering query contains an ECS record, or
+only for queries for which the ECS record is generated using the querier
+address (and therefore did not contain ECS data in the client query).
+If enabled, the address check is skipped when the client query contains an
+ECS record.
+And the lookup in the regular cache is skipped.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B max\-client\-subnet\-ipv6: \fI<number>\fP
+Specifies the maximum prefix length of the client source address we are
+willing to expose to third parties for IPv6.
+.sp
+Default: 56
+.UNINDENT
+.INDENT 0.0
+.TP
+.B max\-client\-subnet\-ipv4: \fI<number>\fP
+Specifies the maximum prefix length of the client source address we are
+willing to expose to third parties for IPv4.
+.sp
+Default: 24
+.UNINDENT
+.INDENT 0.0
+.TP
+.B min\-client\-subnet\-ipv6: \fI<number>\fP
+Specifies the minimum prefix length of the IPv6 source mask we are willing
+to accept in queries.
+Shorter source masks result in REFUSED answers.
+Source mask of 0 is always accepted.
+.sp
+Default: 0
+.UNINDENT
+.INDENT 0.0
+.TP
+.B min\-client\-subnet\-ipv4: \fI<number>\fP
+Specifies the minimum prefix length of the IPv4 source mask we are willing
+to accept in queries.
+Shorter source masks result in REFUSED answers.
+Source mask of 0 is always accepted.
+Default: 0
+.UNINDENT
+.INDENT 0.0
+.TP
+.B max\-ecs\-tree\-size\-ipv4: \fI<number>\fP
+Specifies the maximum number of subnets ECS answers kept in the ECS radix
+tree.
+This number applies for each qname/qclass/qtype tuple.
+.sp
+Default: 100
+.UNINDENT
+.INDENT 0.0
+.TP
+.B max\-ecs\-tree\-size\-ipv6: \fI<number>\fP
+Specifies the maximum number of subnets ECS answers kept in the ECS radix
+tree.
+This number applies for each qname/qclass/qtype tuple.
+.sp
+Default: 100
+.UNINDENT
+.SS Opportunistic IPsec Support Module Options
+.sp
+The IPsec module must be configured in the
+\fI\%module\-config\fP directive, e.g.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+module\-config: \(dqipsecmod validator iterator\(dq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.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. If an answer was found, Unbound
-will call an external hook passing the following arguments:
-.TP 10
-\h'5'\fIQNAME\fR
-Domain name of the A/AAAA and IPSECKEY query. In string format.
-.TP 10
-\h'5'\fIIPSECKEY TTL\fR
+an IPSECKEY subquery for the same domain name.
+If an answer was found, Unbound will call an external hook passing the
+following arguments:
+.INDENT 0.0
+.TP
+.B QNAME
+Domain name of the A/AAAA and IPSECKEY query.
+In string format.
+.TP
+.B IPSECKEY TTL
TTL of the IPSECKEY RRset.
-.TP 10
-\h'5'\fIA/AAAA\fR
-String of space separated IP addresses present in the A/AAAA RRset. The IP
-addresses are in string format.
-.TP 10
-\h'5'\fIIPSECKEY\fR
-String of space separated IPSECKEY RDATA present in the IPSECKEY RRset. The
-IPSECKEY RDATA are in DNS presentation format.
-.LP
-The A/AAAA answer is then cached and returned to the client. If the external
-hook was called the TTL changes to ensure it doesn't surpass
-\fBipsecmod-max-ttl\fR.
-.LP
-The same procedure is also followed when \fBprefetch:\fR is used, but the
-A/AAAA answer is given to the client before the hook is called.
-\fBipsecmod-max-ttl\fR ensures that the A/AAAA answer given from cache is still
-relevant for opportunistic IPsec.
-.TP
-.B ipsecmod-enabled: \fI<yes or no>\fR
-Specifies whether the IPsec module is enabled or not. The IPsec module still
-needs to be defined in the \fBmodule\-config:\fR directive. This option
-facilitates turning on/off the module without restarting/reloading Unbound.
-Defaults to yes.
-.TP
-.B ipsecmod\-hook: \fI<filename>\fR
-Specifies the external hook that Unbound will call with \fIsystem\fR(3). The
-file can be specified as an absolute/relative path. The file needs the proper
-permissions to be able to be executed by the same user that runs Unbound. It
-must be present when the IPsec module is defined in the \fBmodule\-config:\fR
-directive.
-.TP
-.B ipsecmod-strict: \fI<yes or no>\fR
-If enabled Unbound requires the external hook to return a success value of 0.
-Failing to do so Unbound will reply with SERVFAIL. The A/AAAA answer will also
-not be cached. Defaults to no.
-.TP
-.B ipsecmod\-max-ttl: \fI<seconds>\fR
-Time to live maximum for A/AAAA cached records after calling the external hook.
-Defaults to 3600.
-.TP
-.B ipsecmod-ignore-bogus: \fI<yes or no>\fR
-Specifies the behaviour of Unbound when the IPSECKEY answer is bogus. If set
-to yes, the hook will be called and the A/AAAA answer will be returned to the
-client. If set to no, the hook will not be called and the answer to the
-A/AAAA query will be SERVFAIL. Mainly used for testing. Defaults to no.
-.TP
-.B ipsecmod\-allow: \fI<domain>\fR
-Allow the ipsecmod functionality for the domain so that the module logic will be
-executed. Can be given multiple times, for different domains. If the option is
-not specified, all domains are treated as being allowed (default).
-.TP
-.B ipsecmod\-whitelist: \fI<domain>
-Alternate syntax for \fBipsecmod\-allow\fR.
-.SS "Cache DB Module Options"
-.LP
-The Cache DB module must be configured in the \fBmodule\-config:\fR directive
-e.g., "validator cachedb iterator" and be compiled into the daemon
-with \fB\-\-enable\-cachedb\fR.
-If this module is enabled and configured, the specified backend database
-works as a second level cache:
-When Unbound cannot find an answer to a query in its built-in in-memory
-cache, it consults the specified backend.
-If it finds a valid answer in the backend, Unbound uses it to respond
-to the query without performing iterative DNS resolution.
-If Unbound cannot even find an answer in the backend, it resolves the
-query as usual, and stores the answer in the backend.
-.P
-This module interacts with the \fBserve\-expired\-*\fR options and will reply
-with expired data if Unbound is configured for that.
-.P
-If Unbound was built with
-\fB\-\-with\-libhiredis\fR
-on a system that has installed the hiredis C client library of Redis,
-then the "redis" backend can be used.
-This backend communicates with the specified Redis server over a TCP
-connection to store and retrieve cache data.
-It can be used as a persistent and/or shared cache backend.
-It should be noted that Unbound never removes data stored in the Redis server,
-even if some data have expired in terms of DNS TTL or the Redis server has
-cached too much data;
-if necessary the Redis server must be configured to limit the cache size,
-preferably with some kind of least-recently-used eviction policy.
-Additionally, the \fBredis\-expire\-records\fR option can be used in order to
-set the relative DNS TTL of the message as timeout to the Redis records; keep
-in mind that some additional memory is used per key and that the expire
-information is stored as absolute Unix timestamps in Redis (computer time must
-be stable).
-This backend uses synchronous communication with the Redis server
-based on the assumption that the communication is stable and sufficiently
-fast.
-The thread waiting for a response from the Redis server cannot handle
-other DNS queries.
-Although the backend has the ability to reconnect to the server when
-the connection is closed unexpectedly and there is a configurable timeout
-in case the server is overly slow or hangs up, these cases are assumed
-to be very rare.
-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.
-.P
-The
-.B cachedb:
-clause gives custom settings of the cache DB module.
.TP
-.B backend: \fI<backend name>\fR
+.B A/AAAA
+String of space separated IP addresses present in the A/AAAA RRset.
+The IP addresses are in string format.
+.TP
+.B IPSECKEY
+String of space separated IPSECKEY RDATA present in the IPSECKEY RRset.
+The IPSECKEY RDATA are in DNS presentation format.
+.UNINDENT
+.sp
+The A/AAAA answer is then cached and returned to the client.
+If the external hook was called the TTL changes to ensure it doesn\(aqt surpass
+\fI\%ipsecmod\-max\-ttl\fP\&.
+.sp
+The same procedure is also followed when
+\fI\%prefetch: yes\fP is set, but the A/AAAA answer is
+given to the client before the hook is called.
+\fI\%ipsecmod\-max\-ttl\fP ensures that the A/AAAA
+answer given from cache is still relevant for opportunistic IPsec.
+.INDENT 0.0
+.TP
+.B ipsecmod\-enabled: \fI<yes or no>\fP
+Specifies whether the IPsec module is enabled or not.
+The IPsec module still needs to be defined in the
+\fI\%module\-config\fP directive.
+This option facilitates turning on/off the module without
+restarting/reloading Unbound.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ipsecmod\-hook: \fI<filename>\fP
+Specifies the external hook that Unbound will call with \fIsystem(3)\fP\&.
+The file can be specified as an absolute/relative path.
+The file needs the proper permissions to be able to be executed by the same
+user that runs Unbound.
+It must be present when the IPsec module is defined in the
+\fI\%module\-config\fP directive.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ipsecmod\-strict: \fI<yes or no>\fP
+If enabled Unbound requires the external hook to return a success value of
+0.
+Failing to do so Unbound will reply with SERVFAIL.
+The A/AAAA answer will also not be cached.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ipsecmod\-max\-ttl: \fI<seconds>\fP
+Time to live maximum for A/AAAA cached records after calling the external
+hook.
+.sp
+Default: 3600
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ipsecmod\-ignore\-bogus: \fI<yes or no>\fP
+Specifies the behaviour of Unbound when the IPSECKEY answer is bogus.
+If set to yes, the hook will be called and the A/AAAA answer will be
+returned to the client.
+If set to no, the hook will not be called and the answer to the A/AAAA
+query will be SERVFAIL.
+Mainly used for testing.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ipsecmod\-allow: \fI<domain>\fP
+Allow the IPsec module functionality for the domain so that the module
+logic will be executed.
+Can be given multiple times, for different domains.
+If the option is not specified, all domains are treated as being allowed
+(default).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B ipsecmod\-whitelist: \fI<domain>\fP
+Alternate syntax for \fI\%ipsecmod\-allow\fP\&.
+.UNINDENT
+.SS Cache DB Module Options
+.sp
+The Cache DB module must be configured in the
+\fI\%module\-config\fP directive, e.g.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+module\-config: \(dqvalidator cachedb iterator\(dq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+and be compiled into the daemon with \fB\-\-enable\-cachedb\fP\&.
+.sp
+If this module is enabled and configured, the specified backend database works
+as a second level cache; when Unbound cannot find an answer to a query in its
+built\-in in\-memory cache, it consults the specified backend.
+If it finds a valid answer in the backend, Unbound uses it to respond to the
+query without performing iterative DNS resolution.
+If Unbound cannot even find an answer in the backend, it resolves the query as
+usual, and stores the answer in the backend.
+.sp
+This module interacts with the \fIserve\-expired\-*\fP options and will reply with
+expired data if Unbound is configured for that.
+.sp
+If Unbound was built with \fB\-\-with\-libhiredis\fP on a system that has installed
+the hiredis C client library of Redis, then the \fBredis\fP backend can be used.
+This backend communicates with the specified Redis server over a TCP connection
+to store and retrieve cache data.
+It can be used as a persistent and/or shared cache backend.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Unbound never removes data stored in the Redis server, even if some data
+have expired in terms of DNS TTL or the Redis server has cached too much
+data; if necessary the Redis server must be configured to limit the cache
+size, preferably with some kind of least\-recently\-used eviction policy.
+.UNINDENT
+.UNINDENT
+.sp
+Additionally, the
+\fI\%redis\-expire\-records\fP option
+can be used in order to set the relative DNS TTL of the message as timeout to
+the Redis records; keep in mind that some additional memory is used per key and
+that the expire information is stored as absolute Unix timestamps in Redis
+(computer time must be stable).
+.sp
+This backend uses synchronous communication with the Redis server based on the
+assumption that the communication is stable and sufficiently fast.
+The thread waiting for a response from the Redis server cannot handle other DNS
+queries.
+Although the backend has the ability to reconnect to the server when the
+connection is closed unexpectedly and there is a configurable timeout in case
+the server is overly slow or hangs up, these cases are assumed to be very rare.
+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.
+.INDENT 0.0
+.TP
+.B backend: \fI<backend name>\fP
Specify the backend database name.
-The default database is the in-memory backend named "testframe", which,
+The default database is the in\-memory backend named \fBtestframe\fP, which,
as the name suggests, is not of any practical use.
-Depending on the build-time configuration, "redis" backend may also be
+Depending on the build\-time configuration, \fBredis\fP backend may also be
used as described above.
+.sp
+Default: testframe
+.UNINDENT
+.INDENT 0.0
.TP
-.B secret-seed: \fI<"secret string">\fR
+.B secret\-seed: \fI\(dq<secret string>\(dq\fP
Specify a seed to calculate a hash value from query information.
This value will be used as the key of the corresponding answer for the
-backend database and can be customized if the hash should not be predictable
-operationally.
-If the backend database is shared by multiple Unbound instances,
-all instances must use the same secret seed.
-This option defaults to "default".
-.TP
-.B cachedb-no-store: \fI<yes or no>\fR
-If the backend should be read from, but not written to. This makes this
-instance not store dns messages in the backend. But if data is available it
-is retrieved. The default is no.
-.TP
-.B cachedb-check-when-serve-expired: \fI<yes or no>\fR
+backend database and can be customized if the hash should not be
+predictable operationally.
+If the backend database is shared by multiple Unbound instances, all
+instances must use the same secret seed.
+.sp
+Default: \(dqdefault\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B cachedb\-no\-store: \fI<yes or no>\fP
+If the backend should be read from, but not written to.
+This makes this instance not store dns messages in the backend.
+But if data is available it is retrieved.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B cachedb\-check\-when\-serve\-expired: \fI<yes or no>\fP
If enabled, the cachedb is checked before an expired response is returned.
-When \fBserve\-expired\fR is enabled, without \fBserve\-expired\-client\-timeout\fR, it then
-does not immediately respond with an expired response from cache, but instead
-first checks the cachedb for valid contents, and if so returns it. If the
-cachedb also has no valid contents, the serve expired response is sent.
-If also \fBserve\-expired\-client\-timeout\fR is enabled, the expired response
-is delayed until the timeout expires. Unless the lookup succeeds within the
-timeout. The default is yes.
-.P
-The following
-.B cachedb
-options are specific to the redis backend.
-.TP
-.B redis-server-host: \fI<server address or name>\fR
+When
+\fI\%serve\-expired\fP
+is enabled, without
+\fI\%serve\-expired\-client\-timeout\fP
+, it then does not immediately respond with an expired response from cache,
+but instead first checks the cachedb for valid contents, and if so returns it.
+If the cachedb also has no valid contents, the serve expired response is sent.
+If also
+\fI\%serve\-expired\-client\-timeout\fP
+is enabled, the expired response is delayed until the timeout expires.
+Unless the lookup succeeds within the timeout.
+.sp
+Default: yes
+.UNINDENT
+.sp
+The following \fBcachedb:\fP options are specific to the \fBredis\fP backend.
+.INDENT 0.0
+.TP
+.B redis\-server\-host: \fI<server address or name>\fP
The IP (either v6 or v4) address or domain name of the Redis server.
-In general an IP address should be specified as otherwise Unbound will have to
-resolve the name of the server every time it establishes a connection
-to the server.
-This option defaults to "127.0.0.1".
-.TP
-.B redis-server-port: \fI<port number>\fR
+In general an IP address should be specified as otherwise Unbound will have
+to resolve the name of the server every time it establishes a connection to
+the server.
+.sp
+Default: 127.0.0.1
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-server\-port: \fI<port number>\fP
The TCP port number of the Redis server.
-This option defaults to 6379.
-.TP
-.B redis-server-path: \fI<unix socket path>\fR
-The unix socket path to connect to the Redis server. Off by default, and it
-can be set to "" to turn this off. Unix sockets may have better throughput
-than the IP address option.
-.TP
-.B redis-server-password: \fI"<password>"\fR
+.sp
+Default: 6379
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-server\-path: \fI<unix socket path>\fP
+The unix socket path to connect to the Redis server.
+Unix sockets may have better throughput than the IP address option.
+.sp
+Default: \(dq\(dq (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-server\-password: \fI\(dq<password>\(dq\fP
The Redis AUTH password to use for the Redis server.
Only relevant if Redis is configured for client password authorisation.
-Off by default, and it can be set to "" to turn this off.
-.TP
-.B redis-timeout: \fI<msec>\fR
-The period until when Unbound waits for a response from the Redis sever.
-If this timeout expires Unbound closes the connection, treats it as
-if the Redis server does not have the requested data, and will try to
-re-establish a new connection later.
-This option defaults to 100 milliseconds.
-.TP
-.B redis-command-timeout: \fI<msec>\fR
+.sp
+Default: \(dq\(dq (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-timeout: \fI<msec>\fP
+The period until when Unbound waits for a response from the Redis server.
+If this timeout expires Unbound closes the connection, treats it as if the
+Redis server does not have the requested data, and will try to re\-establish
+a new connection later.
+.sp
+Default: 100
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-command\-timeout: \fI<msec>\fP
The timeout to use for Redis commands, in milliseconds.
-If 0, it uses the \fBredis\-timeout\fR value.
-The default is 0.
-.TP
-.B redis-connect-timeout: \fI<msec>\fR
+If \fB0\fP, it uses the
+\fI\%redis\-timeout\fP
+value.
+.sp
+Default: 0
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-connect\-timeout: \fI<msec>\fP
The timeout to use for Redis connection set up, in milliseconds.
-If 0, it uses the \fBredis\-timeout\fR value.
-The default is 0.
-.TP
-.B redis-expire-records: \fI<yes or no>
-If Redis record expiration is enabled. If yes, Unbound sets timeout for Redis
-records so that Redis can evict keys that have expired automatically. If
-Unbound is configured with \fBserve-expired\fR and \fBserve-expired-ttl\fR is 0,
-this option is internally reverted to "no". Redis SETEX support is required
-for this option (Redis >= 2.0.0).
-This option defaults to no.
-.TP
-.B redis-logical-db: \fI<logical database index>
+If \fB0\fP, it uses the
+\fI\%redis\-timeout\fP
+value.
+.sp
+Default: 0
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-expire\-records: \fI<yes or no>\fP
+If Redis record expiration is enabled.
+If yes, Unbound sets timeout for Redis records so that Redis can evict keys
+that have expired automatically.
+If Unbound is configured with
+\fI\%serve\-expired\fP and
+\fI\%serve\-expired\-ttl: 0\fP, this option is
+internally reverted to \(dqno\(dq.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+Redis SETEX support is required for this option (Redis >= 2.0.0).
+.UNINDENT
+.UNINDENT
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-logical\-db: \fI<logical database index>\fP
The logical database in Redis to use.
-These are databases in the same Redis instance sharing the same configuration
-and persisted in the same RDB/AOF file.
+These are databases in the same Redis instance sharing the same
+configuration and persisted in the same RDB/AOF file.
If unsure about using this option, Redis documentation
-(https://redis.io/commands/select/) suggests not to use a single Redis instance
-for multiple unrelated applications.
+(\fI\%https://redis.io/commands/select/\fP) suggests not to use a single Redis
+instance for multiple unrelated applications.
The default database in Redis is 0 while other logical databases need to be
-explicitly SELECT'ed upon connecting.
-This option defaults to 0.
-.TP
-.B redis-replica-server-host: \fI<server address or name>\fR
-The IP (either v6 or v4) address or domain name of the Redis replica server.
-In general an IP address should be specified as otherwise Unbound will have to
-resolve the name of the server every time it establishes a connection
-to the server.
-This server is treated as a read-only replica server
-(https://redis.io/docs/management/replication/#read-only-replica).
-If specified, all Redis read commands will go to this replica server, while
-the write commands will go to the \fBredis-server-host\fR.
-This option defaults to "" (disabled).
+explicitly SELECT\(aqed upon connecting.
+.sp
+Default: 0
+.UNINDENT
+.INDENT 0.0
.TP
-.B redis-replica-server-port: \fI<port number>\fR
+.B redis\-replica\-server\-host: \fI<server address or name>\fP
+The IP (either v6 or v4) address or domain name of the Redis server.
+In general an IP address should be specified as otherwise Unbound will have
+to resolve the name of the server every time it establishes a connection to
+the server.
+.sp
+This server is treated as a read\-only replica server
+(\fI\%https://redis.io/docs/management/replication/#read\-only\-replica\fP).
+If specified, all Redis read commands will go to this replica server, while
+the write commands will go to the
+\fI\%redis\-server\-host\fP\&.
+.sp
+Default: \(dq\(dq (disabled).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-replica\-server\-port: \fI<port number>\fP
The TCP port number of the Redis replica server.
-This option defaults to 6379.
-.TP
-.B redis-replica-server-path: \fI<unix socket path>\fR
-The unix socket path to connect to the Redis server. Off by default, and it
-can be set to "" to turn this off. Unix sockets may have better throughput
-than the IP address option.
-.TP
-.B redis-replica-server-password: \fI"<password>"\fR
-The Redis AUTH password to use for the Redis replica server.
+.sp
+Default: 6379
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-replica\-server\-path: \fI<unix socket path>\fP
+The unix socket path to connect to the Redis replica server.
+Unix sockets may have better throughput than the IP address option.
+.sp
+Default: \(dq\(dq (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-replica\-server\-password: \fI\(dq<password>\(dq\fP
+The Redis AUTH password to use for the Redis server.
Only relevant if Redis is configured for client password authorisation.
-Off by default, and it can be set to "" to turn this off.
-.TP
-.B redis-replica-timeout: \fI<msec>\fR
-The period until when Unbound waits for a response from the Redis replica sever.
-If this timeout expires Unbound closes the connection, treats it as
-if the Redis replica server does not have the requested data, and will try to
-re-establish a new connection later.
-This option defaults to 100 milliseconds.
+.sp
+Default: \(dq\(dq (disabled)
+.UNINDENT
+.INDENT 0.0
.TP
-.B redis-replica-command-timeout: \fI<msec>\fR
+.B redis\-replica\-timeout: \fI<msec>\fP
+The period until when Unbound waits for a response from the Redis replica
+server.
+If this timeout expires Unbound closes the connection, treats it as if the
+Redis server does not have the requested data, and will try to re\-establish
+a new connection later.
+.sp
+Default: 100
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-replica\-command\-timeout: \fI<msec>\fP
The timeout to use for Redis replica commands, in milliseconds.
-If 0, it uses the \fBredis\-replica\-timeout\fR value.
-The default is 0.
-.TP
-.B redis-replica-connect-timeout: \fI<msec>\fR
+If \fB0\fP, it uses the
+\fI\%redis\-replica\-timeout\fP
+value.
+.sp
+Default: 0
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-replica\-connect\-timeout: \fI<msec>\fP
The timeout to use for Redis replica connection set up, in milliseconds.
-If 0, it uses the \fBredis\-replica\-timeout\fR value.
-The default is 0.
-.TP
-.B redis-replica-logical-db: \fI<logical database index>
-Same as \fBredis-logical-db\fR but for the Redis replica server.
-This option defaults to 0.
+If \fB0\fP, it uses the
+\fI\%redis\-replica\-timeout\fP
+value.
+.sp
+Default: 0
+.UNINDENT
+.INDENT 0.0
+.TP
+.B redis\-replica\-logical\-db: \fI<logical database index>\fP
+Same as \fI\%redis\-logical\-db\fP but
+for the Redis replica server.
+.sp
+Default: 0
+.UNINDENT
.SS DNSTAP Logging Options
-DNSTAP support, when compiled in by using \fB\-\-enable\-dnstap\fR, is enabled
-in the \fBdnstap:\fR 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 connects per-process to the
-destination.
-.TP
-.B dnstap-enable: \fI<yes or no>
-If dnstap is enabled. Default no. If yes, it connects to the dnstap server
-and if any of the dnstap-log-..-messages options is enabled it sends logs
-for those messages to the server.
-.TP
-.B dnstap-bidirectional: \fI<yes or no>
-Use frame streams in bidirectional mode to transfer DNSTAP messages. Default is
-yes.
-.TP
-.B dnstap-socket-path: \fI<file name>
+.sp
+DNSTAP support, when compiled in by using \fB\-\-enable\-dnstap\fP, is 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
+connects per\-process to the destination.
+.INDENT 0.0
+.TP
+.B dnstap\-enable: \fI<yes or no>\fP
+If dnstap is enabled.
+If yes, it connects to the DNSTAP server and if any of the
+\fIdnstap\-log\-..\-messages:\fP options is enabled it sends logs for those
+messages to the server.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-bidirectional: \fI<yes or no>\fP
+Use frame streams in bidirectional mode to transfer DNSTAP messages.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-socket\-path: \fI<file name>\fP
Sets the unix socket file name for connecting to the server that is
-listening on that socket. Default is "@DNSTAP_SOCKET_PATH@".
-.TP
-.B dnstap-ip: \fI<IPaddress[@port]>
-If "", the unix socket is used, if set with an IP address (IPv4 or IPv6)
-that address is used to connect to the server.
-.TP
-.B dnstap-tls: \fI<yes or no>
-Set this to use TLS to connect to the server specified in \fBdnstap-ip\fR.
-The default is yes. If set to no, TCP is used to connect to the server.
-.TP
-.B dnstap-tls-server-name: \fI<name of TLS authentication>
-The TLS server name to authenticate the server with. Used when \fBdnstap-tls\fR is enabled. If "" it is ignored, default "".
-.TP
-.B dnstap-tls-cert-bundle: \fI<file name of cert bundle>
-The pem file with certs to verify the TLS server certificate. If "" the
-server default cert bundle is used, or the windows cert bundle on windows.
-Default is "".
-.TP
-.B dnstap-tls-client-key-file: \fI<file name>
-The client key file for TLS client authentication. If "" client
-authentication is not used. Default is "".
-.TP
-.B dnstap-tls-client-cert-file: \fI<file name>
-The client cert file for TLS client authentication. Default is "".
-.TP
-.B dnstap-send-identity: \fI<yes or no>
+listening on that socket.
+.sp
+Default: @DNSTAP_SOCKET_PATH@
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-ip: \fI<IPaddress[@port]>\fP
+If \fB\(dq\(dq\fP, the unix socket is used, if set with an IP address (IPv4 or
+IPv6) that address is used to connect to the server.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-tls: \fI<yes or no>\fP
+Set this to use TLS to connect to the server specified in
+\fI\%dnstap\-ip\fP\&.
+If set to no, TCP is used to connect to the server.
+.sp
+Default: yes
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-tls\-server\-name: \fI<name of TLS authentication>\fP
+The TLS server name to authenticate the server with.
+Used when \fI\%dnstap\-tls: yes\fP is set.
+If \fB\(dq\(dq\fP it is ignored.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-tls\-cert\-bundle: \fI<file name of cert bundle>\fP
+The pem file with certs to verify the TLS server certificate.
+If \fB\(dq\(dq\fP the server default cert bundle is used, or the windows cert
+bundle on windows.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-tls\-client\-key\-file: \fI<file name>\fP
+The client key file for TLS client authentication.
+If \fB\(dq\(dq\fP client authentication is not used.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-tls\-client\-cert\-file: \fI<file name>\fP
+The client cert file for TLS client authentication.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-send\-identity: \fI<yes or no>\fP
If enabled, the server identity is included in the log messages.
-Default is no.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
.TP
-.B dnstap-send-version: \fI<yes or no>
+.B dnstap\-send\-version: \fI<yes or no>\fP
If enabled, the server version if included in the log messages.
-Default is no.
-.TP
-.B dnstap-identity: \fI<string>
-The identity to send with messages, if "" the hostname is used.
-Default is "".
-.TP
-.B dnstap-version: \fI<string>
-The version to send with messages, if "" the package version is used.
-Default is "".
-.TP
-.B dnstap-sample-rate: \fI<number>
-The sample rate for log of messages, it logs only 1/N messages. With 0 it
-is disabled. Default is 0. This is useful in a high volume environment,
-where log functionality would otherwise not be reliable. For example 10
-would spend only 1/10th time on logging, and 100 would only spend a
-hundredth of the time on logging.
-.TP
-.B dnstap-log-resolver-query-messages: \fI<yes or no>
-Enable to log resolver query messages. Default is no.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-identity: \fI<string>\fP
+The identity to send with messages, if \fB\(dq\(dq\fP the hostname is used.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-version: \fI<string>\fP
+The version to send with messages, if \fB\(dq\(dq\fP the package version is used.
+.sp
+Default: \(dq\(dq
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-sample\-rate: \fI<number>\fP
+The sample rate for log of messages, it logs only 1/N messages.
+With 0 it is disabled.
+This is useful in a high volume environment, where log functionality would
+otherwise not be reliable.
+For example 10 would spend only 1/10th time on logging, and 100 would only
+spend a hundredth of the time on logging.
+.sp
+Default: 0 (disabled)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-log\-resolver\-query\-messages: \fI<yes or no>\fP
+Enable to log resolver query messages.
These are messages from Unbound to upstream servers.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
.TP
-.B dnstap-log-resolver-response-messages: \fI<yes or no>
-Enable to log resolver response messages. Default is no.
+.B dnstap\-log\-resolver\-response\-messages: \fI<yes or no>\fP
+Enable to log resolver response messages.
These are replies from upstream servers to Unbound.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
.TP
-.B dnstap-log-client-query-messages: \fI<yes or no>
-Enable to log client query messages. Default is no.
+.B dnstap\-log\-client\-query\-messages: \fI<yes or no>\fP
+Enable to log client query messages.
These are client queries to Unbound.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
.TP
-.B dnstap-log-client-response-messages: \fI<yes or no>
-Enable to log client response messages. Default is no.
+.B dnstap\-log\-client\-response\-messages: \fI<yes or no>\fP
+Enable to log client response messages.
These are responses from Unbound to clients.
-.TP
-.B dnstap-log-forwarder-query-messages: \fI<yes or no>
-Enable to log forwarder query messages. Default is no.
-.TP
-.B dnstap-log-forwarder-response-messages: \fI<yes or no>
-Enable to log forwarder response messages. Default is no.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-log\-forwarder\-query\-messages: \fI<yes or no>\fP
+Enable to log forwarder query messages.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B dnstap\-log\-forwarder\-response\-messages: \fI<yes or no>\fP
+Enable to log forwarder response messages.
+.sp
+Default: no
+.UNINDENT
.SS Response Policy Zone Options
-.LP
-Response Policy Zones are configured with \fBrpz:\fR, and each one must have a
-\fBname:\fR. 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. Note that a
-PASSTHRU action is still considered a match.
-The \fBrespip\fR module needs to be added to the \fBmodule-config\fR, e.g.:
-\fBmodule-config: "respip validator iterator"\fR.
-.P
+.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.
+Note that a PASSTHRU action is still considered a match.
+The respip module needs to be added to the
+\fI\%module\-config\fP, e.g.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+module\-config: \(dqrespip validator iterator\(dq
+.ft P
+.fi
+.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. RPZ QNAME triggers are applied after \fBlocal\-zones\fR and
-before \fBauth\-zones\fR.
-.P
+and drop.
+RPZ QNAME triggers are applied after any
+\fI\%local\-zone\fP and before any
+\fI\%auth\-zone\fP\&.
+.sp
The RPZ zone is a regular DNS zone formatted with a SOA start record as usual.
The items in the zone are entries, that specify what to act on (the trigger)
and what to do (the action).
the resource record.
The names all end in the zone name, so you could type the trigger names without
a trailing dot in the zonefile.
-.P
-An example RPZ record, that answers example.com with NXDOMAIN
+.sp
+An example RPZ record, that answers \fBexample.com\fP with \fBNXDOMAIN\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
.nf
- example.com CNAME .
+.ft C
+example.com CNAME .
+.ft P
.fi
-.P
+.UNINDENT
+.UNINDENT
+.sp
The triggers are encoded in the name on the left
+.INDENT 0.0
+.INDENT 3.5
+.sp
.nf
- name query name
- netblock.rpz-client-ip client IP address
- netblock.rpz-ip response IP address in the answer
- name.rpz-nsdname nameserver name
- netblock.rpz-nsip nameserver IP address
+.ft C
+name query name
+netblock.rpz\-client\-ip client IP address
+netblock.rpz\-ip response IP address in the answer
+name.rpz\-nsdname nameserver name
+netblock.rpz\-nsip nameserver IP address
+.ft P
.fi
-The netblock is written as <netblocklen>.<ip address in reverse>.
-For IPv6 use 'zz' for '::'. Specify individual addresses with scope length
-of 32 or 128. For example, 24.10.100.51.198.rpz-ip is 198.51.100.10/24 and
-32.10.zz.db8.2001.rpz-ip is 2001:db8:0:0:0:0:0:10/32.
-.P
+.UNINDENT
+.UNINDENT
+.sp
+The netblock is written as \fB<netblocklen>.<ip address in reverse>\fP\&.
+For IPv6 use \fB\(aqzz\(aq\fP for \fB\(aq::\(aq\fP\&.
+Specify individual addresses with scope length of 32 or 128.
+For example, \fB24.10.100.51.198.rpz\-ip\fP is \fB198.51.100.10/24\fP and
+\fB32.10.zz.db8.2001.rpz\-ip\fP is \fB2001:db8:0:0:0:0:0:10/32\fP\&.
+.sp
The actions are specified with the record on the right
+.INDENT 0.0
+.INDENT 3.5
+.sp
.nf
- CNAME . nxdomain reply
- CNAME *. nodata reply
- CNAME rpz-passthru. do nothing, allow to continue
- CNAME rpz-drop. the query is dropped
- CNAME rpz-tcp-only. answer over TCP
- A 192.0.2.1 answer with this IP address
+.ft C
+CNAME . nxdomain reply
+CNAME *. nodata reply
+CNAME rpz\-passthru. do nothing, allow to continue
+CNAME rpz\-drop. the query is dropped
+CNAME rpz\-tcp\-only. answer over TCP
+A 192.0.2.1 answer with this IP address
+.ft P
.fi
-Other records like AAAA, TXT and other CNAMEs (not rpz-..) can also be used to
+.UNINDENT
+.UNINDENT
+.sp
+Other records like AAAA, TXT and other CNAMEs (not rpz\-..) can also be used to
answer queries with that content.
-.P
-The RPZ zones can be configured in the config file with these settings in the \fBrpz:\fR block.
+.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>
+.B name: \fI<zone name>\fP
Name of the authority zone.
-.TP
-.B primary: \fI<IP address or host name>
-Where to download a copy of the zone from, with AXFR and IXFR. Multiple
-primaries can be specified. They are all tried if one fails.
-To use a nondefault port for DNS communication append '@' with the port number.
-You can append a '#' and a name, then AXFR over TLS can be used and the tls authentication certificates will be checked with that name. If you combine
-the '@' and '#', the '@' comes first.
-If you point it at another Unbound instance, it would not work because
-that does not support AXFR/IXFR for the zone, but if you used \fBurl:\fR to download
-the zonefile as a text file from a webserver that would work.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B primary: \fI<IP address or host name>\fP
+Where to download a copy of the zone from, with AXFR and IXFR.
+Multiple primaries can be specified.
+They are all tried if one fails.
+.sp
+To use a non\-default port for DNS communication append \fB\(aq@\(aq\fP with the
+port number.
+.sp
+You can append a \fB\(aq#\(aq\fP and a name, then AXFR over TLS can be used and the
+TLS authentication certificates will be checked with that name.
+.sp
+If you combine the \fB\(aq@\(aq\fP and \fB\(aq#\(aq\fP, the \fB\(aq@\(aq\fP comes first.
+If you point it at another Unbound instance, it would not work because that
+does not support AXFR/IXFR for the zone, but if you used
+\fI\%url\fP to download the zonefile as a text file
+from a webserver that would work.
+.sp
If you specify the hostname, you cannot use the domain from the zonefile,
because it may not have that when retrieving that data, instead use a plain
IP address to avoid a circular dependency on retrieving that IP address.
-.TP
-.B master: \fI<IP address or host name>
-Alternate syntax for \fBprimary\fR.
-.TP
-.B url: \fI<url to zonefile>
-Where to download a zonefile for the zone. With http or https. An example
-for the url is "http://www.example.com/example.org.zone". Multiple url
-statements can be given, they are tried in turn. If only urls are given
-the SOA refresh timer is used to wait for making new downloads. If also
-primaries are listed, the primaries are first probed with UDP SOA queries to
-see if the SOA serial number has changed, reducing the number of downloads.
-If none of the urls work, the primaries are tried with IXFR and AXFR.
-For https, the \fBtls\-cert\-bundle\fR and the hostname from the url are used
-to authenticate the connection.
-.TP
-.B allow\-notify: \fI<IP address or host name or netblockIP/prefix>
-With allow\-notify you can specify additional sources of notifies.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B master: \fI<IP address or host name>\fP
+Alternate syntax for \fI\%primary\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B url: \fI<url to zonefile>\fP
+Where to download a zonefile for the zone.
+With HTTP or HTTPS.
+An example for the url is:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+http://www.example.com/example.org.zone
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Multiple url statements can be given, they are tried in turn.
+.sp
+If only urls are given the SOA refresh timer is used to wait for making new
+downloads.
+If also primaries are listed, the primaries are first probed with UDP SOA
+queries to see if the SOA serial number has changed, reducing the number of
+downloads.
+If none of the URLs work, the primaries are tried with IXFR and AXFR.
+.sp
+For HTTPS, the \fI\%tls\-cert\-bundle\fP and
+the hostname from the url are used to authenticate the connection.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B allow\-notify: \fI<IP address or host name or netblockIP/prefix>\fP
+With \fI\%allow\-notify\fP you can specify
+additional sources of notifies.
When notified, the server attempts to first probe and then zone transfer.
-If the notify is from a primary, it first attempts that primary. Otherwise
-other primaries are attempted. If there are no primaries, but only urls, the
-file is downloaded when notified. The primaries from primary: and url:
-statements are allowed notify by default.
-.TP
-.B zonefile: \fI<filename>
-The filename where the zone is stored. If not given then no zonefile is used.
+If the notify is from a primary, it first attempts that primary.
+Otherwise other primaries are attempted.
+If there are no primaries, but only urls, the file is downloaded when
+notified.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+The primaries from \fI\%primary\fP and
+\fI\%url\fP statements are allowed notify by
+default.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B zonefile: \fI<filename>\fP
+The filename where the zone is stored.
+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
+.INDENT 0.0
.TP
-.B rpz\-action\-override: \fI<action>
-Always use this RPZ action for matching triggers from this zone. Possible action
-are: nxdomain, nodata, passthru, drop, disabled and cname.
+.B rpz\-action\-override: \fI<action>\fP
+Always use this RPZ action for matching triggers from this zone.
+Possible actions are: \fInxdomain\fP, \fInodata\fP, \fIpassthru\fP, \fIdrop\fP, \fIdisabled\fP
+and \fIcname\fP\&.
+.UNINDENT
+.INDENT 0.0
.TP
-.B rpz\-cname\-override: \fI<domain>
+.B rpz\-cname\-override: \fI<domain>\fP
The CNAME target domain to use if the cname action is configured for
-\fBrpz\-action\-override\fR.
-.TP
-.B rpz\-log: \fI<yes or no>
-Log all applied RPZ actions for this RPZ zone. Default is no.
-.TP
-.B rpz\-log\-name: \fI<name>
+\fI\%rpz\-action\-override\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B rpz\-log: \fI<yes or no>\fP
+Log all applied RPZ actions for this RPZ zone.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
+.TP
+.B rpz\-log\-name: \fI<name>\fP
Specify a string to be part of the log line, for easy referencing.
+.UNINDENT
+.INDENT 0.0
.TP
-.B rpz\-signal\-nxdomain\-ra: \fI<yes or no>
-Signal when a query is blocked by the RPZ with NXDOMAIN with an unset RA flag.
+.B rpz\-signal\-nxdomain\-ra: \fI<yes or no>\fP
+Signal when a query is blocked by the RPZ with NXDOMAIN with an unset RA
+flag.
This allows certain clients, like dnsmasq, to infer that the domain is
-externally blocked. Default is no.
+externally blocked.
+.sp
+Default: no
+.UNINDENT
+.INDENT 0.0
.TP
-.B for\-downstream: \fI<yes or no>
+.B for\-downstream: \fI<yes or no>\fP
If enabled the zone is authoritatively answered for and queries for the RPZ
-zone information are answered to downstream clients. This is useful for
-monitoring scripts, that can then access the SOA information to check if
-the RPZ information is up to date. Default is no.
-.TP
-.B tags: \fI<list of tags>
-Limit the policies from this RPZ clause to clients with a matching tag. Tags
-need to be defined in \fBdefine\-tag\fR and can be assigned to client addresses
-using \fBaccess\-control\-tag\fR. 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 all clients.
-.SH "MEMORY CONTROL EXAMPLE"
-In the example config settings below memory usage is reduced. Some service
-levels are lower, notable very large data and a high TCP load are no longer
-supported. Very large data and high TCP loads are exceptional for the DNS.
+zone information are answered to downstream clients.
+This is useful for monitoring scripts, that can then access the SOA
+information to check if the RPZ information is up to date.
+.sp
+Default: no
+.UNINDENT
+.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.
+.sp
+Tags need to be defined in \fI\%define\-tag\fP and
+can be assigned to client addresses using
+\fI\%access\-control\-tag\fP or
+\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
+all clients.
+.UNINDENT
+.SH MEMORY CONTROL EXAMPLE
+.sp
+In the example config settings below memory usage is reduced.
+Some service levels are lower, notable very large data and a high TCP load are
+no longer supported.
+Very large data and high TCP loads are exceptional for the DNS.
DNSSEC validation is enabled, just add trust anchors.
-If you do not have to worry about programs using more than 3 Mb of memory,
-the below example is not for you. Use the defaults to receive full service,
-which on BSD\-32bit tops out at 30\-40 Mb after heavy usage.
-.P
+If you do not have to worry about programs using more than 3 Mb of memory, the
+below example is not for you.
+Use the defaults to receive full service, which on BSD\-32bit tops out at 30\-40
+Mb after heavy usage.
+.INDENT 0.0
+.INDENT 3.5
+.sp
.nf
+.ft C
# example settings that reduce memory usage
server:
- num\-threads: 1
- outgoing\-num\-tcp: 1 # this limits TCP service, uses less buffers.
- incoming\-num\-tcp: 1
- outgoing\-range: 60 # uses less memory, but less performance.
- msg\-buffer\-size: 8192 # note this limits service, 'no huge stuff'.
- msg\-cache\-size: 100k
- msg\-cache\-slabs: 1
- rrset\-cache\-size: 100k
- rrset\-cache\-slabs: 1
- infra\-cache\-numhosts: 200
- infra\-cache\-slabs: 1
- key\-cache\-size: 100k
- key\-cache\-slabs: 1
- neg\-cache\-size: 10k
- num\-queries\-per\-thread: 30
- target\-fetch\-policy: "2 1 0 0 0 0"
- harden\-large\-queries: "yes"
- harden\-short\-bufsize: "yes"
+ num\-threads: 1
+ outgoing\-num\-tcp: 1 # this limits TCP service, uses less buffers.
+ incoming\-num\-tcp: 1
+ outgoing\-range: 60 # uses less memory, but less performance.
+ msg\-buffer\-size: 8192 # note this limits service, \(aqno huge stuff\(aq.
+ msg\-cache\-size: 100k
+ msg\-cache\-slabs: 1
+ rrset\-cache\-size: 100k
+ rrset\-cache\-slabs: 1
+ infra\-cache\-numhosts: 200
+ infra\-cache\-slabs: 1
+ key\-cache\-size: 100k
+ key\-cache\-slabs: 1
+ neg\-cache\-size: 10k
+ num\-queries\-per\-thread: 30
+ target\-fetch\-policy: \(dq2 1 0 0 0 0\(dq
+ harden\-large\-queries: \(dqyes\(dq
+ harden\-short\-bufsize: \(dqyes\(dq
+.ft P
.fi
-.SH "FILES"
+.UNINDENT
+.UNINDENT
+.SH FILES
+.INDENT 0.0
.TP
-.I @UNBOUND_RUN_DIR@
+.B @UNBOUND_RUN_DIR@
default Unbound working directory.
.TP
-.I @UNBOUND_CHROOT_DIR@
-default
-\fIchroot\fR(2)
-location.
+.B @UNBOUND_CHROOT_DIR@
+default \fIchroot(2)\fP location.
.TP
-.I @ub_conf_file@
+.B @ub_conf_file@
Unbound configuration file.
.TP
-.I @UNBOUND_PIDFILE@
+.B @UNBOUND_PIDFILE@
default Unbound pidfile with process ID of the running daemon.
.TP
-.I unbound.log
-Unbound log file. default is to log to
-\fIsyslog\fR(3).
-.SH "SEE ALSO"
-\fIunbound\fR(8),
-\fIunbound\-checkconf\fR(8).
-.SH "AUTHORS"
-.B Unbound
-was written by NLnet Labs. Please see CREDITS file
-in the distribution for further details.
+.B unbound.log
+Unbound log file.
+Default is to log to \fIsyslog(3)\fP\&.
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fI\%unbound(8)\fP,
+\fI\%unbound\-checkonf(8)\fP\&.
+.SH AUTHOR
+Unbound developers are mentioned in the CREDITS file in the distribution.
+.SH COPYRIGHT
+1999-2025, NLnet Labs
+.\" Generated by docutils manpage writer.
+.
--- /dev/null
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+unbound.conf(5)
+===============
+
+Synopsis
+--------
+
+**unbound.conf**
+
+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.
+
+Example
+-------
+
+An example config file is shown below.
+Copy this to :file:`/etc/unbound/unbound.conf` and start the server with:
+
+.. code-block:: text
+
+ $ unbound -c /etc/unbound/unbound.conf
+
+Most settings are the defaults.
+Stop the server with:
+
+.. code-block:: text
+
+ $ kill `cat /etc/unbound/unbound.pid`
+
+Below is a minimal config file.
+The source distribution contains an extensive :file:`example.conf` file with
+all the options.
+
+.. code-block:: text
+
+ # unbound.conf(5) config file for unbound(8).
+ server:
+ directory: "/etc/unbound"
+ username: unbound
+ # make sure unbound can access entropy from inside the chroot.
+ # e.g. on linux the use these commands (on BSD, devfs(8) is used):
+ # mount --bind -n /dev/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"
+ # verbosity: 1 # uncomment and increase to get more logging.
+ # listen on all interfaces, answer queries from the local subnet.
+ interface: 0.0.0.0
+ interface: ::0
+ access-control: 10.0.0.0/8 allow
+ access-control: 2001:DB8::/64 allow
+
+File Format
+-----------
+
+There must be whitespace between keywords.
+Attribute keywords end with a colon ``':'``.
+An attribute is followed by 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.
+
+.. _unbound.conf.include:
+
+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.
+If also using :ref:`chroot<unbound.conf.chroot>`, using full path names for
+the included files works, relative pathnames for the included names work if the
+directory where the daemon is started equals its chroot/working directory or is
+specified before the include statement with :ref:`directory:
+dir<unbound.conf.directory>`.
+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
+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.
+
+.. _unbound.conf.server:
+
+Server Options
+^^^^^^^^^^^^^^
+
+These options are part of the **server:** clause.
+
+
+@@UAHL@unbound.conf@verbosity@@: *<number>*
+ The verbosity level.
+
+ Level 0
+ No verbosity, only errors.
+
+ Level 1
+ Gives operational information.
+
+ Level 2
+ Gives detailed operational information including short information per
+ query.
+
+ Level 3
+ Gives query level information, output per query.
+
+ Level 4
+ Gives algorithm level information.
+
+ Level 5
+ Logs client identification for cache misses.
+
+ The verbosity can also be increased from the command line and during run
+ time via remote control. See :doc:`unbound(8)</manpages/unbound>` and
+ :doc:`unbound-control(8)</manpages/unbound-control>` respectively.
+
+ Default: 1
+
+
+@@UAHL@unbound.conf@statistics-interval@@: *<seconds>*
+ The number of seconds between printing statistics to the log for every
+ thread.
+ Disable with value ``0`` or ``""``.
+ The histogram statistics are only printed if replies were sent during the
+ statistics interval, requestlist statistics are printed for every interval
+ (but can be 0).
+ This is because the median calculation requires data to be present.
+
+ Default: 0 (disabled)
+
+
+@@UAHL@unbound.conf@statistics-cumulative@@: *<yes or no>*
+ If enabled, statistics are cumulative since starting Unbound, without
+ clearing the statistics counters after logging the statistics.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@extended-statistics@@: *<yes or no>*
+ If enabled, extended statistics are printed from
+ :doc:`unbound-control(8)</manpages/unbound-control>`.
+ The counters are listed in
+ :doc:`unbound-control(8)</manpages/unbound-control>`.
+ Keeping track of more statistics takes time.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@statistics-inhibit-zero@@: *<yes or no>*
+ If enabled, selected extended statistics with a value of 0 are inhibited
+ from printing with
+ :doc:`unbound-control(8)</manpages/unbound-control>`.
+ These are query types, query classes, query opcodes, answer rcodes
+ (except NOERROR, FORMERR, SERVFAIL, NXDOMAIN, NOTIMPL, REFUSED)
+ and PRZ actions.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@num-threads@@: *<number>*
+ The number of threads to create to serve clients. Use 1 for no threading.
+
+ Default: 1
+
+
+@@UAHL@unbound.conf@port@@: *<port number>*
+ The port number on which the server responds to queries.
+
+ Default: 53
+
+
+@@UAHL@unbound.conf@interface@@: *<IP address or interface name[@port]>*
+ Interface to use to connect to the network.
+ This interface is listened to for queries from clients, and answers to
+ clients are given from it.
+ Can be given multiple times to work on several interfaces.
+ If none are given the default is to listen on localhost.
+
+ If an interface name is used instead of an IP address, the list of IP
+ addresses on that interface are used.
+ The interfaces are not changed on a reload (``kill -HUP``) but only on
+ restart.
+
+ A port number can be specified with @port (without spaces between interface
+ and port number), if not specified the default port (from
+ :ref:`port<unbound.conf.port>`) is used.
+
+
+@@UAHL@unbound.conf@ip-address@@: *<IP address or interface name[@port]>*
+ Same as :ref:`interface<unbound.conf.interface>` (for ease of
+ compatibility with :external+nsd:doc:`manpages/nsd.conf`).
+
+
+@@UAHL@unbound.conf@interface-automatic@@: *<yes or no>*
+ Listen on all addresses on all (current and future) interfaces, detect the
+ source interface on UDP queries and copy them to replies.
+ This is a lot like :ref:`ip-transparent<unbound.conf.ip-transparent>`, but
+ this option services all interfaces whilst with
+ :ref:`ip-transparent<unbound.conf.ip-transparent>` you can select which
+ (future) interfaces Unbound provides service on.
+ This feature is experimental, and needs support in your OS for particular
+ socket options.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@interface-automatic-ports@@: *"<string>"*
+ List the port numbers that
+ :ref:`interface-automatic<unbound.conf.interface-automatic>` listens on.
+ If empty, the default port is listened on.
+ The port numbers are separated by spaces in the string.
+
+ This can be used to have interface automatic to deal with the interface,
+ and listen on the normal port number, by including it in the list, and
+ also HTTPS or DNS-over-TLS port numbers by putting them in the list as
+ well.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf@outgoing-interface@@: *<IPv4/IPv6 address or IPv6 netblock>*
+ Interface to use to connect to the network.
+ This interface is used to send queries to authoritative servers and receive
+ their replies.
+ Can be given multiple times to work on several interfaces.
+ If none are given the default (all) is used.
+ You can specify the same interfaces in
+ :ref:`interface<unbound.conf.interface>` and
+ :ref:`outgoing-interface<unbound.conf.outgoing-interface>` lines, the
+ interfaces are then used for both purposes.
+ Outgoing queries are sent via a random outgoing interface to counter
+ spoofing.
+
+ If an IPv6 netblock is specified instead of an individual IPv6 address,
+ outgoing UDP queries will use a randomised source address taken from the
+ netblock to counter spoofing.
+ Requires the IPv6 netblock to be routed to the host running Unbound, and
+ requires OS support for unprivileged non-local binds (currently only
+ supported on Linux).
+ Several netblocks may be specified with multiple
+ :ref:`outgoing-interface<unbound.conf.outgoing-interface>` options, but do
+ not specify both an individual IPv6 address and an IPv6 netblock, or the
+ randomisation will be compromised.
+ Consider combining with :ref:`prefer-ip6: yes<unbound.conf.prefer-ip6>` to
+ increase the likelihood of IPv6 nameservers being selected for queries.
+ On Linux you need these two commands to be able to use the freebind socket
+ option to receive traffic for the ip6 netblock:
+
+ .. code-block:: text
+
+ ip -6 addr add mynetblock/64 dev lo && \
+ ip -6 route add local mynetblock/64 dev lo
+
+
+@@UAHL@unbound.conf@outgoing-range@@: *<number>*
+ Number of ports to open.
+ This number of file descriptors can be opened per thread.
+ Must be at least 1.
+ Default depends on compile options.
+ Larger numbers need extra resources from the operating system.
+ For performance a very large value is best, use libevent to make this
+ possible.
+
+ Default: 4096 (libevent) / 960 (minievent) / 48 (windows)
+
+
+@@UAHL@unbound.conf@outgoing-port-permit@@: *<port number or range>*
+ Permit Unbound to open this port or range of ports for use to send queries.
+ A larger number of permitted outgoing ports increases resilience against
+ spoofing attempts.
+ Make sure these ports are not needed by other daemons.
+ By default only ports above 1024 that have not been assigned by IANA are
+ used.
+ Give a port number or a range of the form "low-high", without spaces.
+
+ The :ref:`outgoing-port-permit<unbound.conf.outgoing-port-permit>` and
+ :ref:`outgoing-port-avoid<unbound.conf.outgoing-port-avoid>` statements
+ are processed in the line order of the config file, adding the permitted
+ ports and subtracting the avoided ports from the set of allowed ports.
+ The processing starts with the non IANA allocated ports above 1024 in the
+ set of allowed ports.
+
+
+@@UAHL@unbound.conf@outgoing-port-avoid@@: *<port number or range>*
+ Do not permit Unbound to open this port or range of ports for use to send
+ queries.
+ Use this to make sure Unbound does not grab a port that another daemon
+ needs.
+ The port is avoided on all outgoing interfaces, both IPv4 and IPv6.
+ By default only ports above 1024 that have not been assigned by IANA are
+ used.
+ Give a port number or a range of the form "low-high", without spaces.
+
+
+@@UAHL@unbound.conf@outgoing-num-tcp@@: *<number>*
+ Number of outgoing TCP buffers to allocate per thread.
+ If set to 0, or if :ref:`do-tcp: no<unbound.conf.do-tcp>` is set, no TCP
+ queries to authoritative servers are done.
+ For larger installations increasing this value is a good idea.
+
+ Default: 10
+
+
+@@UAHL@unbound.conf@incoming-num-tcp@@: *<number>*
+ Number of incoming TCP buffers to allocate per thread.
+ If set to 0, or if :ref:`do-tcp: no<unbound.conf.do-tcp>` is set, no TCP
+ queries from clients are accepted.
+ For larger installations increasing this value is a good idea.
+
+ Default: 10
+
+
+@@UAHL@unbound.conf@edns-buffer-size@@: *<number>*
+ Number of bytes size to advertise as the EDNS reassembly buffer size.
+ This is the value put into datagrams over UDP towards peers.
+ The actual buffer size is determined by
+ :ref:`msg-buffer-size<unbound.conf.msg-buffer-size>` (both for TCP and
+ UDP).
+ Do not set higher than that value.
+ Setting to 512 bypasses even the most stringent path MTU problems, but is
+ seen as extreme, since the amount of TCP fallback generated is excessive
+ (probably also for this resolver, consider tuning
+ :ref:`outgoing-num-tcp<unbound.conf.outgoing-num-tcp>`).
+
+ Default: 1232 (`DNS Flag Day 2020 recommendation
+ <https://dnsflagday.net/2020/>`__)
+
+
+@@UAHL@unbound.conf@max-udp-size@@: *<number>*
+ Maximum UDP response size (not applied to TCP response).
+ 65536 disables the UDP response size maximum, and uses the choice from the
+ client, always.
+ Suggested values are 512 to 4096.
+
+ Default: 1232 (same as :ref:`edns-buffer-size<unbound.conf.edns-buffer-size>`)
+
+
+@@UAHL@unbound.conf@stream-wait-size@@: *<number>*
+ Number of bytes size maximum to use for waiting stream buffers.
+ A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+ or gigabytes (1024*1024 bytes in a megabyte).
+ As TCP and TLS streams queue up multiple results, the amount of memory used
+ for these buffers does not exceed this number, otherwise the responses are
+ dropped.
+ This manages the total memory usage of the server (under heavy use), the
+ number of requests that can be queued up per connection is also limited,
+ with further requests waiting in TCP buffers.
+
+ Default: 4m
+
+
+@@UAHL@unbound.conf@msg-buffer-size@@: *<number>*
+ Number of bytes size of the message buffers.
+ Default is 65552 bytes, enough for 64 Kb packets, the maximum DNS message
+ size.
+ No message larger than this can be sent or received.
+ Can be reduced to use less memory, but some requests for DNS data, such as
+ for huge resource records, will result in a SERVFAIL reply to the client.
+
+ Default: 65552
+
+
+@@UAHL@unbound.conf@msg-cache-size@@: *<number>*
+ Number of bytes size of the message cache.
+ A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+ or gigabytes (1024*1024 bytes in a megabyte).
+
+ Default: 4m
+
+
+@@UAHL@unbound.conf@msg-cache-slabs@@: *<number>*
+ Number of slabs in the message cache.
+ Slabs reduce lock contention by threads.
+ Must be set to a power of 2.
+ Setting (close) to the number of cpus is a fairly good setting.
+ If left unconfigured, it will be configured automatically to be a power of
+ 2 close to the number of configured threads in multi-threaded environments.
+
+ Default: (unconfigured)
+
+
+@@UAHL@unbound.conf@num-queries-per-thread@@: *<number>*
+ The number of queries that every thread will service simultaneously.
+ If more queries arrive that need servicing, and no queries can be jostled
+ out (see :ref:`jostle-timeout<unbound.conf.jostle-timeout>`), then the
+ queries are dropped.
+ This forces the client to resend after a timeout; allowing the server time
+ to work on the existing queries.
+ Default depends on compile options.
+
+ Default: 2048 (libevent) / 512 (minievent) / 24 (windows)
+
+
+@@UAHL@unbound.conf@jostle-timeout@@: *<msec>*
+ Timeout used when the server is very busy.
+ Set to a value that usually results in one roundtrip to the authority
+ servers.
+
+ If too many queries arrive, then 50% of the queries are allowed to run to
+ completion, and the other 50% are replaced with the new incoming query if
+ they have already spent more than their allowed time.
+ This protects against denial of service by slow queries or high query
+ rates.
+
+ The effect is that the qps for long-lasting queries is about:
+
+ .. code-block:: text
+
+ (num-queries-per-thread / 2) / (average time for such long queries) qps
+
+ The qps for short queries can be about:
+
+ .. code-block:: text
+
+ (num-queries-per-thread / 2) / (jostle-timeout in whole seconds) qps per thread
+
+ about (2048/2)*5 = 5120 qps by default.
+
+ Default: 200
+
+
+@@UAHL@unbound.conf@delay-close@@: *<msec>*
+ Extra delay for timeouted UDP ports before they are closed, in msec.
+ This prevents very delayed answer packets from the upstream (recursive)
+ servers from bouncing against closed ports and setting off all sort of
+ close-port counters, with eg. 1500 msec.
+ When timeouts happen you need extra sockets, it checks the ID and remote IP
+ of packets, and unwanted packets are added to the unwanted packet counter.
+
+ Default: 0 (disabled)
+
+
+@@UAHL@unbound.conf@udp-connect@@: *<yes or no>*
+ Perform *connect(2)* for UDP sockets that mitigates ICMP side channel
+ leakage.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@unknown-server-time-limit@@: *<msec>*
+ The wait time in msec for waiting for an unknown server to reply.
+ Increase this if you are behind a slow satellite link, to eg. 1128.
+ That would then avoid re-querying every initial query because it times out.
+
+ Default: 376
+
+
+@@UAHL@unbound.conf@discard-timeout@@: *<msec>*
+ 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.
+ It is nice to be a bit larger than
+ :ref:`serve-expired-client-timeout<unbound.conf.serve-expired-client-timeout>`
+ if that is enabled.
+ A value of ``1900`` msec is suggested.
+ The value ``0`` disables it.
+
+ Default: 1900
+
+
+@@UAHL@unbound.conf@wait-limit@@: *<number>*
+ 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 ``0`` disables wait limits.
+
+ Default: 1000
+
+
+@@UAHL@unbound.conf@wait-limit-cookie@@: *<number>*
+ 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.
+
+ Default: 10000
+
+
+@@UAHL@unbound.conf@wait-limit-netblock@@: *<netblock>* *<number>*
+ The wait limit for the netblock.
+ If not given the
+ :ref:`wait-limit<unbound.conf.wait-limit>`
+ value is used.
+ The most specific netblock is used to determine the limit.
+ Useful for overriding the default for a specific, group or individual,
+ server.
+ The value ``-1`` disables wait limits for the netblock.
+ By default the loopback has a wait limit netblock of ``-1``, it is not
+ limited, because it is separated from the rest of network for spoofed
+ packets.
+ The loopback addresses ``127.0.0.0/8`` and ``::1/128`` are default at ``-1``.
+
+ Default: (none)
+
+
+@@UAHL@unbound.conf@wait-limit-cookie-netblock@@: *<netblock>* *<number>*
+ The wait limit for the netblock, when the query has a DNS Cookie.
+ If not given, the
+ :ref:`wait-limit-cookie<unbound.conf.wait-limit-cookie>`
+ value is used.
+ The value ``-1`` disables wait limits for the netblock.
+ The loopback addresses ``127.0.0.0/8`` and ``::1/128`` are default at ``-1``.
+
+ Default: (none)
+
+
+@@UAHL@unbound.conf@so-rcvbuf@@: *<number>*
+ If not 0, then set the SO_RCVBUF socket option to get more buffer space on
+ UDP port 53 incoming queries.
+ So that short spikes on busy servers do not drop packets (see counter in
+ ``netstat -su``).
+ Otherwise, the number of bytes to ask for, try "4m" on a busy server.
+
+ The OS caps it at a maximum, on linux Unbound needs root permission to
+ bypass the limit, or the admin can use ``sysctl net.core.rmem_max``.
+
+ On BSD change ``kern.ipc.maxsockbuf`` in ``/etc/sysctl.conf``.
+
+ On OpenBSD change header and recompile kernel.
+
+ On Solaris ``ndd -set /dev/udp udp_max_buf 8388608``.
+
+ Default: 0 (use system value)
+
+
+@@UAHL@unbound.conf@so-sndbuf@@: *<number>*
+ If not 0, then set the SO_SNDBUF socket option to get more buffer space on
+ UDP port 53 outgoing queries.
+ This for very busy servers handles spikes in answer traffic, otherwise:
+
+ .. code-block:: text
+
+ send: resource temporarily unavailable
+
+ can get logged, the buffer overrun is also visible by ``netstat -su``.
+ If set to 0 it uses the system value.
+ Specify the number of bytes to ask for, try "8m" on a very busy server.
+
+ It needs some space to be able to deal with packets that wait for local
+ address resolution, from like ARP and NDP discovery, before they are sent
+ out, hence it is elevated above the system default by default.
+
+ The OS caps it at a maximum, on linux Unbound needs root permission to
+ bypass the limit, or the admin can use ``sysctl net.core.wmem_max``.
+
+ On BSD, Solaris changes are similar to
+ :ref:`so-rcvbuf<unbound.conf.so-rcvbuf>`.
+
+ Default: 4m
+
+
+@@UAHL@unbound.conf@so-reuseport@@: *<yes or no>*
+ If yes, then open dedicated listening sockets for incoming queries for each
+ thread and try to set the SO_REUSEPORT socket option on each socket.
+ May distribute incoming queries to threads more evenly.
+
+ On Linux it is supported in kernels >= 3.9.
+
+ On other systems, FreeBSD, OSX it may also work.
+
+ You can enable it (on any platform and kernel), it then attempts to open
+ the port and passes the option if it was available at compile time, if that
+ works it is used, if it fails, it continues silently (unless verbosity 3)
+ without the option.
+
+ At extreme load it could be better to turn it off to distribute the queries
+ evenly, reported for Linux systems (4.4.x).
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@ip-transparent@@: *<yes or no>*
+ If yes, then use IP_TRANSPARENT socket option on sockets where Unbound is
+ listening for incoming traffic.
+ Allows you to bind to non-local interfaces.
+ For example for non-existent IP addresses that are going to exist later on,
+ with host failover configuration.
+
+ This is a lot like
+ :ref:`interface-automatic<unbound.conf.interface-automatic>`, but that one
+ services all interfaces and with this option you can select which (future)
+ interfaces Unbound provides service on.
+
+ This option needs Unbound to be started with root permissions on some
+ systems.
+ The option uses IP_BINDANY on FreeBSD systems and SO_BINDANY on OpenBSD
+ systems.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@ip-freebind@@: *<yes or no>*
+ If yes, then use IP_FREEBIND socket option on sockets where Unbound is
+ listening to incoming traffic.
+ Allows you to bind to IP addresses that are nonlocal or do not exist, like
+ when the network interface or IP address is down.
+
+ Exists only on Linux, where the similar
+ :ref:`ip-transparent<unbound.conf.ip-transparent>` option is also
+ available.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@ip-dscp@@: *<number>*
+ The value of the Differentiated Services Codepoint (DSCP) in the
+ differentiated services field (DS) of the outgoing IP packet headers.
+ The field replaces the outdated IPv4 Type-Of-Service field and the IPv6
+ traffic class field.
+
+
+@@UAHL@unbound.conf@rrset-cache-size@@: *<number>*
+ Number of bytes size of the RRset cache.
+ A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+ or gigabytes (1024*1024 bytes in a megabyte).
+
+ Default: 4m
+
+
+@@UAHL@unbound.conf@rrset-cache-slabs@@: *<number>*
+ Number of slabs in the RRset cache.
+ Slabs reduce lock contention by threads.
+ Must be set to a power of 2.
+ Setting (close) to the number of cpus is a fairly good setting.
+ If left unconfigured, it will be configured automatically to be a power of
+ 2 close to the number of configured threads in multi-threaded environments.
+
+ Default: (unconfigured)
+
+
+@@UAHL@unbound.conf@cache-max-ttl@@: *<seconds>*
+ Time to live maximum for RRsets and messages in the cache.
+ When the TTL expires, the cache item has expired.
+ Can be set lower to force the resolver to query for data often, and not
+ trust (very large) TTL values.
+ Downstream clients also see the lower TTL.
+
+
+ Default: 86400 (1 day)
+
+
+@@UAHL@unbound.conf@cache-min-ttl@@: *<seconds>*
+ Time to live minimum for RRsets and messages in the cache.
+ If the minimum kicks in, the data is cached for longer than the domain
+ owner intended, and thus less queries are made to look up the data.
+ Zero makes sure the data in the cache is as the domain owner intended,
+ higher values, especially more than an hour or so, can lead to trouble as
+ the data in the cache does not match up with the actual data any more.
+
+ Default: 0 (disabled)
+
+
+@@UAHL@unbound.conf@cache-max-negative-ttl@@: *<seconds>*
+ Time to live maximum for negative responses, these have a SOA in the
+ authority section that is limited in time.
+ This applies to NXDOMAIN and NODATA answers.
+
+ Default: 3600
+
+
+@@UAHL@unbound.conf@cache-min-negative-ttl@@: *<seconds>*
+ Time to live minimum for negative responses, these have a SOA in the
+ authority section that is limited in time.
+ If this is disabled and
+ :ref:`cache-min-ttl<unbound.conf.cache-min-ttl>`
+ is configured, it will take effect instead.
+ In that case you can set this to ``1`` to honor the upstream TTL.
+ This applies to NXDOMAIN and NODATA answers.
+
+ Default: 0 (disabled)
+
+
+@@UAHL@unbound.conf@infra-host-ttl@@: *<seconds>*
+ Time to live for entries in the host cache.
+ The host cache contains roundtrip timing, lameness and EDNS support
+ information.
+
+ Default: 900
+
+
+@@UAHL@unbound.conf@infra-cache-slabs@@: *<number>*
+ Number of slabs in the infrastructure cache.
+ Slabs reduce lock contention by threads.
+ Must be set to a power of 2.
+ Setting (close) to the number of cpus is a fairly good setting.
+ If left unconfigured, it will be configured automatically to be a power of
+ 2 close to the number of configured threads in multi-threaded environments.
+
+ Default: (unconfigured)
+
+
+@@UAHL@unbound.conf@infra-cache-numhosts@@: *<number>*
+ Number of hosts for which information is cached.
+
+ Default: 10000
+
+
+@@UAHL@unbound.conf@infra-cache-min-rtt@@: *<msec>*
+ Lower limit for dynamic retransmit timeout calculation in infrastructure
+ cache.
+ Increase this value if using forwarders needing more time to do recursive
+ name resolution.
+
+ Default: 50
+
+
+@@UAHL@unbound.conf@infra-cache-max-rtt@@: *<msec>*
+ Upper limit for dynamic retransmit timeout calculation in infrastructure
+ cache.
+
+ Default: 120000 (2 minutes)
+
+
+@@UAHL@unbound.conf@infra-keep-probing@@: *<yes or no>*
+ If enabled the server keeps probing hosts that are down, in the one probe
+ at a time regime.
+ Hosts that are down, eg. they did not respond during the one probe at a
+ time period, are marked as down and it may take
+ :ref:`infra-host-ttl<unbound.conf.infra-host-ttl>` time to get probed
+ again.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@define-tag@@: *"<list of tags>"*
+ Define the tags that can be used with
+ :ref:`local-zone<unbound.conf.local-zone>` and
+ :ref:`access-control<unbound.conf.access-control>`.
+ Enclose the list between quotes (``""``) and put spaces between tags.
+
+
+@@UAHL@unbound.conf@do-ip4@@: *<yes or no>*
+ Enable or disable whether IPv4 queries are answered or issued.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@do-ip6@@: *<yes or no>*
+ Enable or disable whether IPv6 queries are answered or issued.
+ If disabled, queries are not answered on IPv6, and queries are not sent on
+ IPv6 to the internet nameservers.
+ With this option you can disable the IPv6 transport for sending DNS
+ traffic, it does not impact the contents of the DNS traffic, which may have
+ IPv4 (A) and IPv6 (AAAA) addresses in it.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@prefer-ip4@@: *<yes or no>*
+ If enabled, prefer IPv4 transport for sending DNS queries to internet
+ nameservers.
+ Useful if the IPv6 netblock the server has, the entire /64 of that is not
+ owned by one operator and the reputation of the netblock /64 is an issue,
+ using IPv4 then uses the IPv4 filters that the upstream servers have.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@prefer-ip6@@: *<yes or no>*
+ If enabled, prefer IPv6 transport for sending DNS queries to internet
+ nameservers.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@do-udp@@: *<yes or no>*
+ Enable or disable whether UDP queries are answered or issued.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@do-tcp@@: *<yes or no>*
+ Enable or disable whether TCP queries are answered or issued.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@tcp-mss@@: *<number>*
+ Maximum segment size (MSS) of TCP socket on which the server responds to
+ queries.
+ Value lower than common MSS on Ethernet (1220 for example) will address
+ path MTU problem.
+ Note that not all platform supports socket option to set MSS (TCP_MAXSEG).
+ Default is system default MSS determined by interface MTU and negotiation
+ between server and client.
+
+
+@@UAHL@unbound.conf@outgoing-tcp-mss@@: *<number>*
+ Maximum segment size (MSS) of TCP socket for outgoing queries (from Unbound
+ to other servers).
+ Value lower than common MSS on Ethernet (1220 for example) will address
+ path MTU problem.
+ Note that not all platform supports socket option to set MSS (TCP_MAXSEG).
+ Default is system default MSS determined by interface MTU and negotiation
+ between Unbound and other servers.
+
+
+@@UAHL@unbound.conf@tcp-idle-timeout@@: *<msec>*
+ The period Unbound will wait for a query on a TCP connection.
+ If this timeout expires Unbound closes the connection.
+ When the number of free incoming TCP buffers falls below 50% of the total
+ number configured, the option value used is progressively reduced, first to
+ 1% of the configured value, then to 0.2% of the configured value if the
+ number of free buffers falls below 35% of the total number configured, and
+ finally to 0 if the number of free buffers falls below 20% of the total
+ number configured.
+ A minimum timeout of 200 milliseconds is observed regardless of the option
+ value used.
+ It will be overridden by
+ :ref:`edns-tcp-keepalive-timeout<unbound.conf.edns-tcp-keepalive-timeout>`
+ if
+ :ref:`edns-tcp-keepalive<unbound.conf.edns-tcp-keepalive>`
+ is enabled.
+
+ Default: 30000 (30 seconds)
+
+
+@@UAHL@unbound.conf@tcp-reuse-timeout@@: *<msec>*
+ The period Unbound will keep TCP persistent connections open to authority
+ servers.
+
+ Default: 60000 (60 seconds)
+
+
+@@UAHL@unbound.conf@max-reuse-tcp-queries@@: *<number>*
+ The maximum number of queries that can be sent on a persistent TCP
+ connection.
+
+ Default: 200
+
+
+@@UAHL@unbound.conf@tcp-auth-query-timeout@@: *<number>*
+ Timeout in milliseconds for TCP queries to auth servers.
+
+ Default: 3000 (3 seconds)
+
+
+@@UAHL@unbound.conf@edns-tcp-keepalive@@: *<yes or no>*
+ Enable or disable EDNS TCP Keepalive.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@edns-tcp-keepalive-timeout@@: *<msec>*
+ Overrides
+ :ref:`tcp-idle-timeout<unbound.conf.tcp-idle-timeout>`
+ when
+ :ref:`edns-tcp-keepalive<unbound.conf.edns-tcp-keepalive>`
+ is enabled.
+ If the client supports the EDNS TCP Keepalive option,
+ If the client supports the EDNS TCP Keepalive option, Unbound sends the
+ timeout value to the client to encourage it to close the connection before
+ the server times out.
+
+ Default: 120000 (2 minutes)
+
+
+@@UAHL@unbound.conf@sock-queue-timeout@@: *<sec>*
+ UDP queries that have waited in the socket buffer for a long time can be
+ dropped.
+ The time is set in seconds, 3 could be a good value to ignore old queries
+ that likely the client does not need a reply for any more.
+ This could happen if the host has not been able to service the queries for
+ a while, i.e. Unbound is not running, and then is enabled again.
+ It uses timestamp socket options.
+
+ Default: 0 (disabled)
+
+
+@@UAHL@unbound.conf@tcp-upstream@@: *<yes or no>*
+ Enable or disable whether the upstream queries use TCP only for transport.
+ Useful in tunneling scenarios.
+ If set to no you can specify TCP transport only for selected forward or
+ stub zones using
+ :ref:`forward-tcp-upstream<unbound.conf.forward.forward-tcp-upstream>` or
+ :ref:`stub-tcp-upstream<unbound.conf.stub.stub-tcp-upstream>`
+ respectively.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@udp-upstream-without-downstream@@: *<yes or no>*
+ Enable UDP upstream even if :ref:`do-udp: no<unbound.conf.do-udp>` is set.
+ Useful for TLS service providers, that want no UDP downstream but use UDP
+ to fetch data upstream.
+
+ Default: no (no changes)
+
+
+@@UAHL@unbound.conf@tls-upstream@@: *<yes or no>*
+ Enabled or disable whether the upstream queries use TLS only for transport.
+ Useful in tunneling scenarios.
+ The TLS contains plain DNS in TCP wireformat.
+ The other server must support this (see
+ :ref:`tls-service-key<unbound.conf.tls-service-key>`).
+
+ If you enable this, also configure a
+ :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>` or use
+ :ref:`tls-win-cert<unbound.conf.tls-win-cert>` or
+ :ref:`tls-system-cert<unbound.conf.tls-system-cert>` to load CA certs,
+ otherwise the connections cannot be authenticated.
+
+ This option enables TLS for all of them, but if you do not set this you can
+ configure TLS specifically for some forward zones with
+ :ref:`forward-tls-upstream<unbound.conf.forward.forward-tls-upstream>`.
+ And also with
+ :ref:`stub-tls-upstream<unbound.conf.stub.stub-tls-upstream>`.
+ If the
+ :ref:`tls-upstream<unbound.conf.tls-upstream>`
+ option is enabled, it is for all the forwards and stubs, where the
+ :ref:`forward-tls-upstream<unbound.conf.forward.forward-tls-upstream>`
+ and
+ :ref:`stub-tls-upstream<unbound.conf.stub.stub-tls-upstream>`
+ options are ignored, as if they had been set to yes.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@ssl-upstream@@: *<yes or no>*
+ Alternate syntax for :ref:`tls-upstream<unbound.conf.tls-upstream>`.
+ If both are present in the config file the last is used.
+
+
+@@UAHL@unbound.conf@tls-service-key@@: *<file>*
+ If enabled, the server provides DNS-over-TLS or DNS-over-HTTPS service on
+ the TCP ports marked implicitly or explicitly for these services with
+ :ref:`tls-port<unbound.conf.tls-port>` or
+ :ref:`https-port<unbound.conf.https-port>`.
+ The file must contain the private key for the TLS session, the public
+ certificate is in the :ref:`tls-service-pem<unbound.conf.tls-service-pem>`
+ file and it must also be specified if
+ :ref:`tls-service-key<unbound.conf.tls-service-key>` is specified.
+ Enabling or disabling this service requires a restart (a reload is not
+ enough), because the key is read while root permissions are held and before
+ chroot (if any).
+ The ports enabled implicitly or explicitly via
+ :ref:`tls-port<unbound.conf.tls-port>` and
+ :ref:`https-port<unbound.conf.https-port>` do not provide normal DNS TCP
+ service.
+
+ .. note::
+ Unbound needs to be compiled with libnghttp2 in order to provide
+ DNS-over-HTTPS.
+
+ Default: "" (disabled)
+
+
+@@UAHL@unbound.conf@ssl-service-key@@: *<file>*
+ Alternate syntax for :ref:`tls-service-key<unbound.conf.tls-service-key>`.
+
+
+@@UAHL@unbound.conf@tls-service-pem@@: *<file>*
+ The public key certificate pem file for the tls service.
+
+ Default: "" (disabled)
+
+
+@@UAHL@unbound.conf@ssl-service-pem@@: *<file>*
+ Alternate syntax for :ref:`tls-service-pem<unbound.conf.tls-service-pem>`.
+
+
+@@UAHL@unbound.conf@tls-port@@: *<number>*
+ The port number on which to provide TCP TLS service.
+ Only interfaces configured with that port number as @number get the TLS
+ service.
+
+ Default: 853
+
+
+@@UAHL@unbound.conf@ssl-port@@: *<number>*
+ Alternate syntax for :ref:`tls-port<unbound.conf.tls-port>`.
+
+
+@@UAHL@unbound.conf@tls-cert-bundle@@: *<file>*
+ If null or ``""``, no file is used.
+ Set it to the certificate bundle file, for example
+ :file:`/etc/pki/tls/certs/ca-bundle.crt`.
+ These certificates are used for authenticating connections made to outside
+ peers.
+ For example :ref:`auth-zone urls<unbound.conf.auth.url>`, and also
+ DNS-over-TLS connections.
+ It is read at start up before permission drop and chroot.
+
+ Default: "" (disabled)
+
+
+@@UAHL@unbound.conf@ssl-cert-bundle@@: *<file>*
+ Alternate syntax for :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>`.
+
+
+@@UAHL@unbound.conf@tls-win-cert@@: *<yes or no>*
+ Add the system certificates to the cert bundle certificates for
+ authentication.
+ If no cert bundle, it uses only these certificates.
+ On windows this option uses the certificates from the cert store.
+ Use the :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>` option on
+ other systems.
+ On other systems, this option enables the system certificates.
+
+ Default: no
+
+
+@@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
+ different name.
+ Because it is not windows specific.
+
+
+@@UAHL@unbound.conf@tls-additional-port@@: *<portnr>*
+ List port numbers as
+ :ref:`tls-additional-port<unbound.conf.tls-additional-port>`, and when
+ interfaces are defined, eg. with the @port suffix, as this port number,
+ they provide DNS-over-TLS service.
+ Can list multiple, each on a new statement.
+
+
+@@UAHL@unbound.conf@tls-session-ticket-keys@@: *<file>*
+ If not ``""``, lists files with 80 bytes of random contents that are used
+ to perform TLS session resumption for clients using the Unbound server.
+ These files contain the secret key for the TLS session tickets.
+ First key use to encrypt and decrypt TLS session tickets.
+ Other keys use to decrypt only.
+
+ With this you can roll over to new keys, by generating a new first file and
+ allowing decrypt of the old file by listing it after the first file for
+ some time, after the wait clients are not using the old key any more and
+ the old key can be removed.
+ One way to create the file is:
+
+ .. code-block:: text
+
+ dd if=/dev/random bs=1 count=80 of=ticket.dat
+
+ The first 16 bytes should be different from the old one if you create a
+ second key, that is the name used to identify the key.
+ Then there is 32 bytes random data for an AES key and then 32 bytes random
+ data for the HMAC key.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf@tls-ciphers@@: *<string with cipher list>*
+ Set the list of ciphers to allow when serving TLS.
+ Use ``""`` for default ciphers.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf@tls-ciphersuites@@: *<string with ciphersuites list>*
+ Set the list of ciphersuites to allow when serving TLS.
+ This is for newer TLS 1.3 connections.
+ Use ``""`` for default ciphersuites.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf@pad-responses@@: *<yes or no>*
+ If enabled, TLS serviced queries that contained an EDNS Padding option will
+ cause responses padded to the closest multiple of the size specified in
+ :ref:`pad-responses-block-size<unbound.conf.pad-responses-block-size>`.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@pad-responses-block-size@@: *<number>*
+ The block size with which to pad responses serviced over TLS.
+ Only responses to padded queries will be padded.
+
+ Default: 468
+
+
+@@UAHL@unbound.conf@pad-queries@@: *<yes or no>*
+ If enabled, all queries sent over TLS upstreams will be padded to the
+ closest multiple of the size specified in
+ :ref:`pad-queries-block-size<unbound.conf.pad-queries-block-size>`.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@pad-queries-block-size@@: *<number>*
+ The block size with which to pad queries sent over TLS upstreams.
+
+ Default: 128
+
+
+@@UAHL@unbound.conf@tls-use-sni@@: *<yes or no>*
+ Enable or disable sending the SNI extension on TLS connections.
+
+ .. note:: Changing the value requires a reload.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@https-port@@: *<number>*
+ The port number on which to provide DNS-over-HTTPS service.
+ Only interfaces configured with that port number as @number get the HTTPS
+ service.
+
+ Default: 443
+
+
+@@UAHL@unbound.conf@http-endpoint@@: *<endpoint string>*
+ The HTTP endpoint to provide DNS-over-HTTPS service on.
+
+ Default: /dns-query
+
+
+@@UAHL@unbound.conf@http-max-streams@@: *<number of streams>*
+ Number used in the SETTINGS_MAX_CONCURRENT_STREAMS parameter in the HTTP/2
+ SETTINGS frame for DNS-over-HTTPS connections.
+
+ Default: 100
+
+
+@@UAHL@unbound.conf@http-query-buffer-size@@: *<size in bytes>*
+ Maximum number of bytes used for all HTTP/2 query buffers combined.
+ These buffers contain (partial) DNS queries waiting for request stream
+ completion.
+ An RST_STREAM frame will be send to streams exceeding this limit.
+ A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+ or gigabytes (1024*1024 bytes in a megabyte).
+
+ Default: 4m
+
+
+@@UAHL@unbound.conf@http-response-buffer-size@@: *<size in bytes>*
+ Maximum number of bytes used for all HTTP/2 response buffers combined.
+ These buffers contain DNS responses waiting to be written back to the
+ clients.
+ An RST_STREAM frame will be send to streams exceeding this limit.
+ A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+ or gigabytes (1024*1024 bytes in a megabyte).
+
+ Default: 4m
+
+
+@@UAHL@unbound.conf@http-nodelay@@: *<yes or no>*
+ Set TCP_NODELAY socket option on sockets used to provide DNS-over-HTTPS
+ service.
+ Ignored if the option is not available.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@http-notls-downstream@@: *<yes or no>*
+ Disable use of TLS for the downstream DNS-over-HTTP connections.
+ Useful for local back end servers.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@proxy-protocol-port@@: *<portnr>*
+ List port numbers as
+ :ref:`proxy-protocol-port<unbound.conf.proxy-protocol-port>`, and when
+ interfaces are defined, eg. with the @port suffix, as this port number,
+ they support and expect PROXYv2.
+
+ In this case the proxy address will only be used for the network
+ communication and initial ACL (check if the proxy itself is denied/refused
+ by configuration).
+
+ The proxied address (if any) will then be used as the true client address
+ and will be used where applicable for logging, ACL, DNSTAP, RPZ and IP
+ ratelimiting.
+
+ PROXYv2 is supported for UDP and TCP/TLS listening interfaces.
+
+ There is no support for PROXYv2 on a DoH, DoQ or DNSCrypt listening interface.
+
+ Can list multiple, each on a new statement.
+
+
+@@UAHL@unbound.conf@quic-port@@: *<number>*
+ The port number on which to provide DNS-over-QUIC service.
+ Only interfaces configured with that port number as @number get the QUIC
+ service.
+ The interface uses QUIC for the UDP traffic on that port number.
+
+ Default: 853
+
+
+@@UAHL@unbound.conf@quic-size@@: *<size in bytes>*
+ Maximum number of bytes for all QUIC buffers and data combined.
+ A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+ or gigabytes (1024*1024 bytes in a megabyte).
+ New connections receive connection refused when the limit is exceeded.
+ New streams are reset when the limit is exceeded.
+
+ Default: 8m
+
+
+@@UAHL@unbound.conf@use-systemd@@: *<yes or no>*
+ Enable or disable systemd socket activation.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@do-daemonize@@: *<yes or no>*
+ Enable or disable whether the Unbound server forks into the background as a
+ daemon.
+ Set the value to no when Unbound runs as systemd service.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@tcp-connection-limit@@: *<IP netblock> <limit>*
+ Allow up to limit simultaneous TCP connections from the given netblock.
+ When at the limit, further connections are accepted but closed immediately.
+ This option is experimental at this time.
+
+ Default: (disabled)
+
+
+@@UAHL@unbound.conf@access-control@@: *<IP netblock> <action>*
+ Specify treatment of incoming queries from their originating IP address.
+ Queries can be allowed to have access to this server that gives DNS
+ answers, or refused, with other actions possible.
+ The IP address range can be specified as a netblock, it is possible to give
+ the statement several times in order to specify the treatment of different
+ netblocks.
+ The netblock is given as an IPv4 or IPv6 address with /size appended for a
+ classless network block.
+ The most specific netblock match is used, if none match
+ :ref:`refuse<unbound.conf.access-control.action.refuse>` is used.
+ The order of the access-control statements therefore does not matter.
+ The action can be
+ :ref:`deny<unbound.conf.access-control.action.deny>`,
+ :ref:`refuse<unbound.conf.access-control.action.refuse>`,
+ :ref:`allow<unbound.conf.access-control.action.allow>`,
+ :ref:`allow_setrd<unbound.conf.access-control.action.allow_setrd>`,
+ :ref:`allow_snoop<unbound.conf.access-control.action.allow_snoop>`,
+ :ref:`allow_cookie<unbound.conf.access-control.action.allow_cookie>`,
+ :ref:`deny_non_local<unbound.conf.access-control.action.deny_non_local>` or
+ :ref:`refuse_non_local<unbound.conf.access-control.action.refuse_non_local>`.
+
+
+ @@UAHL@unbound.conf.access-control.action@deny@@
+ Stops queries from hosts from that netblock.
+
+ @@UAHL@unbound.conf.access-control.action@refuse@@
+ Stops queries too, but sends a DNS rcode REFUSED error message back.
+
+ @@UAHL@unbound.conf.access-control.action@allow@@
+ Gives access to clients from that netblock.
+ It gives only access for recursion clients (which is what almost all
+ clients need).
+ Non-recursive queries are refused.
+
+ The :ref:`allow<unbound.conf.access-control.action.allow>` action does
+ allow non-recursive queries to access the local-data that is
+ configured.
+ The reason is that this does not involve the Unbound server recursive
+ lookup algorithm, and static data is served in the reply.
+ This supports normal operations where non-recursive queries are made
+ for the authoritative data.
+ For non-recursive queries any replies from the dynamic cache are
+ refused.
+
+ @@UAHL@unbound.conf.access-control.action@allow_setrd@@
+ Ignores the recursion desired (RD) bit and treats all requests as if
+ the recursion desired bit is set.
+
+ Note that this behavior violates :rfc:`1034` which states that a name
+ server should never perform recursive service unless asked via the RD
+ bit since this interferes with trouble shooting of name servers and
+ their databases.
+ This prohibited behavior may be useful if another DNS server must
+ forward requests for specific zones to a resolver DNS server, but only
+ supports stub domains and sends queries to the resolver DNS server with
+ the RD bit cleared.
+
+ @@UAHL@unbound.conf.access-control.action@allow_snoop@@
+ Gives non-recursive access too.
+ This gives both recursive and non recursive access.
+ The name *allow_snoop* refers to cache snooping, a technique to use
+ non-recursive queries to examine the cache contents (for malicious
+ acts).
+ However, non-recursive queries can also be a valuable debugging tool
+ (when you want to examine the cache contents).
+
+ In that case use
+ :ref:`allow_snoop<unbound.conf.access-control.action.allow_snoop>` for
+ your administration host.
+
+ @@UAHL@unbound.conf.access-control.action@allow_cookie@@
+ Allows access only to UDP queries that contain a valid DNS Cookie as
+ specified in RFC 7873 and RFC 9018, when the
+ :ref:`answer-cookie<unbound.conf.answer-cookie>` option is enabled.
+ UDP queries containing only a DNS Client Cookie and no Server Cookie,
+ or an invalid DNS Cookie, will receive a BADCOOKIE response including a
+ newly generated DNS Cookie, allowing clients to retry with that DNS
+ Cookie.
+ The *allow_cookie* action will also accept requests over stateful
+ transports, regardless of the presence of an DNS Cookie and regardless
+ of the :ref:`answer-cookie<unbound.conf.answer-cookie>` setting.
+ UDP queries without a DNS Cookie receive REFUSED responses with the TC
+ flag set, that may trigger fall back to TCP for those clients.
+
+ @@UAHL@unbound.conf.access-control.action@deny_non_local@@
+ The
+ :ref:`deny_non_local<unbound.conf.access-control.action.deny_non_local>`
+ action is for hosts that are only allowed to query for the
+ authoritative :ref:`local-data<unbound.conf.local-data>`, they are not
+ allowed full recursion but only the static data.
+ Messages that are disallowed are dropped.
+
+ @@UAHL@unbound.conf.access-control.action@refuse_non_local@@
+ The
+ :ref:`refuse_non_local<unbound.conf.access-control.action.refuse_non_local>`
+ action is for hosts that are only allowed to query for the
+ authoritative :ref:`local-data<unbound.conf.local-data>`, they are not
+ allowed full recursion but only the static data.
+ Messages that are disallowed receive error code REFUSED.
+
+
+ By default only localhost (the 127.0.0.0/8 IP netblock, not the loopback
+ interface) is implicitly *allowed*, the rest is refused.
+ The default is *refused*, because that is protocol-friendly.
+ The DNS protocol is not designed to handle dropped packets due to policy,
+ and dropping may result in (possibly excessive) retried queries.
+
+
+@@UAHL@unbound.conf@access-control-tag@@: *<IP netblock> "<list of tags>"*
+ Assign tags to :ref:`access-control<unbound.conf.access-control>`
+ elements.
+ Clients using this access control element use localzones that are tagged
+ with one of these tags.
+
+ Tags must be defined in :ref:`define-tag<unbound.conf.define-tag>`.
+ Enclose list of tags in quotes (``""``) and put spaces between tags.
+
+ If :ref:`access-control-tag<unbound.conf.access-control-tag>` is
+ configured for a netblock that does not have an
+ :ref:`access-control<unbound.conf.access-control>`, an access-control
+ element with action :ref:`allow<unbound.conf.access-control.action.allow>`
+ is configured for this netblock.
+
+
+@@UAHL@unbound.conf@access-control-tag-action@@: *<IP netblock> <tag> <action>*
+ Set action for particular tag for given access control element.
+ If you have multiple tag values, the tag used to lookup the action is the
+ first tag match between
+ :ref:`access-control-tag<unbound.conf.access-control-tag>` and
+ :ref:`local-zone-tag<unbound.conf.local-zone-tag>` where "first" comes
+ from the order of the :ref:`define-tag<unbound.conf.define-tag>` values.
+
+
+@@UAHL@unbound.conf@access-control-tag-data@@: *<IP netblock> <tag> "<resource record string>"*
+ Set redirect data for particular tag for given access control element.
+
+
+@@UAHL@unbound.conf@access-control-view@@: *<IP netblock> <view name>*
+ Set view for given access control element.
+
+
+@@UAHL@unbound.conf@interface-action@@: *<ip address or interface name [@port]> <action>*
+ Similar to :ref:`access-control<unbound.conf.access-control>` but for
+ interfaces.
+
+ The action is the same as the ones defined under
+ :ref:`access-control<unbound.conf.access-control>`.
+
+ Default action for interfaces is
+ :ref:`refuse<unbound.conf.access-control.action.refuse>`.
+ By default only localhost (the 127.0.0.0/8 IP netblock, not the loopback
+ interface) is implicitly allowed through the default
+ :ref:`access-control<unbound.conf.access-control>` behavior.
+ This also means that any attempt to use the **interface-\*:** options for
+ the loopback interface will not work as they will be overridden by the
+ implicit default "access-control: 127.0.0.0/8 allow" option.
+
+ .. 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.
+
+
+@@UAHL@unbound.conf@interface-tag@@: *<ip address or interface name [@port]> <"list of tags">*
+ Similar to :ref:`access-control-tag<unbound.conf.access-control-tag>` but
+ for interfaces.
+
+ .. 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.
+
+
+@@UAHL@unbound.conf@interface-tag-action@@: *<ip address or interface name [@port]> <tag> <action>*
+ Similar to
+ :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>`
+ but for interfaces.
+
+ .. 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.
+
+
+@@UAHL@unbound.conf@interface-tag-data@@: *<ip address or interface name [@port]> <tag> <"resource record string">*
+ Similar to
+ :ref:`access-control-tag-data<unbound.conf.access-control-tag-data>` but
+ for interfaces.
+
+ .. 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.
+
+
+@@UAHL@unbound.conf@interface-view@@: *<ip address or interface name [@port]> <view name>*
+ Similar to :ref:`access-control-view<unbound.conf.access-control-view>`
+ but for interfaces.
+
+ .. 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.
+
+
+@@UAHL@unbound.conf@chroot@@: *<directory>*
+ If :ref:`chroot<unbound.conf.chroot>` is enabled, you should pass the
+ configfile (from the commandline) as a full path from the original root.
+ After the chroot has been performed the now defunct portion of the config
+ file path is removed to be able to reread the config after a reload.
+
+ All other file paths (working dir, logfile, roothints, and key files) can
+ be specified in several ways: as an absolute path relative to the new root,
+ as a relative path to the working directory, or as an absolute path
+ relative to the original root.
+ In the last case the path is adjusted to remove the unused portion.
+
+ The pidfile can be either a relative path to the working directory, or an
+ absolute path relative to the original root.
+ It is written just prior to chroot and dropping permissions.
+ This allows the pidfile to be :file:`/var/run/unbound.pid` and the chroot
+ to be :file:`/var/unbound`, for example.
+ Note that Unbound is not able to remove the pidfile after termination when
+ it is located outside of the chroot directory.
+
+ Additionally, Unbound may need to access :file:`/dev/urandom` (for entropy)
+ from inside the chroot.
+
+ If given, a *chroot(2)* is done to the given directory.
+ If you give ``""`` no *chroot(2)* is performed.
+
+ Default: @UNBOUND_CHROOT_DIR@
+
+
+@@UAHL@unbound.conf@username@@: *<name>*
+ If given, after binding the port the user privileges are dropped.
+ If you give username: ``""`` no user change is performed.
+
+ If this user is not capable of binding the port, reloads (by signal HUP)
+ will still retain the opened ports.
+ If you change the port number in the config file, and that new port number
+ requires privileges, then a reload will fail; a restart is needed.
+
+ Default: @UNBOUND_USERNAME@
+
+
+@@UAHL@unbound.conf@directory@@: *<directory>*
+ Sets the working directory for the program.
+ On Windows the string "%EXECUTABLE%" tries to change to the directory that
+ :command:`unbound.exe` resides in.
+ If you give a :ref:`server: directory:
+ \<directory\><unbound.conf.directory>` before
+ :ref:`include<unbound.conf.include>` file statements then those includes
+ can be relative to the working directory.
+
+ Default: @UNBOUND_RUN_DIR@
+
+
+@@UAHL@unbound.conf@logfile@@: *<filename>*
+ If ``""`` is given, logging goes to stderr, or nowhere once daemonized.
+ The logfile is appended to, in the following format:
+
+ .. code-block:: text
+
+ [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``.
+
+ The logfile is reopened (for append) when the config file is reread, on
+ SIGHUP.
+
+ Default: "" (disabled)
+
+
+@@UAHL@unbound.conf@use-syslog@@: *<yes or no>*
+ Sets Unbound to send log messages to the syslogd, using *syslog(3)*.
+ The log facility LOG_DAEMON is used, with identity "unbound".
+ The logfile setting is overridden when
+ :ref:`use-syslog: yes<unbound.conf.use-syslog>` is set.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@log-identity@@: *<string>*
+ If ``""`` is given, then the name of the executable, usually
+ "unbound" is used to report to the log.
+ Enter a string to override it with that, which is useful on systems that
+ run more than one instance of Unbound, with different configurations, so
+ that the logs can be easily distinguished against.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf@log-time-ascii@@: *<yes or no>*
+ Sets logfile lines to use a timestamp in UTC ASCII.
+ No effect if using syslog, in that case syslog formats the timestamp
+ printed into the log files.
+
+ Default: no (prints the seconds since 1970 in brackets)
+
+
+@@UAHL@unbound.conf@log-time-iso@@: *<yes or no>*
+ Log time in ISO8601 format, if
+ :ref:`log-time-ascii: yes<unbound.conf.log-time-ascii>`
+ is also set.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@log-queries@@: *<yes or no>*
+ Prints one line per query to the log, with the log timestamp and IP
+ address, name, type and class.
+ Note that it takes time to print these lines which makes the server
+ (significantly) slower.
+ Odd (nonprintable) characters in names are printed as ``'?'``.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@log-replies@@: *<yes or no>*
+ Prints one line per reply to the log, with the log timestamp and IP
+ address, name, type, class, return code, time to resolve, from cache and
+ response size.
+ Note that it takes time to print these lines which makes the server
+ (significantly) slower.
+ Odd (nonprintable) characters in names are printed as ``'?'``.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@log-tag-queryreply@@: *<yes or no>*
+ Prints the word 'query' and 'reply' with
+ :ref:`log-queries<unbound.conf.log-queries>` and
+ :ref:`log-replies<unbound.conf.log-replies>`.
+ This makes filtering logs easier.
+
+ Default: no (backwards compatible)
+
+
+@@UAHL@unbound.conf@log-destaddr@@: *<yes or no>*
+ Prints the destination address, port and type in the
+ :ref:`log-replies<unbound.conf.log-replies>` output.
+ This disambiguates what type of traffic, eg. UDP or TCP, and to what local
+ port the traffic was sent to.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@log-local-actions@@: *<yes or no>*
+ Print log lines to inform about local zone actions.
+ These lines are like the :ref:`local-zone type
+ inform<unbound.conf.local-zone.type.inform>` print outs, but they are also
+ printed for the other types of local zones.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@log-servfail@@: *<yes or no>*
+ Print log lines that say why queries return SERVFAIL to clients.
+ This is separate from the verbosity debug logs, much smaller, and printed
+ at the error level, not the info level of debug info from verbosity.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@pidfile@@: *<filename>*
+ The process id is written to the file.
+ Default is :file:`"@UNBOUND_PIDFILE@"`.
+ So,
+
+ .. code-block:: text
+
+ kill -HUP `cat @UNBOUND_PIDFILE@`
+
+ triggers a reload,
+
+ .. code-block:: text
+
+ kill -TERM `cat @UNBOUND_PIDFILE@`
+
+ gracefully terminates.
+
+ Default: @UNBOUND_PIDFILE@
+
+
+@@UAHL@unbound.conf@root-hints@@: *<filename>*
+ Read the root hints from this file.
+ Default is nothing, using builtin hints for the IN class.
+ The file has the format of zone files, with root nameserver names and
+ addresses only.
+ The default may become outdated, when servers change, therefore it is good
+ practice to use a root hints file.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf@hide-identity@@: *<yes or no>*
+ If enabled 'id.server' and 'hostname.bind' queries are REFUSED.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@identity@@: *<string>*
+ Set the identity to report.
+ If set to ``""``, then the hostname of the server is returned.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf@hide-version@@: *<yes or no>*
+ If enabled 'version.server' and 'version.bind' queries are REFUSED.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@version@@: *<string>*
+ Set the version to report.
+ If set to ``""``, then the package version is returned.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf@hide-http-user-agent@@: *<yes or no>*
+ If enabled the HTTP header User-Agent is not set.
+ Use with caution as some webserver configurations may reject HTTP requests
+ lacking this header.
+ If needed, it is better to explicitly set the
+ :ref:`http-user-agent<unbound.conf.http-user-agent>` below.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@http-user-agent@@: *<string>*
+ Set the HTTP User-Agent header for outgoing HTTP requests.
+ If set to ``""``, then the package name and version are used.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf@nsid@@: *<string>*
+ Add the specified nsid to the EDNS section of the answer when queried with
+ an NSID EDNS enabled packet.
+ As a sequence of hex characters or with 'ascii\_' prefix and then an ASCII
+ string.
+
+ Default: (disabled)
+
+
+@@UAHL@unbound.conf@hide-trustanchor@@: *<yes or no>*
+ If enabled 'trustanchor.unbound' queries are REFUSED.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@target-fetch-policy@@: *<"list of numbers">*
+ Set the target fetch policy used by Unbound to determine if it should fetch
+ nameserver target addresses opportunistically.
+ The policy is described per dependency depth.
+
+ The number of values determines the maximum dependency depth that Unbound
+ will pursue in answering a query.
+ A value of -1 means to fetch all targets opportunistically for that
+ dependency depth.
+ A value of 0 means to fetch on demand only.
+ A positive value fetches that many targets opportunistically.
+
+ Enclose the list between quotes (``""``) and put spaces between numbers.
+ Setting all zeroes, "0 0 0 0 0" gives behaviour closer to that of BIND 9,
+ while setting "-1 -1 -1 -1 -1" gives behaviour rumoured to be closer to
+ that of BIND 8.
+
+ Default: "3 2 1 0 0"
+
+
+@@UAHL@unbound.conf@harden-short-bufsize@@: *<yes or no>*
+ Very small EDNS buffer sizes from queries are ignored.
+
+ Default: yes (as described in the standard)
+
+
+@@UAHL@unbound.conf@harden-large-queries@@: *<yes or no>*
+ Very large queries are ignored.
+ Default is no, since it is legal protocol wise to send these, and could be
+ necessary for operation if TSIG or EDNS payload is very large.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@harden-glue@@: *<yes or no>*
+ Will trust glue only if it is within the servers authority.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@harden-unverified-glue@@: *<yes or no>*
+ Will trust only in-zone glue.
+ Will try to resolve all out of zone (*unverified*) glue.
+ Will fallback to the original glue if unable to resolve.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@harden-dnssec-stripped@@: *<yes or no>*
+ Require DNSSEC data for trust-anchored zones, if such data is absent, the
+ zone becomes bogus.
+ If turned off, and no DNSSEC data is received (or the DNSKEY data fails to
+ validate), then the zone is made insecure, this behaves like there is no
+ trust anchor.
+ You could turn this off if you are sometimes behind an intrusive firewall
+ (of some sort) that removes DNSSEC data from packets, or a zone changes
+ from signed to unsigned to badly signed often.
+ If turned off you run the risk of a downgrade attack that disables security
+ for a zone.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@harden-below-nxdomain@@: *<yes or no>*
+ From :rfc:`8020` (with title "NXDOMAIN: There Really Is Nothing
+ Underneath"), returns NXDOMAIN to queries for a name below another name
+ that is already known to be NXDOMAIN.
+ DNSSEC mandates NOERROR for empty nonterminals, hence this is possible.
+ Very old software might return NXDOMAIN for empty nonterminals (that
+ usually happen for reverse IP address lookups), and thus may be
+ incompatible with this.
+ To try to avoid this only DNSSEC-secure NXDOMAINs are used, because the old
+ software does not have DNSSEC.
+
+ .. note::
+ The NXDOMAIN must be secure, this means NSEC3 with optout is
+ insufficient.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@harden-referral-path@@: *<yes or no>*
+ Harden the referral path by performing additional queries for
+ infrastructure data.
+ Validates the replies if trust anchors are configured and the zones are
+ signed.
+ This enforces DNSSEC validation on nameserver NS sets and the nameserver
+ addresses that are encountered on the referral path to the answer.
+ Default is off, because it burdens the authority servers, and it is not RFC
+ standard, and could lead to performance problems because of the extra query
+ load that is generated.
+ Experimental option.
+ If you enable it consider adding more numbers after the
+ :ref:`target-fetch-policy<unbound.conf.target-fetch-policy>` to increase
+ the max depth that is checked to.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@harden-algo-downgrade@@: *<yes or no>*
+ Harden against algorithm downgrade when multiple algorithms are advertised
+ in the DS record.
+ This works by first choosing only the strongest DS digest type as per
+ :rfc:`4509` (Unbound treats the highest algorithm as the strongest) and
+ then expecting signatures from all the advertised signing algorithms from
+ the chosen DS(es) to be present.
+ If no, allows any one supported algorithm to validate the zone, even if
+ other advertised algorithms are broken.
+ :rfc:`6840` mandates that zone signers must produce zones signed with all
+ advertised algorithms, but sometimes they do not.
+ :rfc:`6840` also clarifies that this requirement is not for validators and
+ validators should accept any single valid path.
+ It should thus be explicitly noted that this option violates :rfc:`6840`
+ for DNSSEC validation and should only be used to perform a signature
+ completeness test to support troubleshooting.
+
+ .. warning::
+ Using this option may break DNSSEC resolution with non :rfc:`6840`
+ conforming signers and/or in multi-signer configurations that don't
+ send all the advertised signatures.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@harden-unknown-additional@@: *<yes or no>*
+ Harden against unknown records in the authority section and additional
+ section.
+ If no, such records are copied from the upstream and presented to the
+ client together with the answer.
+ If yes, it could hamper future protocol developments that want to add
+ records.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@use-caps-for-id@@: *<yes or no>*
+ Use 0x20-encoded random bits in the query to foil spoof attempts.
+ This perturbs the lowercase and uppercase of query names sent to authority
+ servers and checks if the reply still has the correct casing.
+ This feature is an experimental implementation of draft dns-0x20.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@caps-exempt@@: *<domain>*
+ Exempt the domain so that it does not receive caps-for-id perturbed
+ queries.
+ For domains that do not support 0x20 and also fail with fallback because
+ they keep sending different answers, like some load balancers.
+ Can be given multiple times, for different domains.
+
+
+@@UAHL@unbound.conf@caps-whitelist@@: *<domain>*
+ Alternate syntax for :ref:`caps-exempt<unbound.conf.caps-exempt>`.
+
+
+@@UAHL@unbound.conf@qname-minimisation@@: *<yes or no>*
+ Send minimum amount of information to upstream servers to enhance privacy.
+ Only send minimum required labels of the QNAME and set QTYPE to A when
+ possible.
+ Best effort approach; full QNAME and original QTYPE will be sent when
+ upstream replies with a RCODE other than NOERROR, except when receiving
+ NXDOMAIN from a DNSSEC signed zone.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@qname-minimisation-strict@@: *<yes or no>*
+ QNAME minimisation in strict mode.
+ Do not fall-back to sending full QNAME to potentially broken nameservers.
+ A lot of domains will not be resolvable when this option in enabled.
+ Only use if you know what you are doing.
+ This option only has effect when
+ :ref:`qname-minimisation<unbound.conf.qname-minimisation>` is enabled.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@aggressive-nsec@@: *<yes or no>*
+ Aggressive NSEC uses the DNSSEC NSEC chain to synthesize NXDOMAIN and other
+ denials, using information from previous NXDOMAINs answers.
+ It helps to reduce the query rate towards targets that get a very high
+ nonexistent name lookup rate.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@private-address@@: *<IP address or subnet>*
+ Give IPv4 of IPv6 addresses or classless subnets.
+ These are addresses on your private network, and are not allowed to be
+ returned for public internet names.
+ Any occurrence of such addresses are removed from DNS answers.
+ Additionally, the DNSSEC validator may mark the answers bogus.
+ This protects against so-called DNS Rebinding, where a user browser is
+ turned into a network proxy, allowing remote access through the browser to
+ other parts of your private network.
+
+ Some names can be allowed to contain your private addresses, by default all
+ the :ref:`local-data<unbound.conf.local-data>` that you configured is
+ allowed to, and you can specify additional names using
+ :ref:`private-domain<unbound.conf.private-domain>`.
+ No private addresses are enabled by default.
+
+ We consider to enable this for the :rfc:`1918` private IP address space by
+ default in later releases.
+ That would enable private addresses for ``10.0.0.0/8``, ``172.16.0.0/12``,
+ ``192.168.0.0/16``, ``169.254.0.0/16``, ``fd00::/8`` and ``fe80::/10``,
+ since the RFC standards say these addresses should not be visible on the
+ public internet.
+
+ Turning on ``127.0.0.0/8`` would hinder many spamblocklists as they use
+ that.
+ Adding ``::ffff:0:0/96`` stops IPv4-mapped IPv6 addresses from bypassing
+ the filter.
+
+
+@@UAHL@unbound.conf@private-domain@@: *<domain name>*
+ Allow this domain, and all its subdomains to contain private addresses.
+ Give multiple times to allow multiple domain names to contain private
+ addresses.
+
+ Default: (none)
+
+
+@@UAHL@unbound.conf@unwanted-reply-threshold@@: *<number>*
+ If set, a total number of unwanted replies is kept track of in every
+ thread.
+ When it reaches the threshold, a defensive action is taken and a warning is
+ printed to the log.
+ The defensive action is to clear the rrset and message caches, hopefully
+ flushing away any poison.
+ A value of 10 million is suggested.
+
+ Default: 0 (disabled)
+
+
+@@UAHL@unbound.conf@do-not-query-address@@: *<IP address>*
+ Do not query the given IP address.
+ Can be IPv4 or IPv6.
+ Append /num to indicate a classless delegation netblock, for example like
+ ``10.2.3.4/24`` or ``2001::11/64``.
+
+ Default: (none)
+
+
+@@UAHL@unbound.conf@do-not-query-localhost@@: *<yes or no>*
+ If yes, localhost is added to the
+ :ref:`do-not-query-address<unbound.conf.do-not-query-address>` entries,
+ both IPv6 ``::1`` and IPv4 ``127.0.0.1/8``.
+ If no, then localhost can be used to send queries to.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@prefetch@@: *<yes or no>*
+ If yes, cache hits on message cache elements that are on their last 10
+ percent of their TTL value trigger a prefetch to keep the cache up to date.
+ Turning it on gives about 10 percent more traffic and load on the machine,
+ but popular items do not expire from the cache.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@prefetch-key@@: *<yes or no>*
+ If yes, fetch the DNSKEYs earlier in the validation process, when a DS
+ record is encountered.
+ This lowers the latency of requests.
+ It does use a little more CPU.
+ Also if the cache is set to 0, it is no use.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@deny-any@@: *<yes or no>*
+ If yes, deny queries of type ANY with an empty response.
+ If disabled, Unbound responds with a short list of resource records if some
+ can be found in the cache and makes the upstream type ANY query if there
+ are none.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@rrset-roundrobin@@: *<yes or no>*
+ If yes, Unbound rotates RRSet order in response (the random number is taken
+ from the query ID, for speed and thread safety).
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@minimal-responses@@: *<yes or no>*
+ If yes, Unbound does not insert authority/additional sections into response
+ messages when those sections are not required.
+ This reduces response size significantly, and may avoid TCP fallback for
+ some responses which may cause a slight speedup.
+ The default is yes, even though the DNS protocol RFCs mandate these
+ sections, and the additional content could save roundtrips for clients that
+ use the additional content.
+ However these sections are hardly used by clients.
+ Enabling prefetch can benefit clients that need the additional content
+ by trying to keep that content fresh in the cache.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@disable-dnssec-lame-check@@: *<yes or no>*
+ If true, disables the DNSSEC lameness check in the iterator.
+ This check sees if RRSIGs are present in the answer, when dnssec is
+ expected, and retries another authority if RRSIGs are unexpectedly missing.
+ The validator will insist in RRSIGs for DNSSEC signed domains regardless of
+ this setting, if a trust anchor is loaded.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@module-config@@: *"<module names>"*
+ Module configuration, a list of module names separated by spaces, surround
+ the string with quotes (``""``).
+ The modules can be ``respip``, ``validator``, or ``iterator`` (and possibly
+ more, see below).
+
+ .. note::
+ The ordering of the modules is significant, the order decides the order
+ of processing.
+
+ Setting this to just "iterator" will result in a non-validating server.
+ Setting this to "validator iterator" will turn on DNSSEC validation.
+
+ .. note::
+ You must also set trust-anchors for validation to be useful.
+
+ Adding ``respip`` to the front will cause RPZ processing to be done on all
+ queries.
+
+ Most modules that need to be listed here have to be listed at the beginning
+ of the line.
+
+ The ``subnetcache`` module has to be listed just before the iterator.
+
+ The ``python`` module can be listed in different places, it then processes
+ the output of the module it is just before.
+
+ The ``dynlib`` module can be listed pretty much anywhere, it is only a very
+ thin wrapper that allows dynamic libraries to run in its place.
+
+ Default: "validator iterator"
+
+
+@@UAHL@unbound.conf@trust-anchor-file@@: *<filename>*
+ File with trusted keys for validation.
+ Both DS and DNSKEY entries can appear in the file.
+ The format of the file is the standard DNS Zone file format.
+
+ Default: "" (no trust anchor file)
+
+
+@@UAHL@unbound.conf@auto-trust-anchor-file@@: *<filename>*
+ File with trust anchor for one zone, which is tracked with :rfc:`5011`
+ probes.
+ The probes are run several times per month, thus the machine must be online
+ frequently.
+ The initial file can be one with contents as described in
+ :ref:`trust-anchor-file<unbound.conf.trust-anchor-file>`.
+ The file is written to when the anchor is updated, so the Unbound user must
+ have write permission.
+ Write permission to the file, but also to the directory it is in (to create
+ a temporary file, which is necessary to deal with filesystem full events),
+ it must also be inside the :ref:`chroot<unbound.conf.chroot>` (if that is
+ used).
+
+ Default: "" (no auto trust anchor file)
+
+
+@@UAHL@unbound.conf@trust-anchor@@: *"<Resource Record>"*
+ A DS or DNSKEY RR for a key to use for validation.
+ Multiple entries can be given to specify multiple trusted keys, in addition
+ to the :ref:`trust-anchor-file<unbound.conf.trust-anchor-file>`.
+ The resource record is entered in the same format as *dig(1)* or *drill(1)*
+ prints them, the same format as in the zone file.
+ Has to be on a single line, with ``""`` around it.
+ A TTL can be specified for ease of cut and paste, but is ignored.
+ A class can be specified, but class IN is default.
+
+ Default: (none)
+
+
+@@UAHL@unbound.conf@trusted-keys-file@@: *<filename>*
+ File with trusted keys for validation.
+ Specify more than one file with several entries, one file per entry.
+ Like :ref:`trust-anchor-file<unbound.conf.trust-anchor-file>` but has a
+ different file format.
+ Format is BIND-9 style format, the ``trusted-keys { name flag proto algo
+ "key"; };`` clauses are read.
+ It is possible to use wildcards with this statement, the wildcard is
+ expanded on start and on reload.
+
+ Default: "" (no trusted keys file)
+
+
+@@UAHL@unbound.conf@trust-anchor-signaling@@: *<yes or no>*
+ Send :rfc:`8145` key tag query after trust anchor priming.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@root-key-sentinel@@: *<yes or no>*
+ Root key trust anchor sentinel.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@domain-insecure@@: *<domain name>*
+ Sets *<domain name>* to be insecure, DNSSEC chain of trust is ignored
+ towards the *<domain name>*.
+ So a trust anchor above the domain name can not make the domain secure with
+ a DS record, such a DS record is then ignored.
+ Can be given multiple times to specify multiple domains that are treated as
+ if unsigned.
+ If you set trust anchors for the domain they override this setting (and the
+ domain is secured).
+
+ This can be useful if you want to make sure a trust anchor for external
+ lookups does not affect an (unsigned) internal domain.
+ A DS record externally can create validation failures for that internal
+ domain.
+
+ Default: (none)
+
+
+@@UAHL@unbound.conf@val-override-date@@: *<rrsig-style date spec>*
+ .. warning:: Debugging feature!
+
+ If enabled by giving a RRSIG style date, that date is used for verifying
+ RRSIG inception and expiration dates, instead of the current date.
+ Do not set this unless you are debugging signature inception and
+ expiration.
+ The value -1 ignores the date altogether, useful for some special
+ applications.
+
+ Default: 0 (disabled)
+
+
+@@UAHL@unbound.conf@val-sig-skew-min@@: *<seconds>*
+ Minimum number of seconds of clock skew to apply to validated signatures.
+ A value of 10% of the signature lifetime (expiration - inception) is used,
+ capped by this setting.
+ Default is 3600 (1 hour) which allows for daylight savings differences.
+ Lower this value for more strict checking of short lived signatures.
+
+ Default: 3600 (1 hour)
+
+
+@@UAHL@unbound.conf@val-sig-skew-max@@: *<seconds>*
+ Maximum number of seconds of clock skew to apply to validated signatures.
+ A value of 10% of the signature lifetime (expiration - inception) is used,
+ capped by this setting.
+ Default is 86400 (24 hours) which allows for timezone setting problems in
+ stable domains.
+ Setting both min and max very low disables the clock skew allowances.
+ Setting both min and max very high makes the validator check the signature
+ timestamps less strictly.
+
+ Default: 86400 (24 hours)
+
+
+@@UAHL@unbound.conf@val-max-restart@@: *<number>*
+ The maximum number the validator should restart validation with another
+ authority in case of failed validation.
+
+ Default: 5
+
+
+@@UAHL@unbound.conf@val-bogus-ttl@@: *<seconds>*
+ The time to live for bogus data.
+ This is data that has failed validation; due to invalid signatures or other
+ checks.
+ The TTL from that data cannot be trusted, and this value is used instead.
+ The time interval prevents repeated revalidation of bogus data.
+
+ Default: 60
+
+
+@@UAHL@unbound.conf@val-clean-additional@@: *<yes or no>*
+ Instruct the validator to remove data from the additional section of secure
+ messages that are not signed properly.
+ Messages that are insecure, bogus, indeterminate or unchecked are not
+ affected.
+ Use this setting to protect the users that rely on this validator for
+ authentication from potentially bad data in the additional section.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@val-log-level@@: *<number>*
+ Have the validator print validation failures to the log.
+ Regardless of the verbosity setting.
+
+ At 1, for every user query that fails a line is printed to the logs.
+ This way you can monitor what happens with validation.
+ Use a diagnosis tool, such as dig or drill, to find out why validation is
+ failing for these queries.
+
+ At 2, not only the query that failed is printed but also the reason why
+ Unbound thought it was wrong and which server sent the faulty data.
+
+ Default: 0 (disabled)
+
+
+@@UAHL@unbound.conf@val-permissive-mode@@: *<yes or no>*
+ Instruct the validator to mark bogus messages as indeterminate.
+ The security checks are performed, but if the result is bogus (failed
+ security), the reply is not withheld from the client with SERVFAIL as
+ usual.
+ The client receives the bogus data.
+ For messages that are found to be secure the AD bit is set in replies.
+ Also logging is performed as for full validation.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@ignore-cd-flag@@: *<yes or no>*
+ Instruct Unbound to ignore the CD flag from clients and refuse to return
+ bogus answers to them.
+ Thus, the CD (Checking Disabled) flag does not disable checking any more.
+ This is useful if legacy (w2008) servers that set the CD flag but cannot
+ validate DNSSEC themselves are the clients, and then Unbound provides them
+ with DNSSEC protection.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@disable-edns-do@@: *<yes or no>*
+ Disable the EDNS DO flag in upstream requests.
+ It breaks DNSSEC validation for Unbound's clients.
+ This results in the upstream name servers to not include DNSSEC records in
+ their replies and could be helpful for devices that cannot handle DNSSEC
+ information.
+ When the option is enabled, clients that set the DO flag receive no EDNS
+ record in the response to indicate the lack of support to them.
+ If this option is enabled but Unbound is already configured for DNSSEC
+ validation (i.e., the validator module is enabled; default) this option is
+ implicitly turned off with a warning as to not break DNSSEC validation in
+ Unbound.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@serve-expired@@: *<yes or no>*
+ If enabled, Unbound attempts to serve old responses from cache with a TTL
+ of :ref:`serve-expired-reply-ttl<unbound.conf.serve-expired-reply-ttl>` in
+ the response.
+ By default the expired answer will be used after a resolution attempt
+ errored out or is taking more than
+ :ref:`serve-expired-client-timeout<unbound.conf.serve-expired-client-timeout>`
+ to resolve.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@serve-expired-ttl@@: *<seconds>*
+ Limit serving of expired responses to configured seconds after expiration.
+ ``0`` disables the limit.
+ This option only applies when
+ :ref:`serve-expired<unbound.conf.serve-expired>` is enabled.
+ A suggested value per RFC 8767 is between 86400 (1 day) and 259200 (3 days).
+ The default is 86400.
+
+ Default: 86400
+
+
+@@UAHL@unbound.conf@serve-expired-ttl-reset@@: *<yes or no>*
+ Set the TTL of expired records to the
+ :ref:`serve-expired-ttl<unbound.conf.serve-expired-ttl>` value after a
+ failed attempt to retrieve the record from upstream.
+ This makes sure that the expired records will be served as long as there
+ are queries for it.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@serve-expired-reply-ttl@@: *<seconds>*
+ TTL value to use when replying with expired data.
+ If
+ :ref:`serve-expired-client-timeout<unbound.conf.serve-expired-client-timeout>`
+ is also used then it is RECOMMENDED to use 30 as the value (:rfc:`8767`).
+
+ Default: 30
+
+
+@@UAHL@unbound.conf@serve-expired-client-timeout@@: *<msec>*
+ Time in milliseconds before replying to the client with expired data.
+ This essentially enables the serve-stale behavior as specified in
+ :rfc:`8767` that first tries to resolve before immediately responding with
+ expired data.
+ Setting this to ``0`` will disable this behavior and instead serve the
+ expired record immediately from the cache before attempting to refresh it
+ via resolution.
+
+ Default: 1800
+
+
+@@UAHL@unbound.conf@serve-original-ttl@@: *<yes or no>*
+ If enabled, Unbound will always return the original TTL as received from
+ the upstream name server rather than the decrementing TTL as stored in the
+ cache.
+ This feature may be useful if Unbound serves as a front-end to a hidden
+ authoritative name server.
+
+ Enabling this feature does not impact cache expiry, it only changes the TTL
+ Unbound embeds in responses to queries.
+
+ .. note::
+ Enabling this feature implicitly disables enforcement of the configured
+ minimum and maximum TTL, as it is assumed users who enable this feature
+ do not want Unbound to change the TTL obtained from an upstream server.
+
+ .. note::
+ The values set using :ref:`cache-min-ttl<unbound.conf.cache-min-ttl>`
+ and :ref:`cache-max-ttl<unbound.conf.cache-max-ttl>` are ignored.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@val-nsec3-keysize-iterations@@: <"list of values">
+ List of keysize and iteration count values, separated by spaces, surrounded
+ by quotes.
+ This determines the maximum allowed NSEC3 iteration count before a message
+ is simply marked insecure instead of performing the many hashing
+ iterations.
+ The list must be in ascending order and have at least one entry.
+ If you set it to "1024 65535" there is no restriction to NSEC3 iteration
+ values.
+
+ .. note::
+ This table must be kept short; a very long list could cause slower
+ operation.
+
+ Default: "1024 150 2048 150 4096 150"
+
+
+@@UAHL@unbound.conf@zonemd-permissive-mode@@: *<yes or no>*
+ If enabled the ZONEMD verification failures are only logged and do not
+ cause the zone to be blocked and only return servfail.
+ Useful for testing out if it works, or if the operator only wants to be
+ notified of a problem without disrupting service.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@add-holddown@@: *<seconds>*
+ Instruct the
+ :ref:`auto-trust-anchor-file<unbound.conf.auto-trust-anchor-file>` probe
+ mechanism for :rfc:`5011` autotrust updates to add new trust anchors only
+ after they have been visible for this time.
+
+ Default: 2592000 (30 days as per the RFC)
+
+
+@@UAHL@unbound.conf@del-holddown@@: *<seconds>*
+ Instruct the
+ :ref:`auto-trust-anchor-file<unbound.conf.auto-trust-anchor-file>` probe
+ mechanism for :rfc:`5011` autotrust updates to remove revoked trust anchors
+ after they have been kept in the revoked list for this long.
+
+ Default: 2592000 (30 days as per the RFC)
+
+
+@@UAHL@unbound.conf@keep-missing@@: *<seconds>*
+ Instruct the
+ :ref:`auto-trust-anchor-file<unbound.conf.auto-trust-anchor-file>` probe
+ mechanism for :rfc:`5011` autotrust updates to remove missing trust anchors
+ after they have been unseen for this long.
+ This cleans up the state file if the target zone does not perform trust
+ anchor revocation, so this makes the auto probe mechanism work with zones
+ that perform regular (non-5011) rollovers.
+ The value 0 does not remove missing anchors, as per the RFC.
+
+ Default: 31622400 (366 days)
+
+
+@@UAHL@unbound.conf@permit-small-holddown@@: *<yes or no>*
+ Debug option that allows the autotrust 5011 rollover timers to assume very
+ small values.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@key-cache-size@@: *<number>*
+ Number of bytes size of the key cache.
+ A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+ or gigabytes (1024*1024 bytes in a megabyte).
+
+ Default: 4m
+
+
+@@UAHL@unbound.conf@key-cache-slabs@@: *<number>*
+ Number of slabs in the key cache.
+ Slabs reduce lock contention by threads.
+ Must be set to a power of 2.
+ Setting (close) to the number of cpus is a fairly good setting.
+ If left unconfigured, it will be configured automatically to be a power of
+ 2 close to the number of configured threads in multi-threaded environments.
+
+ Default: (unconfigured)
+
+
+@@UAHL@unbound.conf@neg-cache-size@@: *<number>*
+ Number of bytes size of the aggressive negative cache.
+ A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
+ or gigabytes (1024*1024 bytes in a megabyte).
+
+ Default: 1m
+
+
+@@UAHL@unbound.conf@unblock-lan-zones@@: *<yes or no>*
+ If enabled, then for private address space, the reverse lookups are no
+ longer filtered.
+ This allows Unbound when running as dns service on a host where it provides
+ service for that host, to put out all of the queries for the 'lan'
+ upstream.
+ When enabled, only localhost, ``127.0.0.1`` reverse and ``::1`` reverse
+ zones are configured with default local zones.
+ Disable the option when Unbound is running as a (DHCP-) DNS network
+ resolver for a group of machines, where such lookups should be filtered
+ (RFC compliance), this also stops potential data leakage about the local
+ network to the upstream DNS servers.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@insecure-lan-zones@@: *<yes or no>*
+ If enabled, then reverse lookups in private address space are not
+ validated.
+ This is usually required whenever
+ :ref:`unblock-lan-zones<unbound.conf.unblock-lan-zones>` is used.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@local-zone@@: *<zone> <type>*
+ Configure a local zone.
+ The type determines the answer to give if there is no match from
+ :ref:`local-data<unbound.conf.local-data>`.
+ The types are
+ :ref:`deny<unbound.conf.local-zone.type.deny>`,
+ :ref:`refuse<unbound.conf.local-zone.type.refuse>`,
+ :ref:`static<unbound.conf.local-zone.type.static>`,
+ :ref:`transparent<unbound.conf.local-zone.type.transparent>`,
+ :ref:`redirect<unbound.conf.local-zone.type.redirect>`,
+ :ref:`nodefault<unbound.conf.local-zone.type.nodefault>`,
+ :ref:`typetransparent<unbound.conf.local-zone.type.typetransparent>`,
+ :ref:`inform<unbound.conf.local-zone.type.inform>`,
+ :ref:`inform_deny<unbound.conf.local-zone.type.inform_deny>`,
+ :ref:`inform_redirect<unbound.conf.local-zone.type.inform_redirect>`,
+ :ref:`always_transparent<unbound.conf.local-zone.type.always_transparent>`,
+ :ref:`block_a<unbound.conf.local-zone.type.block_a>`,
+ :ref:`always_refuse<unbound.conf.local-zone.type.always_refuse>`,
+ :ref:`always_nxdomain<unbound.conf.local-zone.type.always_nxdomain>`,
+ :ref:`always_null<unbound.conf.local-zone.type.always_null>`,
+ :ref:`noview<unbound.conf.local-zone.type.noview>`,
+ and are explained below.
+ After that the default settings are listed.
+ Use :ref:`local-data<unbound.conf.local-data>` to enter data into the
+ local zone.
+ Answers for local zones are authoritative DNS answers.
+ By default the zones are class IN.
+
+ If you need more complicated authoritative data, with referrals,
+ wildcards, CNAME/DNAME support, or DNSSEC authoritative service,
+ setup a :ref:`stub-zone<unbound.conf.stub>` for it as detailed in the
+ stub zone section below.
+ A :ref:`stub-zone<unbound.conf.stub>` can be used to have unbound
+ send queries to another server, an authoritative server, to fetch the
+ information.
+ With a :ref:`forward-zone<unbound.conf.forward>`, unbound sends
+ queries to a server that is a recursive server to fetch the information.
+ With an :ref:`auth-zone<unbound.conf.auth>` a zone can be loaded from
+ file and used, it can be used like a local zone for users downstream, or
+ the :ref:`auth-zone<unbound.conf.auth>` information can be used to fetch
+ information from when resolving like it is an upstream server.
+ The :ref:`forward-zone<unbound.conf.forward>` and
+ :ref:`auth-zone<unbound.conf.auth>` options are described in their
+ sections below.
+ If you want to perform filtering of the information that the users can
+ fetch, the :ref:`local-zone<unbound.conf.local-zone>` and
+ :ref:`local-data<unbound.conf.local-data>` statements allow for this, but
+ also the :ref:`rpz<unbound.conf.rpz>` functionality can be used, described
+ in the RPZ section.
+
+ @@UAHL@unbound.conf.local-zone.type@deny@@
+ Do not send an answer, drop the query.
+ If there is a match from local data, the query is answered.
+
+ @@UAHL@unbound.conf.local-zone.type@refuse@@
+ Send an error message reply, with rcode REFUSED.
+ If there is a match from local data, the query is answered.
+
+ @@UAHL@unbound.conf.local-zone.type@static@@
+ If there is a match from local data, the query is answered.
+ Otherwise, the query is answered with NODATA or NXDOMAIN.
+ For a negative answer a SOA is included in the answer if present as
+ :ref:`local-data<unbound.conf.local-data>` for the zone apex domain.
+
+ @@UAHL@unbound.conf.local-zone.type@transparent@@
+ If there is a match from :ref:`local-data<unbound.conf.local-data>`,
+ the query is answered.
+ Otherwise if the query has a different name, the query is resolved
+ normally.
+ If the query is for a name given in
+ :ref:`local-data<unbound.conf.local-data>` but no such type of data is
+ given in localdata, then a NOERROR NODATA answer is returned.
+ If no :ref:`local-zone<unbound.conf.local-zone>` is given
+ :ref:`local-data<unbound.conf.local-data>` causes a transparent zone
+ to be created by default.
+
+ @@UAHL@unbound.conf.local-zone.type@typetransparent@@
+ If there is a match from local data, the query is answered.
+ If the query is for a different name, or for the same name but for a
+ different type, the query is resolved normally.
+ So, similar to
+ :ref:`transparent<unbound.conf.local-zone.type.transparent>` but types
+ that are not listed in local data are resolved normally, so if an A
+ record is in the local data that does not cause a NODATA reply for AAAA
+ queries.
+
+ @@UAHL@unbound.conf.local-zone.type@redirect@@
+ The query is answered from the local data for the zone name.
+ There may be no local data beneath the zone name.
+ This answers queries for the zone, and all subdomains of the zone with
+ the local data for the zone.
+ It can be used to redirect a domain to return a different address
+ record to the end user, with:
+
+ .. code-block:: text
+
+ local-zone: "example.com." redirect
+ local-data: "example.com. A 127.0.0.1"
+
+ queries for ``www.example.com`` and ``www.foo.example.com`` are
+ redirected, so that users with web browsers cannot access sites with
+ suffix example.com.
+
+ @@UAHL@unbound.conf.local-zone.type@inform@@
+ The query is answered normally, same as
+ :ref:`transparent<unbound.conf.local-zone.type.transparent>`.
+ The client IP address (@portnumber) is printed to the logfile.
+ The log message is:
+
+ .. code-block:: text
+
+ timestamp, unbound-pid, info: zonename inform IP@port queryname type class.
+
+ This option can be used for normal resolution, but machines looking up
+ infected names are logged, eg. to run antivirus on them.
+
+ @@UAHL@unbound.conf.local-zone.type@inform_deny@@
+ The query is dropped, like
+ :ref:`deny<unbound.conf.local-zone.type.deny>`, and logged, like
+ :ref:`inform<unbound.conf.local-zone.type.inform>`.
+ Ie. find infected machines without answering the queries.
+
+ @@UAHL@unbound.conf.local-zone.type@inform_redirect@@
+ The query is redirected, like
+ :ref:`redirect<unbound.conf.local-zone.type.redirect>`, and logged,
+ like :ref:`inform<unbound.conf.local-zone.type.inform>`.
+ Ie. answer queries with fixed data and also log the machines that ask.
+
+ @@UAHL@unbound.conf.local-zone.type@always_transparent@@
+ Like :ref:`transparent<unbound.conf.local-zone.type.transparent>`, but
+ ignores local data and resolves normally.
+
+ @@UAHL@unbound.conf.local-zone.type@block_a@@
+ Like :ref:`transparent<unbound.conf.local-zone.type.transparent>`, but
+ ignores local data and resolves normally all query types excluding A.
+ For A queries it unconditionally returns NODATA.
+ Useful in cases when there is a need to explicitly force all apps to
+ use IPv6 protocol and avoid any queries to IPv4.
+
+ @@UAHL@unbound.conf.local-zone.type@always_refuse@@
+ Like :ref:`refuse<unbound.conf.local-zone.type.refuse>`, but ignores
+ local data and refuses the query.
+
+ @@UAHL@unbound.conf.local-zone.type@always_nxdomain@@
+ Like :ref:`static<unbound.conf.local-zone.type.static>`, but ignores
+ local data and returns NXDOMAIN for the query.
+
+ @@UAHL@unbound.conf.local-zone.type@always_nodata@@
+ Like :ref:`static<unbound.conf.local-zone.type.static>`, but ignores
+ local data and returns NODATA for the query.
+
+ @@UAHL@unbound.conf.local-zone.type@always_deny@@
+ Like :ref:`deny<unbound.conf.local-zone.type.deny>`, but ignores local
+ data and drops the query.
+
+ @@UAHL@unbound.conf.local-zone.type@always_null@@
+ Always returns ``0.0.0.0`` or ``::0`` for every name in the zone.
+ Like :ref:`redirect<unbound.conf.local-zone.type.redirect>` with zero
+ data for A and AAAA.
+ Ignores local data in the zone.
+ Used for some block lists.
+
+ @@UAHL@unbound.conf.local-zone.type@noview@@
+ Breaks out of that view and moves towards the global local zones for
+ answer to the query.
+ If the :ref:`view-first<unbound.conf.view.view-first>` is no, it'll
+ resolve normally.
+ If :ref:`view-first<unbound.conf.view.view-first>` is enabled, it'll
+ break perform that step and check the global answers.
+ For when the view has view specific overrides but some zone has to be
+ answered from global local zone contents.
+
+ @@UAHL@unbound.conf.local-zone.type@nodefault@@
+ Used to turn off default contents for AS112 zones.
+ The other types also turn off default contents for the zone.
+ The :ref:`nodefault<unbound.conf.local-zone.type.nodefault>` option has
+ no other effect than turning off default contents for the given zone.
+ Use :ref:`nodefault<unbound.conf.local-zone.type.nodefault>` if you use
+ exactly that zone, if you want to use a subzone, use
+ :ref:`transparent<unbound.conf.local-zone.type.transparent>`.
+
+ The default zones are localhost, reverse ``127.0.0.1`` and ``::1``, the
+ ``home.arpa``, ``resolver.arpa``, ``service.arpa``, ``onion``, ``test``,
+ ``invalid`` and the AS112 zones.
+ The AS112 zones are reverse DNS zones for private use and reserved IP
+ addresses for which the servers on the internet cannot provide correct
+ answers.
+ They are configured by default to give NXDOMAIN (no reverse information)
+ answers.
+
+ The defaults can be turned off by specifying your own
+ :ref:`local-zone<unbound.conf.local-zone>` of that name, or using the
+ :ref:`nodefault<unbound.conf.local-zone.type.nodefault>` type.
+ Below is a list of the default zone contents.
+
+ @@UAHL@unbound.conf.local-zone.defaults@localhost@@
+ The IPv4 and IPv6 localhost information is given.
+ NS and SOA records are provided for completeness and to satisfy some
+ DNS update tools.
+ Default content:
+
+ .. code-block:: text
+
+ local-zone: "localhost." redirect
+ local-data: "localhost. 10800 IN NS localhost."
+ local-data: "localhost. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+ local-data: "localhost. 10800 IN A 127.0.0.1"
+ local-data: "localhost. 10800 IN AAAA ::1"
+
+ @@UAHL@unbound.conf.local-zone.defaults@reverse IPv4 loopback@@
+ Default content:
+
+ .. code-block:: text
+
+ local-zone: "127.in-addr.arpa." static
+ local-data: "127.in-addr.arpa. 10800 IN NS localhost."
+ local-data: "127.in-addr.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+ local-data: "1.0.0.127.in-addr.arpa. 10800 IN PTR localhost."
+
+ @@UAHL@unbound.conf.local-zone.defaults@reverse IPv6 loopback@@
+ Default content:
+
+ .. code-block:: text
+
+ local-zone: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." static
+ local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN NS localhost."
+ local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+ local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN PTR localhost."
+
+ @@UAHL@unbound.conf.local-zone.defaults@home.arpa@@ (:rfc:`8375`)
+ Default content:
+
+ .. code-block:: text
+
+ local-zone: "home.arpa." static
+ local-data: "home.arpa. 10800 IN NS localhost."
+ local-data: "home.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+
+ @@UAHL@unbound.conf.local-zone.defaults@resolver.arpa@@ (:rfc:`9462`)
+ Default content:
+
+ .. code-block:: text
+
+ local-zone: "resolver.arpa." static
+ local-data: "resolver.arpa. 10800 IN NS localhost."
+ local-data: "resolver.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+
+ @@UAHL@unbound.conf.local-zone.defaults@service.arpa@@ (draft-ietf-dnssd-srp-25)
+ Default content:
+
+ .. code-block:: text
+
+ local-zone: "service.arpa." static
+ local-data: "service.arpa. 10800 IN NS localhost."
+ local-data: "service.arpa. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+
+ @@UAHL@unbound.conf.local-zone.defaults@onion@@ (:rfc:`7686`)
+ Default content:
+
+ .. code-block:: text
+
+ local-zone: "onion." static
+ local-data: "onion. 10800 IN NS localhost."
+ local-data: "onion. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+
+ @@UAHL@unbound.conf.local-zone.defaults@test@@ (:rfc:`6761`)
+ Default content:
+
+ .. code-block:: text
+
+ local-zone: "test." static
+ local-data: "test. 10800 IN NS localhost."
+ local-data: "test. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+
+ @@UAHL@unbound.conf.local-zone.defaults@invalid@@ (:rfc:`6761`)
+ Default content:
+
+ .. code-block:: text
+
+ local-zone: "invalid." static
+ local-data: "invalid. 10800 IN NS localhost."
+ local-data: "invalid. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
+
+ @@UAHL@unbound.conf.local-zone.defaults@reverse local use zones@@ (:rfc:`1918`)
+ Reverse data for zones ``10.in-addr.arpa``, ``16.172.in-addr.arpa`` to
+ ``31.172.in-addr.arpa``, ``168.192.in-addr.arpa``.
+ The :ref:`local-zone<unbound.conf.local-zone>` is set static and as
+ :ref:`local-data<unbound.conf.local-data>` SOA and NS records are
+ provided.
+
+ @@UAHL@unbound.conf.local-zone.defaults@special-use IPv4 Addresses@@ (:rfc:`3330`)
+ Reverse data for zones ``0.in-addr.arpa`` (this), ``254.169.in-addr.arpa`` (link-local),
+ ``2.0.192.in-addr.arpa`` (TEST NET 1), ``100.51.198.in-addr.arpa``
+ (TEST NET 2), ``113.0.203.in-addr.arpa`` (TEST NET 3),
+ ``255.255.255.255.in-addr.arpa`` (broadcast).
+ And from ``64.100.in-addr.arpa`` to ``127.100.in-addr.arpa`` (Shared
+ Address Space).
+
+ @@UAHL@unbound.conf.local-zone.defaults@reverse IPv6 unspecified@@ (:rfc:`4291`)
+ Reverse data for zone
+ ``0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa.``
+
+ @@UAHL@unbound.conf.local-zone.defaults@reverse IPv6 Locally Assigned Local Addresses@@ (:rfc:`4193`)
+ Reverse data for zone ``D.F.ip6.arpa``.
+
+ @@UAHL@unbound.conf.local-zone.defaults@reverse IPv6 Link Local Addresses@@ (:rfc:`4291`)
+ Reverse data for zones ``8.E.F.ip6.arpa`` to ``B.E.F.ip6.arpa``.
+
+ @@UAHL@unbound.conf.local-zone.defaults@reverse IPv6 Example Prefix@@
+ Reverse data for zone ``8.B.D.0.1.0.0.2.ip6.arpa``.
+ This zone is used for tutorials and examples.
+ You can remove the block on this zone with:
+
+ .. code-block:: text
+
+ local-zone: 8.B.D.0.1.0.0.2.ip6.arpa. nodefault
+
+ You can also selectively unblock a part of the zone by making that part
+ transparent with a :ref:`local-zone<unbound.conf.local-zone>` statement.
+ This also works with the other default zones.
+
+
+@@UAHL@unbound.conf@local-data@@: *"<resource record string>"*
+ Configure local data, which is served in reply to queries for it.
+ The query has to match exactly unless you configure the
+ :ref:`local-zone<unbound.conf.local-zone>` as redirect.
+ If not matched exactly, the :ref:`local-zone<unbound.conf.local-zone>`
+ type determines further processing.
+ If :ref:`local-data<unbound.conf.local-data>` is configured that is not a
+ subdomain of a :ref:`local-zone<unbound.conf.local-zone>`, a
+ :ref:`transparent local-zone<unbound.conf.local-zone.type.transparent>` is
+ configured.
+ For record types such as TXT, use single quotes, as in:
+
+ .. code-block:: text
+
+ local-data: 'example. TXT "text"'
+
+ .. note::
+ If you need more complicated authoritative data, with referrals,
+ wildcards, CNAME/DNAME support, or DNSSEC authoritative service, setup
+ a :ref:`stub-zone<unbound.conf.stub>` for it as detailed in the stub
+ zone section below.
+
+
+@@UAHL@unbound.conf@local-data-ptr@@: *"IPaddr name"*
+ Configure local data shorthand for a PTR record with the reversed IPv4 or
+ IPv6 address and the host name.
+ For example ``"192.0.2.4 www.example.com"``.
+ TTL can be inserted like this: ``"2001:DB8::4 7200 www.example.com"``
+
+
+@@UAHL@unbound.conf@local-zone-tag@@: *<zone> <"list of tags">*
+ Assign tags to local zones.
+ Tagged localzones will only be applied when the used
+ :ref:`access-control<unbound.conf.access-control>` element has a matching
+ tag.
+ Tags must be defined in :ref:`define-tag<unbound.conf.define-tag>`.
+ Enclose list of tags in quotes (``""``) and put spaces between tags.
+ When there are multiple tags it checks if the intersection of the list of
+ tags for the query and :ref:`local-zone-tag<unbound.conf.local-zone-tag>`
+ is non-empty.
+
+
+@@UAHL@unbound.conf@local-zone-override@@: *<zone> <IP netblock> <type>*
+ Override the local zone type for queries from addresses matching netblock.
+ Use this localzone type, regardless the type configured for the local zone
+ (both tagged and untagged) and regardless the type configured using
+ :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>`.
+
+
+@@UAHL@unbound.conf@response-ip@@: *<IP-netblock> <action>*
+ This requires use of the ``respip`` module.
+
+ If the IP address in an AAAA or A RR in the answer section of a response
+ matches the specified IP netblock, the specified action will apply.
+ *<action>* has generally the same semantics as that for
+ :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>`,
+ but there are some exceptions.
+
+ Actions for :ref:`response-ip<unbound.conf.response-ip>` are different
+ from those for :ref:`local-zone<unbound.conf.local-zone>` in that in case
+ of the former there is no point of such conditions as "the query matches it
+ but there is no local data".
+ Because of this difference, the semantics of
+ :ref:`response-ip<unbound.conf.response-ip>` actions are modified or
+ simplified as follows: The *static*, *refuse*, *transparent*,
+ *typetransparent*, and *nodefault* actions are invalid for *response-ip*.
+ Using any of these will cause the configuration to be rejected as faulty.
+ The *deny* action is non-conditional, i.e. it always results in dropping
+ the corresponding query.
+ The resolution result before applying the *deny* action is still cached and
+ can be used for other queries.
+
+
+@@UAHL@unbound.conf@response-ip-data@@: *<IP-netblock> <"resource record string">*
+ This requires use of the ``respip`` module.
+
+ This specifies the action data for
+ :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>`,
+ 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
+ IP netblocks).
+ If it is CNAME there must not be more than one
+ :ref:`response-ip-data<unbound.conf.response-ip-data>` for the same
+ *<IP-netblock>*.
+ Also, CNAME and other types of records must not coexist for the same
+ *<IP-netblock>*, following the normal rules for CNAME records.
+ The textual domain name for the CNAME does not have to be explicitly
+ terminated with a dot (``"."``); the root name is assumed to be the origin
+ for the name.
+
+
+@@UAHL@unbound.conf@response-ip-tag@@: *<IP-netblock> <"list of tags">*
+ This requires use of the ``respip`` module.
+
+ Assign tags to response *<IP-netblock>*.
+ If the IP address in an AAAA or A RR in the answer section of a response
+ matches the specified *<IP-netblock>*, the specified tags are assigned to
+ the IP address.
+ Then, if an :ref:`access-control-tag<unbound.conf.access-control-tag>` is
+ defined for the client and it includes one of the tags for the response IP,
+ the corresponding
+ :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>`
+ will apply.
+ Tag matching rule is the same as that for
+ :ref:`access-control-tag<unbound.conf.access-control-tag>` and
+ :ref:`local-zone<unbound.conf.local-zone>`.
+ Unlike :ref:`local-zone-tag<unbound.conf.local-zone-tag>`,
+ :ref:`response-ip-tag<unbound.conf.response-ip-tag>` can be defined for an
+ *<IP-netblock>* even if no :ref:`response-ip<unbound.conf.response-ip>` is
+ defined for that netblock.
+ If multiple :ref:`response-ip-tag<unbound.conf.response-ip-tag>` options
+ are specified for the same *<IP-netblock>* in different statements, all but
+ the first will be ignored.
+ However, this will not be flagged as a configuration error, but the result
+ is probably not what was intended.
+
+ Actions specified in an
+ :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>`
+ that has a matching tag with
+ :ref:`response-ip-tag<unbound.conf.response-ip-tag>` can be those that are
+ "invalid" for :ref:`response-ip<unbound.conf.response-ip>` listed above,
+ since
+ :ref:`access-control-tag-action<unbound.conf.access-control-tag-action>`
+ can be shared with local zones.
+ For these actions, if they behave differently depending on whether local
+ data exists or not in case of local zones, the behavior for
+ :ref:`response-ip-data<unbound.conf.response-ip-data>` will generally
+ result in NOERROR/NODATA instead of NXDOMAIN, since the
+ :ref:`response-ip<unbound.conf.response-ip>` data are inherently type
+ specific, and non-existence of data does not indicate anything about the
+ existence or non-existence of the qname itself.
+ For example, if the matching tag action is static but there is no data for
+ the corresponding :ref:`response-ip<unbound.conf.response-ip>`
+ configuration, then the result will be NOERROR/NODATA.
+ The only case where NXDOMAIN is returned is when an
+ :ref:`always_nxdomain<unbound.conf.local-zone.type.always_nxdomain>`
+ action applies.
+
+
+@@UAHL@unbound.conf@ratelimit@@: *<number or 0>*
+ Enable ratelimiting of queries sent to nameserver for performing recursion.
+ 0 disables the feature.
+ This option is experimental at this time.
+
+ The ratelimit is in queries per second that are allowed.
+ More queries are turned away with an error (SERVFAIL).
+ Cached responses are not ratelimited by this setting.
+
+ This stops recursive floods, eg. random query names, but not spoofed
+ reflection floods.
+ The zone of the query is determined by examining the nameservers for it,
+ the zone name is used to keep track of the rate.
+ For example, 1000 may be a suitable value to stop the server from being
+ overloaded with random names, and keeps unbound from sending traffic to the
+ nameservers for those zones.
+
+ .. note:: Configured forwarders are excluded from ratelimiting.
+
+ Default: 0
+
+
+@@UAHL@unbound.conf@ratelimit-size@@: *<memory size>*
+ Give the size of the data structure in which the current ongoing rates are
+ kept track in.
+ In bytes or use m(mega), k(kilo), g(giga).
+ The ratelimit structure is small, so this data structure likely does not
+ need to be large.
+
+ Default: 4m
+
+
+@@UAHL@unbound.conf@ratelimit-slabs@@: *<number>*
+ Number of slabs in the ratelimit tracking data structure.
+ Slabs reduce lock contention by threads.
+ Must be set to a power of 2.
+ Setting (close) to the number of cpus is a fairly good setting.
+ If left unconfigured, it will be configured automatically to be a power of
+ 2 close to the number of configured threads in multi-threaded environments.
+
+ Default: (unconfigured)
+
+
+@@UAHL@unbound.conf@ratelimit-factor@@: *<number>*
+ Set the amount of queries to rate limit when the limit is exceeded.
+ If set to 0, all queries are dropped for domains where the limit is
+ exceeded.
+ If set to another value, 1 in that number is allowed through to complete.
+ Default is 10, allowing 1/10 traffic to flow normally.
+ This can make ordinary queries complete (if repeatedly queried for), and
+ enter the cache, whilst also mitigating the traffic flow by the factor
+ given.
+
+ Default: 10
+
+
+@@UAHL@unbound.conf@ratelimit-backoff@@: *<yes or no>*
+ If enabled, the ratelimit is treated as a hard failure instead of the
+ default maximum allowed constant rate.
+ When the limit is reached, traffic is ratelimited and demand continues to
+ be kept track of for a 2 second rate window.
+ No traffic is allowed, except for
+ :ref:`ratelimit-factor<unbound.conf.ratelimit-factor>`, until demand
+ decreases below the configured ratelimit for a 2 second rate window.
+ Useful to set :ref:`ratelimit<unbound.conf.ratelimit>` to a suspicious
+ rate to aggressively limit unusually high traffic.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@ratelimit-for-domain@@: *<domain> <number qps or 0>*
+ Override the global :ref:`ratelimit<unbound.conf.ratelimit>` for an exact
+ match domain name with the listed number.
+ You can give this for any number of names.
+ For example, for a top-level-domain you may want to have a higher limit
+ than other names.
+ A value of 0 will disable ratelimiting for that domain.
+
+
+@@UAHL@unbound.conf@ratelimit-below-domain@@: *<domain> <number qps or 0>*
+ Override the global :ref:`ratelimit<unbound.conf.ratelimit>` for a domain
+ name that ends in this name.
+ You can give this multiple times, it then describes different settings in
+ different parts of the namespace.
+ The closest matching suffix is used to determine the qps limit.
+ The rate for the exact matching domain name is not changed, use
+ :ref:`ratelimit-for-domain<unbound.conf.ratelimit-for-domain>` to set
+ that, you might want to use different settings for a top-level-domain and
+ subdomains.
+ A value of 0 will disable ratelimiting for domain names that end in this
+ name.
+
+
+@@UAHL@unbound.conf@ip-ratelimit@@: *<number or 0>*
+ Enable global ratelimiting of queries accepted per ip address.
+ This option is experimental at this time.
+ The ratelimit is in queries per second that are allowed.
+ More queries are completely dropped and will not receive a reply, SERVFAIL
+ or otherwise.
+ IP ratelimiting happens before looking in the cache.
+ This may be useful for mitigating amplification attacks.
+ Clients with a valid DNS Cookie will bypass the ratelimit.
+ If a ratelimit for such clients is still needed,
+ :ref:`ip-ratelimit-cookie<unbound.conf.ip-ratelimit-cookie>`
+ can be used instead.
+
+ Default: 0 (disabled)
+
+
+@@UAHL@unbound.conf@ip-ratelimit-cookie@@: *<number or 0>*
+ Enable global ratelimiting of queries accepted per IP address with a valid
+ DNS Cookie.
+ This option is experimental at this time.
+ The ratelimit is in queries per second that are allowed.
+ More queries are completely dropped and will not receive a reply, SERVFAIL
+ or otherwise.
+ IP ratelimiting happens before looking in the cache.
+ This option could be useful in combination with
+ :ref:`allow_cookie<unbound.conf.access-control.action.allow_cookie>`, in an
+ attempt to mitigate other amplification attacks than UDP reflections (e.g.,
+ attacks targeting Unbound itself) which are already handled with DNS
+ Cookies.
+ If used, the value is suggested to be higher than
+ :ref:`ip-ratelimit<unbound.conf.ip-ratelimit>` e.g., tenfold.
+
+ Default: 0 (disabled)
+
+
+@@UAHL@unbound.conf@ip-ratelimit-size@@: *<memory size>*
+ Give the size of the data structure in which the current ongoing rates are
+ kept track in.
+ In bytes or use m(mega), k(kilo), g(giga).
+ The IP ratelimit structure is small, so this data structure likely does not
+ need to be large.
+
+ Default: 4m
+
+
+@@UAHL@unbound.conf@ip-ratelimit-slabs@@: *<number>*
+ Number of slabs in the ip ratelimit tracking data structure.
+ Slabs reduce lock contention by threads.
+ Must be set to a power of 2.
+ Setting (close) to the number of cpus is a fairly good setting.
+ If left unconfigured, it will be configured automatically to be a power of
+ 2 close to the number of configured threads in multi-threaded environments.
+
+ Default: (unconfigured)
+
+
+@@UAHL@unbound.conf@ip-ratelimit-factor@@: *<number>*
+ Set the amount of queries to rate limit when the limit is exceeded.
+ If set to 0, all queries are dropped for addresses where the limit is
+ exceeded.
+ If set to another value, 1 in that number is allowed through to complete.
+ Default is 10, allowing 1/10 traffic to flow normally.
+ This can make ordinary queries complete (if repeatedly queried for), and
+ enter the cache, whilst also mitigating the traffic flow by the factor
+ given.
+
+ Default: 10
+
+
+@@UAHL@unbound.conf@ip-ratelimit-backoff@@: *<yes or no>*
+ If enabled, the rate limit is treated as a hard failure instead of the
+ default maximum allowed constant rate.
+ When the limit is reached, traffic is ratelimited and demand continues to
+ be kept track of for a 2 second rate window.
+ No traffic is allowed, except for
+ :ref:`ip-ratelimit-factor<unbound.conf.ip-ratelimit-factor>`, until demand
+ decreases below the configured ratelimit for a 2 second rate window.
+ Useful to set :ref:`ip-ratelimit<unbound.conf.ip-ratelimit>` to a
+ suspicious rate to aggressively limit unusually high traffic.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@outbound-msg-retry@@: *<number>*
+ The number of retries, per upstream nameserver in a delegation, that
+ Unbound will attempt in case a throwaway response is received.
+ No response (timeout) contributes to the retry counter.
+ If a forward/stub zone is used, this is the number of retries per
+ nameserver in the zone.
+
+ Default: 5
+
+
+@@UAHL@unbound.conf@max-sent-count@@: *<number>*
+ Hard limit on the number of outgoing queries Unbound will make while
+ resolving a name, making sure large NS sets do not loop.
+ Results in SERVFAIL when reached.
+ It resets on query restarts (e.g., CNAME) and referrals.
+
+ Default: 32
+
+
+@@UAHL@unbound.conf@max-query-restarts@@: *<number>*
+ Hard limit on the number of times Unbound is allowed to restart a query
+ upon encountering a CNAME record.
+ Results in SERVFAIL when reached.
+ Changing this value needs caution as it can allow long CNAME chains to be
+ accepted, where Unbound needs to verify (resolve) each link individually.
+
+ Default: 11
+
+
+@@UAHL@unbound.conf@iter-scrub-ns@@: *<number>*
+ Limit on the number of NS records allowed in an rrset of type NS, from the
+ iterator scrubber.
+ This protects the internals of the resolver from overly large NS sets.
+
+ Default: 20
+
+
+@@UAHL@unbound.conf@iter-scrub-cname@@: *<number>*
+ Limit on the number of CNAME, DNAME records in an answer, from the iterator
+ scrubber.
+ This protects the internals of the resolver from overly long indirection
+ chains.
+ Clips off the remainder of the reply packet at that point.
+
+ Default: 11
+
+
+@@UAHL@unbound.conf@max-global-quota@@: *<number>*
+ Limit on the number of upstream queries sent out for an incoming query and
+ its subqueries from recursion.
+ It is not reset during the resolution.
+ When it is exceeded the query is failed and the lookup process stops.
+
+ Default: 200
+
+
+@@UAHL@unbound.conf@fast-server-permil@@: *<number>*
+ Specify how many times out of 1000 to pick from the set of fastest servers.
+ 0 turns the feature off.
+ A value of 900 would pick from the fastest servers 90 percent of the time,
+ and would perform normal exploration of random servers for the remaining
+ time.
+ When :ref:`prefetch<unbound.conf.prefetch>` is enabled (or
+ :ref:`serve-expired<unbound.conf.serve-expired>`), such prefetches are not
+ sped up, because there is no one waiting for it, and it presents a good
+ moment to perform server exploration.
+ The :ref:`fast-server-num<unbound.conf.fast-server-num>` option can be
+ used to specify the size of the fastest servers set.
+
+ Default: 0
+
+
+@@UAHL@unbound.conf@fast-server-num@@: *<number>*
+ Set the number of servers that should be used for fast server selection.
+ Only use the fastest specified number of servers with the
+ :ref:`fast-server-permil<unbound.conf.fast-server-permil>` option, that
+ turns this on or off.
+
+ Default: 3
+
+
+@@UAHL@unbound.conf@answer-cookie@@: *<yes or no>*
+ If enabled, Unbound will answer to requests containing DNS Cookies as
+ specified in RFC 7873 and RFC 9018.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@cookie-secret@@: *"<128 bit hex string>"*
+ Server's secret for DNS Cookie generation.
+ Useful to explicitly set for servers in an anycast deployment that need to
+ share the secret in order to verify each other's Server Cookies.
+ An example hex string would be "000102030405060708090a0b0c0d0e0f".
+
+ .. note::
+ This option is ignored if a
+ :ref:`cookie-secret-file<unbound.conf.cookie-secret-file>` is present.
+ In that case the secrets from that file are used in DNS Cookie
+ calculations.
+
+ Default: 128 bits random secret generated at startup time
+
+
+@@UAHL@unbound.conf@cookie-secret-file@@: *<filename>*
+ File from which the secrets are read used in DNS Cookie calculations.
+ When this file exists, the secrets in this file are used and the secret
+ specified by the
+ :ref:`cookie-secret<unbound.conf.cookie-secret>` option is ignored.
+ Enable it by setting a filename, like
+ "/usr/local/etc/unbound_cookiesecrets.txt".
+ The content of this file must be manipulated with the
+ :ref:`add_cookie_secret<unbound-control.commands.add_cookie_secret>`,
+ :ref:`drop_cookie_secret<unbound-control.commands.drop_cookie_secret>` and
+ :ref:`activate_cookie_secret<unbound-control.commands.activate_cookie_secret>`
+ commands to the :doc:`unbound-control(8)</manpages/unbound-control>` tool.
+ Please see that manpage on how to perform a safe cookie secret rollover.
+
+ Default: "" (disabled)
+
+
+@@UAHL@unbound.conf@edns-client-string@@: *<IP netblock> <string>*
+ Include an EDNS0 option containing configured ASCII string in queries with
+ destination address matching the configured *<IP netblock>*.
+ This configuration option can be used multiple times.
+ The most specific match will be used.
+
+
+@@UAHL@unbound.conf@edns-client-string-opcode@@: *<opcode>*
+ EDNS0 option code for the
+ :ref:`edns-client-string<unbound.conf.edns-client-string>` option, from 0
+ to 65535.
+ A value from the 'Reserved for Local/Experimental' range (65001-65534)
+ should be used.
+
+ Default: 65001
+
+
+@@UAHL@unbound.conf@ede@@: *<yes or no>*
+ If enabled, Unbound will respond with Extended DNS Error codes
+ (:rfc:`8914`).
+ These EDEs privide additional information with a response mainly for, but
+ not limited to, DNS and DNSSEC errors.
+
+ When the :ref:`val-log-level<unbound.conf.val-log-level>` option is also
+ set to ``2``, responses with Extended DNS Errors concerning DNSSEC failures
+ will also contain a descriptive text message about the reason for the
+ failure.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@ede-serve-expired@@: *<yes or no>*
+ If enabled, Unbound will attach an Extended DNS Error (:rfc:`8914`) *Code 3
+ - Stale Answer* as EDNS0 option to the expired response.
+
+ .. note::
+ :ref:`ede: yes<unbound.conf.ede>` needs to be set as well for this to
+ work.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@dns-error-reporting@@: *<yes or no>*
+ If enabled, Unbound will send DNS Error Reports (:rfc:`9567`).
+ The name servers need to express support by attaching the Report-Channel
+ EDNS0 option on their replies specifying the reporting agent for the zone.
+ Any errors encountered during resolution that would result in Unbound
+ generating an Extended DNS Error (:rfc:`8914`) will be reported to the
+ zone's reporting agent.
+
+ The :ref:`ede<unbound.conf.ede>` option does not need to be enabled for
+ this to work.
+
+ It is advised that the
+ :ref:`qname-minimisation<unbound.conf.qname-minimisation>` option is also
+ enabled to increase privacy on the outgoing reports.
+
+ Default: no
+
+.. _unbound.conf.remote:
+
+Remote Control Options
+^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+To setup the correct self-signed certificates use the
+*unbound-control-setup(8)* utility.
+
+
+@@UAHL@unbound.conf.remote@control-enable@@: *<yes or no>*
+ The option is used to enable remote control.
+ If turned off, the server does not listen for control commands.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.remote@control-interface@@: *<IP address or interface name or path>*
+ Give IPv4 or IPv6 addresses or local socket path to listen on for control
+ commands.
+ If an interface name is used instead of an IP address, the list of IP
+ addresses on that interface are used.
+
+ By default localhost (``127.0.0.1`` and ``::1``) is listened to.
+ Use ``0.0.0.0`` and ``::0`` to listen to all interfaces.
+ If you change this and permissions have been dropped, you must restart the
+ server for the change to take effect.
+
+ If you set it to an absolute path, a unix domain socket is used.
+ This socket does not use the certificates and keys, so those files need not
+ be present.
+ To restrict access, Unbound sets permissions on the file to the user and
+ group that is configured, the access bits are set to allow the group
+ members to access the control socket file.
+ Put users that need to access the socket in the that group.
+ To restrict access further, create a directory to put the control socket in
+ and restrict access to that directory.
+
+
+@@UAHL@unbound.conf.remote@control-port@@: *<port number>*
+ The port number to listen on for IPv4 or IPv6 control interfaces.
+
+ .. note::
+ If you change this and permissions have been dropped, you must restart
+ the server for the change to take effect.
+
+ Default: 8953
+
+
+@@UAHL@unbound.conf.remote@control-use-cert@@: *<yes or no>*
+ For localhost
+ :ref:`control-interface<unbound.conf.remote.control-interface>` you can
+ disable the use of TLS by setting this option to "no".
+ For local sockets, TLS is disabled and the value of this option is ignored.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf.remote@server-key-file@@: *<private key file>*
+ Path to the server private key.
+ This file is generated by the
+ :doc:`unbound-control-setup(8)</manpages/unbound-control>` utility.
+ This file is used by the Unbound server, but not by
+ :doc:`unbound-control(8)</manpages/unbound-control>`.
+
+ Default: unbound_server.key
+
+
+@@UAHL@unbound.conf.remote@server-cert-file@@: *<certificate file.pem>*
+ Path to the server self signed certificate.
+ This file is generated by the
+ :doc:`unbound-control-setup(8)</manpages/unbound-control>` utility.
+ This file is used by the Unbound server, and also by
+ :doc:`unbound-control(8)</manpages/unbound-control>`.
+
+ Default: unbound_server.pem
+
+
+@@UAHL@unbound.conf.remote@control-key-file@@: *<private key file>*
+ Path to the control client private key.
+ This file is generated by the
+ :doc:`unbound-control-setup(8)</manpages/unbound-control>` utility.
+ This file is used by :doc:`unbound-control(8)</manpages/unbound-control>`.
+
+ Default: unbound_control.key
+
+
+@@UAHL@unbound.conf.remote@control-cert-file@@: *<certificate file.pem>*
+ Path to the control client certificate.
+ This certificate has to be signed with the server certificate.
+ This file is generated by the
+ :doc:`unbound-control-setup(8)</manpages/unbound-control>` utility.
+ This file is used by :doc:`unbound-control(8)</manpages/unbound-control>`.
+
+ Default: unbound_control.pem
+
+.. _unbound.conf.stub:
+
+Stub Zone Options
+^^^^^^^^^^^^^^^^^
+
+There may be multiple **stub-zone:** clauses.
+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.
+Class IN is assumed.
+The servers should be authority servers, not recursors; Unbound performs the
+recursive processing itself for stub zones.
+
+The stub zone can be used to configure authoritative data to be used by the
+resolver that cannot be accessed using the public internet servers.
+This is useful for company-local data or private zones.
+Setup an authoritative server on a different host (or different port).
+Enter a config entry for Unbound with:
+
+.. code-block:: text
+
+ stub-addr: <ip address of host[@port]>
+
+The Unbound resolver can then access the data, without referring to the public
+internet for it.
+
+This setup allows DNSSEC signed zones to be served by that authoritative
+server, in which case a trusted key entry with the public key can be put in
+config, so that Unbound can validate the data and set the AD bit on replies for
+the private zone (authoritative servers do not set the AD bit).
+This setup makes Unbound capable of answering queries for the private zone, and
+can even set the AD bit ('authentic'), but the AA ('authoritative') bit is not
+set on these replies.
+
+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:`local-zone: nodefault<unbound.conf.local-zone.type.nodefault>` (or
+:ref:`transparent<unbound.conf.local-zone.type.transparent>`) clause makes the
+(reverse-) zone bypass Unbound's filtering of :rfc:`1918` zones.
+
+
+@@UAHL@unbound.conf.stub@name@@: *<domain name>*
+ Name of the stub zone.
+ This is the full domain name of the zone.
+
+
+@@UAHL@unbound.conf.stub@stub-host@@: *<domain name>*
+ Name of stub zone nameserver.
+ Is itself resolved before it is used.
+
+ To use a non-default port for DNS communication append ``'@'`` with the
+ port number.
+
+ If TLS is enabled, then you can append a ``'#'`` and a name, then it'll
+ check the TLS authentication certificates with that name.
+
+ If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first.
+ If only ``'#'`` is used the default port is the configured
+ :ref:`tls-port<unbound.conf.tls-port>`.
+
+
+@@UAHL@unbound.conf.stub@stub-addr@@: *<IP address>*
+ IP address of stub zone nameserver.
+ Can be IPv4 or IPv6.
+
+ To use a non-default port for DNS communication append ``'@'`` with the
+ port number.
+
+ If TLS is enabled, then you can append a ``'#'`` and a name, then it'll
+ check the tls authentication certificates with that name.
+
+ If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first.
+ If only ``'#'`` is used the default port is the configured
+ :ref:`tls-port<unbound.conf.tls-port>`.
+
+
+@@UAHL@unbound.conf.stub@stub-prime@@: *<yes or no>*
+ If enabled it performs NS set priming, which is similar to root hints,
+ where it starts using the list of nameservers currently published by the
+ zone.
+ Thus, if the hint list is slightly outdated, the resolver picks up a
+ correct list online.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.stub@stub-first@@: *<yes or no>*
+ If enabled, a query is attempted without the stub clause if it fails.
+ The data could not be retrieved and would have caused SERVFAIL because the
+ servers are unreachable, instead it is tried without this clause.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.stub@stub-tls-upstream@@: *<yes or no>*
+ Enabled or disable whether the queries to this stub use TLS for transport.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.stub@stub-ssl-upstream@@: *<yes or no>*
+ Alternate syntax for
+ :ref:`stub-tls-upstream<unbound.conf.stub.stub-tls-upstream>`.
+
+
+@@UAHL@unbound.conf.stub@stub-tcp-upstream@@: *<yes or no>*
+ If it is set to "yes" then upstream queries use TCP only for transport
+ regardless of global flag :ref:`tcp-upstream<unbound.conf.tcp-upstream>`.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.stub@stub-no-cache@@: *<yes or no>*
+ If enabled, data inside the stub is not cached.
+ This is useful when you want immediate changes to be visible.
+
+ Default: no
+
+.. _unbound.conf.forward:
+
+Forward Zone Options
+^^^^^^^^^^^^^^^^^^^^
+
+There may be multiple **forward-zone:** clauses.
+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
+to.
+The servers listed as :ref:`forward-host<unbound.conf.forward.forward-host>`
+and :ref:`forward-addr<unbound.conf.forward.forward-addr>` have to handle
+further recursion for the query.
+Thus, those servers are not authority servers, but are (just like Unbound is)
+recursive servers too; Unbound does not perform recursion itself for the
+forward zone, it lets the remote server do it.
+Class IN is assumed.
+CNAMEs are chased by Unbound itself, asking the remote server for every name in
+the indirection chain, to protect the local cache from illegal indirect
+referenced items.
+A :ref:`forward-zone<unbound.conf.forward>` entry with name
+``"."`` and a :ref:`forward-addr<unbound.conf.forward.forward-addr>` target
+will forward all queries to that other server (unless it can answer from the
+cache).
+
+
+@@UAHL@unbound.conf.forward@name@@: *<domain name>*
+ Name of the forward zone.
+ This is the full domain name of the zone.
+
+
+@@UAHL@unbound.conf.forward@forward-host@@: *<domain name>*
+ Name of server to forward to.
+ Is itself resolved before it is used.
+
+ To use a non-default port for DNS communication append ``'@'`` with the
+ port number.
+
+ If TLS is enabled, then you can append a ``'#'`` and a name, then it'll
+ check the TLS authentication certificates with that name.
+
+ If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first.
+ If only ``'#'`` is used the default port is the configured
+ :ref:`tls-port<unbound.conf.tls-port>`.
+
+
+@@UAHL@unbound.conf.forward@forward-addr@@: *<IP address>*
+ IP address of server to forward to.
+ Can be IPv4 or IPv6.
+
+ To use a non-default port for DNS communication append ``'@'`` with the
+ port number.
+
+ If TLS is enabled, then you can append a ``'#'`` and a name, then it'll
+ check the tls authentication certificates with that name.
+
+ If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first.
+ If only ``'#'`` is used the default port is the configured
+ :ref:`tls-port<unbound.conf.tls-port>`.
+
+ At high verbosity it logs the TLS certificate, with TLS enabled.
+ If you leave out the ``'#'`` and auth name from the
+ :ref:`forward-addr<unbound.conf.forward.forward-addr>`, any name is
+ accepted.
+ The cert must also match a CA from the
+ :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>`.
+
+
+@@UAHL@unbound.conf.forward@forward-first@@: *<yes or no>*
+ If a forwarded query is met with a SERVFAIL error, and this option is
+ enabled, Unbound will fall back to normal recursive resolution for this
+ query as if no query forwarding had been specified.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.forward@forward-tls-upstream@@: *<yes or no>*
+ Enabled or disable whether the queries to this forwarder use TLS for
+ transport.
+ If you enable this, also configure a
+ :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>` or use
+ :ref:`tls-win-cert<unbound.conf.tls-win-cert>` to load CA certs, otherwise
+ the connections cannot be authenticated.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.forward@forward-ssl-upstream@@: *<yes or no>*
+ Alternate syntax for
+ :ref:`forward-tls-upstream<unbound.conf.forward.forward-tls-upstream>`.
+
+
+@@UAHL@unbound.conf.forward@forward-tcp-upstream@@: *<yes or no>*
+ If it is set to "yes" then upstream queries use TCP only for transport
+ regardless of global flag :ref:`tcp-upstream<unbound.conf.tcp-upstream>`.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.forward@forward-no-cache@@: *<yes or no>*
+ If enabled, data inside the forward is not cached.
+ This is useful when you want immediate changes to be visible.
+
+ Default: no
+
+.. _unbound.conf.auth:
+
+Authority Zone Options
+^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+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.
+
+With :ref:`for-downstream: yes<unbound.conf.auth.for-downstream>` (default),
+authority zones are processed after **local-zones** and before cache.
+When used in this manner, Unbound responds like an authority server with no
+further processing other than returning an answer from the zone contents.
+A notable example, in this case, is CNAME records which are returned verbatim
+to downstream clients without further resolution.
+
+With :ref:`for-upstream: yes<unbound.conf.auth.for-upstream>` (default),
+authority zones are processed after the cache lookup, just before going to the
+network to fetch information for recursion.
+When used in this manner they provide a local copy of an authority server
+that speeds up lookups for that data during resolving.
+
+If both options are enabled (default), client queries for an authority zone are
+answered authoritatively from Unbound, while internal queries that require data
+from the authority zone consult the local zone data instead of going to the
+network.
+
+An interesting configuration is
+:ref:`for-downstream: no<unbound.conf.auth.for-downstream>`,
+:ref:`for-upstream: yes<unbound.conf.auth.for-upstream>`
+that allows for hyperlocal behavior where both client and internal queries
+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.
+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
+detect zone changes.
+
+If the update fetch fails, the timers in the SOA record are used to time
+another fetch attempt.
+Until the SOA expiry timer is reached.
+Then the zone is expired.
+When a zone is expired, queries are SERVFAIL, and any new serial number is
+accepted from the primary (even if older), and if fallback is enabled, the
+fallback activates to fetch from the upstream instead of the SERVFAIL.
+
+
+@@UAHL@unbound.conf.auth@name@@: *<zone name>*
+ Name of the authority zone.
+
+
+@@UAHL@unbound.conf.auth@primary@@: *<IP address or host name>*
+ Where to download a copy of the zone from, with AXFR and IXFR.
+ Multiple primaries can be specified.
+ They are all tried if one fails.
+
+ To use a non-default port for DNS communication append ``'@'`` with the
+ port number.
+
+ You can append a ``'#'`` and a name, then AXFR over TLS can be used and the
+ TLS authentication certificates will be checked with that name.
+
+ If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first.
+ If you point it at another Unbound instance, it would not work because that
+ does not support AXFR/IXFR for the zone, but if you used
+ :ref:`url<unbound.conf.auth.url>` to download the zonefile as a text file
+ from a webserver that would work.
+
+ If you specify the hostname, you cannot use the domain from the zonefile,
+ because it may not have that when retrieving that data, instead use a plain
+ IP address to avoid a circular dependency on retrieving that IP address.
+
+
+@@UAHL@unbound.conf.auth@master@@: *<IP address or host name>*
+ Alternate syntax for :ref:`primary<unbound.conf.auth.primary>`.
+
+
+@@UAHL@unbound.conf.auth@url@@: *<URL to zone file>*
+ Where to download a zonefile for the zone.
+ With HTTP or HTTPS.
+ An example for the url is:
+
+ .. code-block:: text
+
+ http://www.example.com/example.org.zone
+
+ Multiple url statements can be given, they are tried in turn.
+
+ If only urls are given the SOA refresh timer is used to wait for making new
+ downloads.
+ If also primaries are listed, the primaries are first probed with UDP SOA
+ queries to see if the SOA serial number has changed, reducing the number of
+ downloads.
+ If none of the urls work, the primaries are tried with IXFR and AXFR.
+
+ For HTTPS, the :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>` and
+ the hostname from the url are used to authenticate the connection.
+
+ If you specify a hostname in the URL, you cannot use the domain from the
+ zonefile, because it may not have that when retrieving that data, instead
+ use a plain IP address to avoid a circular dependency on retrieving that IP
+ address.
+
+ Avoid dependencies on name lookups by using a notation like
+ ``"http://192.0.2.1/unbound-primaries/example.com.zone"``, with an explicit
+ IP address.
+
+
+@@UAHL@unbound.conf.auth@allow-notify@@: *<IP address or host name or netblockIP/prefix>*
+ With :ref:`allow-notify<unbound.conf.auth.allow-notify>` you can specify
+ additional sources of notifies.
+ When notified, the server attempts to first probe and then zone transfer.
+ If the notify is from a primary, it first attempts that primary.
+ Otherwise other primaries are attempted.
+ If there are no primaries, but only urls, the file is downloaded when
+ notified.
+
+ .. note::
+ The primaries from :ref:`primary<unbound.conf.auth.primary>` and
+ :ref:`url<unbound.conf.auth.url>` statements are allowed notify by
+ default.
+
+
+@@UAHL@unbound.conf.auth@fallback-enabled@@: *<yes or no>*
+ If enabled, Unbound falls back to querying the internet as a resolver for
+ this zone when lookups fail.
+ For example for DNSSEC validation failures.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.auth@for-downstream@@: *<yes or no>*
+ If enabled, Unbound serves authority responses to downstream clients for
+ this zone.
+ This option makes Unbound behave, for the queries with names in this zone,
+ like one of the authority servers for that zone.
+
+ Turn it off if you want Unbound to provide recursion for the zone but have
+ a local copy of zone data.
+
+ If :ref:`for-downstream: no<unbound.conf.auth.for-downstream>` and
+ :ref:`for-upstream: yes<unbound.conf.auth.for-upstream>` are set, then
+ Unbound will DNSSEC validate the contents of the zone before serving the
+ zone contents to clients and store validation results in the cache.
+
+ Default: yes
+
+
+
+@@UAHL@unbound.conf.auth@for-upstream@@: *<yes or no>*
+ If enabled, Unbound fetches data from this data collection for answering
+ recursion queries.
+ Instead of sending queries over the internet to the authority servers for
+ this zone, it'll fetch the data directly from the zone data.
+
+ Turn it on when you want Unbound to provide recursion for downstream
+ clients, and use the zone data as a local copy to speed up lookups.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf.auth@zonemd-check@@: *<yes or no>*
+ Enable this option to check ZONEMD records in the zone.
+ The ZONEMD record is a checksum over the zone data.
+ This includes glue in the zone and data from the zone file, and excludes
+ comments from the zone file.
+ When there is a DNSSEC chain of trust, DNSSEC signatures are checked too.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.auth@zonemd-reject-absence@@: *<yes or no>*
+ Enable this option to reject the absence of the ZONEMD record.
+ Without it, when ZONEMD is not there it is not checked.
+
+ It is useful to enable for a non-DNSSEC signed zone where the operator
+ wants to require the verification of a ZONEMD, hence a missing ZONEMD is a
+ failure.
+
+ The action upon failure is controlled by the
+ :ref:`zonemd-permissive-mode<unbound.conf.zonemd-permissive-mode>` option,
+ for log only or also block the zone.
+
+ Without the option, absence of a ZONEMD is only a failure when the zone is
+ DNSSEC signed, and we have a trust anchor, and the DNSSEC verification of
+ the absence of the ZONEMD fails.
+ With the option enabled, the absence of a ZONEMD is always a failure, also
+ for nonDNSSEC signed zones.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.auth@zonefile@@: *<filename>*
+ The filename where the zone is stored.
+ 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).
+
+.. _unbound.conf.view:
+
+View Options
+^^^^^^^^^^^^
+
+There may be multiple **view:** clauses.
+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.
+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.
+View can be mapped to requests by specifying the view name in an
+:ref:`access-control-view<unbound.conf.access-control-view>` attribute.
+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.
+
+
+@@UAHL@unbound.conf.view@name@@: *<view name>*
+ Name of the view.
+ Must be unique.
+ This name is used in the
+ :ref:`access-control-view<unbound.conf.access-control-view>` attribute.
+
+
+@@UAHL@unbound.conf.view@local-zone@@: *<zone> <type>*
+ View specific local zone elements.
+ Has the same types and behaviour as the global
+ :ref:`local-zone<unbound.conf.local-zone>` elements.
+ When there is at least one *local-zone:* specified and :ref:`view-first:
+ no<unbound.conf.view.view-first>` is set, the default local-zones will be
+ added to this view.
+ Defaults can be disabled using the nodefault type.
+ When :ref:`view-first: yes<unbound.conf.view.view-first>` is set or when a
+ view does not have a :ref:`local-zone<unbound.conf.view.local-zone>`, the
+ global :ref:`local-zone<unbound.conf.local-zone>` will be used including
+ it's default zones.
+
+
+@@UAHL@unbound.conf.view@local-data@@: *"<resource record string>"*
+ View specific local data elements.
+ Has the same behaviour as the global
+ :ref:`local-data<unbound.conf.local-data>` elements.
+
+
+@@UAHL@unbound.conf.view@local-data-ptr@@: *"IPaddr name"*
+ View specific local-data-ptr elements.
+ Has the same behaviour as the global
+ :ref:`local-data-ptr<unbound.conf.local-data-ptr>` elements.
+
+
+@@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
+ :ref:`local-data<unbound.conf.local-data>` if there is no match in the
+ view specific options.
+
+ Default: no
+
+Python Module Options
+^^^^^^^^^^^^^^^^^^^^^
+
+The **python:** clause 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
+``python`` has to be put in the
+:ref:`module-config<unbound.conf.module-config>` option (usually first, or
+between the validator and iterator).
+Multiple instances of the python module are supported by adding the word
+``python`` more than once.
+
+If the :ref:`chroot<unbound.conf.chroot>` option is enabled, you should make
+sure Python's library directory structure is bind mounted in the new root
+environment, see *mount(8)*.
+Also the :ref:`python-script<unbound.conf.python.python-script>` path should
+be specified as an absolute path relative to the new root, or as a relative
+path to the working directory.
+
+
+@@UAHL@unbound.conf.python@python-script@@: *<python file>*
+ The script file to load.
+ Repeat this option for every python module instance added to the
+ :ref:`module-config<unbound.conf.module-config>` option.
+
+Dynamic Library Module Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The **dynlib:** clause 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.
+Multiple instances of dynamic libraries are supported by adding the word
+``dynlib`` more than once.
+
+The :ref:`dynlib-file<unbound.conf.dynlib.dynlib-file>` path should be
+specified as an absolute path relative to the new path set by
+:ref:`chroot<unbound.conf.chroot>`, or as a relative path to the working
+directory.
+
+
+@@UAHL@unbound.conf.dynlib@dynlib-file@@: *<dynlib file>*
+ The dynamic library file to load.
+ Repeat this option for every dynlib module instance added to the
+ :ref:`module-config<unbound.conf.module-config>` option.
+
+DNS64 Module Options
+^^^^^^^^^^^^^^^^^^^^
+
+The ``dns64`` module must be configured in the
+:ref:`module-config<unbound.conf.module-config>` directive, e.g.:
+
+.. code-block:: text
+
+ module-config: "dns64 validator iterator"
+
+and be compiled into the daemon to be enabled.
+
+.. note::
+ These settings go in the :ref:`server:<unbound.conf.server>` section.
+
+
+@@UAHL@unbound.conf.dns64@dns64-prefix@@: *<IPv6 prefix>*
+ This sets the DNS64 prefix to use to synthesize AAAA records with.
+ It must be /96 or shorter.
+
+ Default: 64:ff9b::/96
+
+
+@@UAHL@unbound.conf.dns64@dns64-synthall@@: *<yes or no>*
+ .. warning:: Debugging feature!
+
+ If enabled, synthesize all AAAA records despite the presence of actual AAAA
+ records.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.dns64@dns64-ignore-aaaa@@: *<domain name>*
+ List domain for which the AAAA records are ignored and the A record is used
+ by DNS64 processing instead.
+ Can be entered multiple times, list a new domain for which it applies, one
+ per line.
+ Applies also to names underneath the name given.
+
+NAT64 Operation
+^^^^^^^^^^^^^^^
+
+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>*
+ Use NAT64 to reach IPv4-only servers.
+ Consider also enabling :ref:`prefer-ip6<unbound.conf.prefer-ip6>`
+ to prefer native IPv6 connections to nameservers.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.nat64@nat64-prefix@@: *<IPv6 prefix>*
+ Use a specific NAT64 prefix to reach IPv4-only servers.
+ The prefix length must be one of /32, /40, /48, /56, /64 or /96.
+
+ Default: 64:ff9b::/96 (same as :ref:`dns64-prefix<unbound.conf.dns64.dns64-prefix>`)
+
+DNSCrypt Options
+^^^^^^^^^^^^^^^^
+
+The **dnscrypt:** clause 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.
+You can use dnscrypt-wrapper to generate those:
+https://github.com/cofyc/dnscrypt-wrapper/blob/master/README.md#usage
+
+
+@@UAHL@unbound.conf.dnscrypt@dnscrypt-enable@@: *<yes or no>*
+ Whether or not the dnscrypt config should be enabled.
+ You may define configuration but not activate it.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.dnscrypt@dnscrypt-port@@: *<port number>*
+ On which port should dnscrypt should be activated.
+
+ .. note::
+ There should be a matching interface option defined in the
+ :ref:`server:<unbound.conf.server>` section for this port.
+
+
+@@UAHL@unbound.conf.dnscrypt@dnscrypt-provider@@: *<provider name>*
+ The provider name to use to distribute certificates.
+ This is of the form:
+
+ .. code-block:: text
+
+ 2.dnscrypt-cert.example.com.
+
+ .. important:: The name *MUST* end with a dot.
+
+
+@@UAHL@unbound.conf.dnscrypt@dnscrypt-secret-key@@: *<path to secret key file>*
+ Path to the time limited secret key file.
+ This option may be specified multiple times.
+
+
+@@UAHL@unbound.conf.dnscrypt@dnscrypt-provider-cert@@: *<path to cert file>*
+ Path to the certificate related to the
+ :ref:`dnscrypt-secret-key<unbound.conf.dnscrypt.dnscrypt-secret-key>`.
+ This option may be specified multiple times.
+
+
+@@UAHL@unbound.conf.dnscrypt@dnscrypt-provider-cert-rotated@@: *<path to cert file>*
+ Path to a certificate that we should be able to serve existing connection
+ from but do not want to advertise over
+ :ref:`dnscrypt-provider<unbound.conf.dnscrypt.dnscrypt-provider>` 's TXT
+ record certs distribution.
+
+ A typical use case is when rotating certificates, existing clients may
+ still use the client magic from the old cert in their queries until they
+ fetch and update the new cert.
+ Likewise, it would allow one to prime the new cert/key without distributing
+ the new cert yet, this can be useful when using a network of servers using
+ anycast and on which the configuration may not get updated at the exact
+ same time.
+
+ By priming the cert, the servers can handle both old and new certs traffic
+ while distributing only one.
+
+ This option may be specified multiple times.
+
+
+@@UAHL@unbound.conf.dnscrypt@dnscrypt-shared-secret-cache-size@@: *<memory size>*
+ Give the size of the data structure in which the shared secret keys are
+ kept in.
+ In bytes or use m(mega), k(kilo), g(giga).
+ The shared secret cache is used when a same client is making multiple
+ queries using the same public key.
+ It saves a substantial amount of CPU.
+
+ Default: 4m
+
+
+@@UAHL@unbound.conf.dnscrypt@dnscrypt-shared-secret-cache-slabs@@: *<number>*
+ Number of slabs in the dnscrypt shared secrets cache.
+ Slabs reduce lock contention by threads.
+ Must be set to a power of 2.
+ Setting (close) to the number of cpus is a fairly good setting.
+ If left unconfigured, it will be configured automatically to be a power of
+ 2 close to the number of configured threads in multi-threaded environments.
+
+ Default: (unconfigured)
+
+
+@@UAHL@unbound.conf.dnscrypt@dnscrypt-nonce-cache-size@@: *<memory size>*
+ Give the size of the data structure in which the client nonces are kept in.
+ In bytes or use m(mega), k(kilo), g(giga).
+ The nonce cache is used to prevent dnscrypt message replaying.
+ Client nonce should be unique for any pair of client pk/server sk.
+
+ Default: 4m
+
+
+@@UAHL@unbound.conf.dnscrypt@dnscrypt-nonce-cache-slabs@@: *<number>*
+ Number of slabs in the dnscrypt nonce cache.
+ Slabs reduce lock contention by threads.
+ Must be set to a power of 2.
+ Setting (close) to the number of cpus is a fairly good setting.
+ If left unconfigured, it will be configured automatically to be a power of
+ 2 close to the number of configured threads in multi-threaded environments.
+
+ Default: (unconfigured)
+
+EDNS Client Subnet Module Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ECS module must be configured in the
+:ref:`module-config<unbound.conf.module-config>` directive, e.g.:
+
+.. code-block:: text
+
+ module-config: "subnetcache validator iterator"
+
+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
+in a specialized cache.
+If the authority indicated no support, the response is stored in the regular
+cache.
+
+Additionally, when a client includes the option in its queries, Unbound will
+forward the option when sending the query to addresses that are explicitly
+allowed in the configuration using
+:ref:`send-client-subnet<unbound.conf.ecs.send-client-subnet>`.
+The option will always be forwarded, regardless the allowed addresses, when
+:ref:`client-subnet-always-forward: yes<unbound.conf.ecs.client-subnet-always-forward>`
+is set.
+In this case the lookup in the regular cache is skipped.
+
+The maximum size of the ECS cache is controlled by
+:ref:`msg-cache-size<unbound.conf.msg-cache-size>` in the configuration file.
+On top of that, for each query only 100 different subnets are allowed to be
+stored for each address family.
+Exceeding that number, older entries will be purged from cache.
+
+Note that due to the nature of how EDNS Client Subnet works, by segregating the
+client IP space in order to try and have tailored responses for prefixes of
+unknown sizes, resolution and cache response performance are impacted as a
+result.
+Usage of the subnetcache module should only be enabled in installations that
+require such functionality where the resolver and the clients belong to
+different networks.
+An example of that is an open resolver installation.
+
+This module does not interact with the
+:ref:`serve-expired\*<unbound.conf.serve-expired>` and
+:ref:`prefetch<unbound.conf.prefetch>` options.
+
+
+@@UAHL@unbound.conf.ecs@send-client-subnet@@: *<IP address>*
+ Send client source address to this authority.
+ Append /num to indicate a classless delegation netblock, for example like
+ ``10.2.3.4/24`` or ``2001::11/64``.
+ Can be given multiple times.
+ Authorities not listed will not receive edns-subnet information, unless
+ domain in query is specified in
+ :ref:`client-subnet-zone<unbound.conf.ecs.client-subnet-zone>`.
+
+
+@@UAHL@unbound.conf.ecs@client-subnet-zone@@: *<domain>*
+ Send client source address in queries for this domain and its subdomains.
+ Can be given multiple times.
+ Zones not listed will not receive edns-subnet information, unless hosted by
+ authority specified in
+ :ref:`send-client-subnet<unbound.conf.ecs.send-client-subnet>`.
+
+
+@@UAHL@unbound.conf.ecs@client-subnet-always-forward@@: *<yes or no>*
+ Specify whether the ECS address check (configured using
+ :ref:`send-client-subnet<unbound.conf.ecs.send-client-subnet>`) is applied
+ for all queries, even if the triggering query contains an ECS record, or
+ only for queries for which the ECS record is generated using the querier
+ address (and therefore did not contain ECS data in the client query).
+ If enabled, the address check is skipped when the client query contains an
+ ECS record.
+ And the lookup in the regular cache is skipped.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.ecs@max-client-subnet-ipv6@@: *<number>*
+ Specifies the maximum prefix length of the client source address we are
+ willing to expose to third parties for IPv6.
+
+ Default: 56
+
+
+@@UAHL@unbound.conf.ecs@max-client-subnet-ipv4@@: *<number>*
+ Specifies the maximum prefix length of the client source address we are
+ willing to expose to third parties for IPv4.
+
+ Default: 24
+
+
+@@UAHL@unbound.conf.ecs@min-client-subnet-ipv6@@: *<number>*
+ Specifies the minimum prefix length of the IPv6 source mask we are willing
+ to accept in queries.
+ Shorter source masks result in REFUSED answers.
+ Source mask of 0 is always accepted.
+
+ Default: 0
+
+
+@@UAHL@unbound.conf.ecs@min-client-subnet-ipv4@@: *<number>*
+ Specifies the minimum prefix length of the IPv4 source mask we are willing
+ to accept in queries.
+ Shorter source masks result in REFUSED answers.
+ Source mask of 0 is always accepted.
+ Default: 0
+
+
+@@UAHL@unbound.conf.ecs@max-ecs-tree-size-ipv4@@: *<number>*
+ Specifies the maximum number of subnets ECS answers kept in the ECS radix
+ tree.
+ This number applies for each qname/qclass/qtype tuple.
+
+ Default: 100
+
+
+@@UAHL@unbound.conf.ecs@max-ecs-tree-size-ipv6@@: *<number>*
+ Specifies the maximum number of subnets ECS answers kept in the ECS radix
+ tree.
+ This number applies for each qname/qclass/qtype tuple.
+
+ Default: 100
+
+Opportunistic IPsec Support Module Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The IPsec module must be configured in the
+:ref:`module-config<unbound.conf.module-config>` directive, e.g.:
+
+.. code-block:: text
+
+ module-config: "ipsecmod validator iterator"
+
+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.
+If an answer was found, Unbound will call an external hook passing the
+following arguments:
+
+QNAME
+ Domain name of the A/AAAA and IPSECKEY query.
+ In string format.
+
+IPSECKEY TTL
+ TTL of the IPSECKEY RRset.
+
+A/AAAA
+ String of space separated IP addresses present in the A/AAAA RRset.
+ The IP addresses are in string format.
+
+IPSECKEY
+ String of space separated IPSECKEY RDATA present in the IPSECKEY RRset.
+ The IPSECKEY RDATA are in DNS presentation format.
+
+The A/AAAA answer is then cached and returned to the client.
+If the external hook was called the TTL changes to ensure it doesn't surpass
+:ref:`ipsecmod-max-ttl<unbound.conf.ipsecmod-max-ttl>`.
+
+The same procedure is also followed when
+:ref:`prefetch: yes<unbound.conf.prefetch>` is set, but the A/AAAA answer is
+given to the client before the hook is called.
+:ref:`ipsecmod-max-ttl<unbound.conf.ipsecmod-max-ttl>` ensures that the A/AAAA
+answer given from cache is still relevant for opportunistic IPsec.
+
+
+@@UAHL@unbound.conf@ipsecmod-enabled@@: *<yes or no>*
+ Specifies whether the IPsec module is enabled or not.
+ The IPsec module still needs to be defined in the
+ :ref:`module-config<unbound.conf.module-config>` directive.
+ This option facilitates turning on/off the module without
+ restarting/reloading Unbound.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf@ipsecmod-hook@@: *<filename>*
+ Specifies the external hook that Unbound will call with *system(3)*.
+ The file can be specified as an absolute/relative path.
+ The file needs the proper permissions to be able to be executed by the same
+ user that runs Unbound.
+ It must be present when the IPsec module is defined in the
+ :ref:`module-config<unbound.conf.module-config>` directive.
+
+
+@@UAHL@unbound.conf@ipsecmod-strict@@: *<yes or no>*
+ If enabled Unbound requires the external hook to return a success value of
+ 0.
+ Failing to do so Unbound will reply with SERVFAIL.
+ The A/AAAA answer will also not be cached.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@ipsecmod-max-ttl@@: *<seconds>*
+ Time to live maximum for A/AAAA cached records after calling the external
+ hook.
+
+ Default: 3600
+
+
+@@UAHL@unbound.conf@ipsecmod-ignore-bogus@@: *<yes or no>*
+ Specifies the behaviour of Unbound when the IPSECKEY answer is bogus.
+ If set to yes, the hook will be called and the A/AAAA answer will be
+ returned to the client.
+ If set to no, the hook will not be called and the answer to the A/AAAA
+ query will be SERVFAIL.
+ Mainly used for testing.
+
+ Default: no
+
+
+@@UAHL@unbound.conf@ipsecmod-allow@@: *<domain>*
+ Allow the IPsec module functionality for the domain so that the module
+ logic will be executed.
+ Can be given multiple times, for different domains.
+ If the option is not specified, all domains are treated as being allowed
+ (default).
+
+
+@@UAHL@unbound.conf@ipsecmod-whitelist@@: *<domain>*
+ Alternate syntax for :ref:`ipsecmod-allow<unbound.conf.ipsecmod-allow>`.
+
+Cache DB Module Options
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The Cache DB module must be configured in the
+:ref:`module-config<unbound.conf.module-config>` directive, e.g.:
+
+.. code-block:: text
+
+ module-config: "validator cachedb iterator"
+
+and be compiled into the daemon with ``--enable-cachedb``.
+
+If this module is enabled and configured, the specified backend database works
+as a second level cache; when Unbound cannot find an answer to a query in its
+built-in in-memory cache, it consults the specified backend.
+If it finds a valid answer in the backend, Unbound uses it to respond to the
+query without performing iterative DNS resolution.
+If Unbound cannot even find an answer in the backend, it resolves the query as
+usual, and stores the answer in the backend.
+
+This module interacts with the *serve-expired-\** options and will reply with
+expired data if Unbound is configured for that.
+
+If Unbound was built with ``--with-libhiredis`` on a system that has installed
+the hiredis C client library of Redis, then the ``redis`` backend can be used.
+This backend communicates with the specified Redis server over a TCP connection
+to store and retrieve cache data.
+It can be used as a persistent and/or shared cache backend.
+
+.. note::
+ Unbound never removes data stored in the Redis server, even if some data
+ have expired in terms of DNS TTL or the Redis server has cached too much
+ data; if necessary the Redis server must be configured to limit the cache
+ size, preferably with some kind of least-recently-used eviction policy.
+
+Additionally, the
+:ref:`redis-expire-records<unbound.conf.cachedb.redis-expire-records>` option
+can be used in order to set the relative DNS TTL of the message as timeout to
+the Redis records; keep in mind that some additional memory is used per key and
+that the expire information is stored as absolute Unix timestamps in Redis
+(computer time must be stable).
+
+This backend uses synchronous communication with the Redis server based on the
+assumption that the communication is stable and sufficiently fast.
+The thread waiting for a response from the Redis server cannot handle other DNS
+queries.
+Although the backend has the ability to reconnect to the server when the
+connection is closed unexpectedly and there is a configurable timeout in case
+the server is overly slow or hangs up, these cases are assumed to be very rare.
+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.
+
+
+@@UAHL@unbound.conf.cachedb@backend@@: *<backend name>*
+ Specify the backend database name.
+ The default database is the in-memory backend named ``testframe``, which,
+ as the name suggests, is not of any practical use.
+ Depending on the build-time configuration, ``redis`` backend may also be
+ used as described above.
+
+ Default: testframe
+
+
+@@UAHL@unbound.conf.cachedb@secret-seed@@: *"<secret string>"*
+ Specify a seed to calculate a hash value from query information.
+ This value will be used as the key of the corresponding answer for the
+ backend database and can be customized if the hash should not be
+ predictable operationally.
+ If the backend database is shared by multiple Unbound instances, all
+ instances must use the same secret seed.
+
+ Default: "default"
+
+
+@@UAHL@unbound.conf.cachedb@cachedb-no-store@@: *<yes or no>*
+ If the backend should be read from, but not written to.
+ This makes this instance not store dns messages in the backend.
+ But if data is available it is retrieved.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.cachedb@cachedb-check-when-serve-expired@@: *<yes or no>*
+ If enabled, the cachedb is checked before an expired response is returned.
+ When
+ :ref:`serve-expired<unbound.conf.serve-expired>`
+ is enabled, without
+ :ref:`serve-expired-client-timeout<unbound.conf.serve-expired-client-timeout>`
+ , it then does not immediately respond with an expired response from cache,
+ but instead first checks the cachedb for valid contents, and if so returns it.
+ If the cachedb also has no valid contents, the serve expired response is sent.
+ If also
+ :ref:`serve-expired-client-timeout<unbound.conf.serve-expired-client-timeout>`
+ is enabled, the expired response is delayed until the timeout expires.
+ Unless the lookup succeeds within the timeout.
+
+ Default: yes
+
+The following **cachedb:** options are specific to the ``redis`` backend.
+
+
+@@UAHL@unbound.conf.cachedb@redis-server-host@@: *<server address or name>*
+ The IP (either v6 or v4) address or domain name of the Redis server.
+ In general an IP address should be specified as otherwise Unbound will have
+ to resolve the name of the server every time it establishes a connection to
+ the server.
+
+ Default: 127.0.0.1
+
+
+@@UAHL@unbound.conf.cachedb@redis-server-port@@: *<port number>*
+ The TCP port number of the Redis server.
+
+ Default: 6379
+
+
+@@UAHL@unbound.conf.cachedb@redis-server-path@@: *<unix socket path>*
+ The unix socket path to connect to the Redis server.
+ Unix sockets may have better throughput than the IP address option.
+
+ Default: "" (disabled)
+
+
+@@UAHL@unbound.conf.cachedb@redis-server-password@@: *"<password>"*
+ The Redis AUTH password to use for the Redis server.
+ Only relevant if Redis is configured for client password authorisation.
+
+ Default: "" (disabled)
+
+
+@@UAHL@unbound.conf.cachedb@redis-timeout@@: *<msec>*
+ The period until when Unbound waits for a response from the Redis server.
+ If this timeout expires Unbound closes the connection, treats it as if the
+ Redis server does not have the requested data, and will try to re-establish
+ a new connection later.
+
+ Default: 100
+
+
+@@UAHL@unbound.conf.cachedb@redis-command-timeout@@: *<msec>*
+ The timeout to use for Redis commands, in milliseconds.
+ If ``0``, it uses the
+ :ref:`redis-timeout<unbound.conf.cachedb.redis-timeout>`
+ value.
+
+ Default: 0
+
+
+@@UAHL@unbound.conf.cachedb@redis-connect-timeout@@: *<msec>*
+ The timeout to use for Redis connection set up, in milliseconds.
+ If ``0``, it uses the
+ :ref:`redis-timeout<unbound.conf.cachedb.redis-timeout>`
+ value.
+
+ Default: 0
+
+
+@@UAHL@unbound.conf.cachedb@redis-expire-records@@: *<yes or no>*
+ If Redis record expiration is enabled.
+ If yes, Unbound sets timeout for Redis records so that Redis can evict keys
+ that have expired automatically.
+ If Unbound is configured with
+ :ref:`serve-expired<unbound.conf.serve-expired>` and
+ :ref:`serve-expired-ttl: 0<unbound.conf.serve-expired-ttl>`, this option is
+ internally reverted to "no".
+
+ .. note::
+ Redis SETEX support is required for this option (Redis >= 2.0.0).
+
+ Default: no
+
+
+@@UAHL@unbound.conf.cachedb@redis-logical-db@@: *<logical database index>*
+ The logical database in Redis to use.
+ These are databases in the same Redis instance sharing the same
+ configuration and persisted in the same RDB/AOF file.
+ If unsure about using this option, Redis documentation
+ (https://redis.io/commands/select/) suggests not to use a single Redis
+ instance for multiple unrelated applications.
+ The default database in Redis is 0 while other logical databases need to be
+ explicitly SELECT'ed upon connecting.
+
+ Default: 0
+
+
+@@UAHL@unbound.conf.cachedb@redis-replica-server-host@@: *<server address or name>*
+ The IP (either v6 or v4) address or domain name of the Redis server.
+ In general an IP address should be specified as otherwise Unbound will have
+ to resolve the name of the server every time it establishes a connection to
+ the server.
+
+ This server is treated as a read-only replica server
+ (https://redis.io/docs/management/replication/#read-only-replica).
+ If specified, all Redis read commands will go to this replica server, while
+ the write commands will go to the
+ :ref:`redis-server-host<unbound.conf.cachedb.redis-server-host>`.
+
+ Default: "" (disabled).
+
+
+@@UAHL@unbound.conf.cachedb@redis-replica-server-port@@: *<port number>*
+ The TCP port number of the Redis replica server.
+
+ Default: 6379
+
+
+@@UAHL@unbound.conf.cachedb@redis-replica-server-path@@: *<unix socket path>*
+ The unix socket path to connect to the Redis replica server.
+ Unix sockets may have better throughput than the IP address option.
+
+ Default: "" (disabled)
+
+
+@@UAHL@unbound.conf.cachedb@redis-replica-server-password@@: *"<password>"*
+ The Redis AUTH password to use for the Redis server.
+ Only relevant if Redis is configured for client password authorisation.
+
+ Default: "" (disabled)
+
+
+@@UAHL@unbound.conf.cachedb@redis-replica-timeout@@: *<msec>*
+ The period until when Unbound waits for a response from the Redis replica
+ server.
+ If this timeout expires Unbound closes the connection, treats it as if the
+ Redis server does not have the requested data, and will try to re-establish
+ a new connection later.
+
+ Default: 100
+
+
+@@UAHL@unbound.conf.cachedb@redis-replica-command-timeout@@: *<msec>*
+ The timeout to use for Redis replica commands, in milliseconds.
+ If ``0``, it uses the
+ :ref:`redis-replica-timeout<unbound.conf.cachedb.redis-replica-timeout>`
+ value.
+
+ Default: 0
+
+
+@@UAHL@unbound.conf.cachedb@redis-replica-connect-timeout@@: *<msec>*
+ The timeout to use for Redis replica connection set up, in milliseconds.
+ If ``0``, it uses the
+ :ref:`redis-replica-timeout<unbound.conf.cachedb.redis-replica-timeout>`
+ value.
+
+ Default: 0
+
+
+@@UAHL@unbound.conf.cachedb@redis-replica-logical-db@@: *<logical database index>*
+ Same as :ref:`redis-logical-db<unbound.conf.cachedb.redis-logical-db>` but
+ for the Redis replica server.
+
+ Default: 0
+
+
+.. _unbound.conf.dnstap:
+
+DNSTAP Logging Options
+^^^^^^^^^^^^^^^^^^^^^^
+
+DNSTAP support, when compiled in by using ``--enable-dnstap``, is 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
+connects per-process to the destination.
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-enable@@: *<yes or no>*
+ If dnstap is enabled.
+ If yes, it connects to the DNSTAP server and if any of the
+ *dnstap-log-..-messages:* options is enabled it sends logs for those
+ messages to the server.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-bidirectional@@: *<yes or no>*
+ Use frame streams in bidirectional mode to transfer DNSTAP messages.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-socket-path@@: *<file name>*
+ Sets the unix socket file name for connecting to the server that is
+ listening on that socket.
+
+ Default: @DNSTAP_SOCKET_PATH@
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-ip@@: *<IPaddress[@port]>*
+ If ``""``, the unix socket is used, if set with an IP address (IPv4 or
+ IPv6) that address is used to connect to the server.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-tls@@: *<yes or no>*
+ Set this to use TLS to connect to the server specified in
+ :ref:`dnstap-ip<unbound.conf.dnstap.dnstap-ip>`.
+ If set to no, TCP is used to connect to the server.
+
+ Default: yes
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-tls-server-name@@: *<name of TLS authentication>*
+ The TLS server name to authenticate the server with.
+ Used when :ref:`dnstap-tls: yes<unbound.conf.dnstap.dnstap-tls>` is set.
+ If ``""`` it is ignored.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-tls-cert-bundle@@: *<file name of cert bundle>*
+ The pem file with certs to verify the TLS server certificate.
+ If ``""`` the server default cert bundle is used, or the windows cert
+ bundle on windows.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-tls-client-key-file@@: *<file name>*
+ The client key file for TLS client authentication.
+ If ``""`` client authentication is not used.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-tls-client-cert-file@@: *<file name>*
+ The client cert file for TLS client authentication.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-send-identity@@: *<yes or no>*
+ If enabled, the server identity is included in the log messages.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-send-version@@: *<yes or no>*
+ If enabled, the server version if included in the log messages.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-identity@@: *<string>*
+ The identity to send with messages, if ``""`` the hostname is used.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-version@@: *<string>*
+ The version to send with messages, if ``""`` the package version is used.
+
+ Default: ""
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-sample-rate@@: *<number>*
+ The sample rate for log of messages, it logs only 1/N messages.
+ With 0 it is disabled.
+ This is useful in a high volume environment, where log functionality would
+ otherwise not be reliable.
+ For example 10 would spend only 1/10th time on logging, and 100 would only
+ spend a hundredth of the time on logging.
+
+ Default: 0 (disabled)
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-log-resolver-query-messages@@: *<yes or no>*
+ Enable to log resolver query messages.
+ These are messages from Unbound to upstream servers.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-log-resolver-response-messages@@: *<yes or no>*
+ Enable to log resolver response messages.
+ These are replies from upstream servers to Unbound.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-log-client-query-messages@@: *<yes or no>*
+ Enable to log client query messages.
+ These are client queries to Unbound.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-log-client-response-messages@@: *<yes or no>*
+ Enable to log client response messages.
+ These are responses from Unbound to clients.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-log-forwarder-query-messages@@: *<yes or no>*
+ Enable to log forwarder query messages.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.dnstap@dnstap-log-forwarder-response-messages@@: *<yes or no>*
+ Enable to log forwarder response messages.
+
+ Default: no
+
+.. _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.
+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.:
+
+.. code-block:: text
+
+ module-config: "respip validator iterator"
+
+QNAME, Response IP Address, nsdname, nsip and clientip triggers are supported.
+Supported actions are: NXDOMAIN, NODATA, PASSTHRU, DROP, Local Data, tcp-only
+and drop.
+RPZ QNAME triggers are applied after any
+:ref:`local-zone<unbound.conf.local-zone>` and before any
+:ref:`auth-zone<unbound.conf.auth>`.
+
+The RPZ zone is a regular DNS zone formatted with a SOA start record as usual.
+The items in the zone are entries, that specify what to act on (the trigger)
+and what to do (the action).
+The trigger to act on is recorded in the name, the action to do is recorded as
+the resource record.
+The names all end in the zone name, so you could type the trigger names without
+a trailing dot in the zonefile.
+
+An example RPZ record, that answers ``example.com`` with ``NXDOMAIN``:
+
+.. code-block:: text
+
+ example.com CNAME .
+
+The triggers are encoded in the name on the left
+
+.. code-block:: text
+
+ name query name
+ netblock.rpz-client-ip client IP address
+ netblock.rpz-ip response IP address in the answer
+ name.rpz-nsdname nameserver name
+ netblock.rpz-nsip nameserver IP address
+
+The netblock is written as ``<netblocklen>.<ip address in reverse>``.
+For IPv6 use ``'zz'`` for ``'::'``.
+Specify individual addresses with scope length of 32 or 128.
+For example, ``24.10.100.51.198.rpz-ip`` is ``198.51.100.10/24`` and
+``32.10.zz.db8.2001.rpz-ip`` is ``2001:db8:0:0:0:0:0:10/32``.
+
+The actions are specified with the record on the right
+
+.. code-block:: text
+
+ CNAME . nxdomain reply
+ CNAME *. nodata reply
+ CNAME rpz-passthru. do nothing, allow to continue
+ CNAME rpz-drop. the query is dropped
+ CNAME rpz-tcp-only. answer over TCP
+ A 192.0.2.1 answer with this IP address
+
+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.
+
+
+@@UAHL@unbound.conf.rpz@primary@@: *<IP address or host name>*
+ Where to download a copy of the zone from, with AXFR and IXFR.
+ Multiple primaries can be specified.
+ They are all tried if one fails.
+
+ To use a non-default port for DNS communication append ``'@'`` with the
+ port number.
+
+ You can append a ``'#'`` and a name, then AXFR over TLS can be used and the
+ TLS authentication certificates will be checked with that name.
+
+ If you combine the ``'@'`` and ``'#'``, the ``'@'`` comes first.
+ If you point it at another Unbound instance, it would not work because that
+ does not support AXFR/IXFR for the zone, but if you used
+ :ref:`url<unbound.conf.rpz.url>` to download the zonefile as a text file
+ from a webserver that would work.
+
+ If you specify the hostname, you cannot use the domain from the zonefile,
+ because it may not have that when retrieving that data, instead use a plain
+ IP address to avoid a circular dependency on retrieving that IP address.
+
+
+@@UAHL@unbound.conf.rpz@master@@: *<IP address or host name>*
+ Alternate syntax for :ref:`primary<unbound.conf.rpz.primary>`.
+
+
+@@UAHL@unbound.conf.rpz@url@@: *<url to zonefile>*
+ Where to download a zonefile for the zone.
+ With HTTP or HTTPS.
+ An example for the url is:
+
+ .. code-block:: text
+
+ http://www.example.com/example.org.zone
+
+ Multiple url statements can be given, they are tried in turn.
+
+ If only urls are given the SOA refresh timer is used to wait for making new
+ downloads.
+ If also primaries are listed, the primaries are first probed with UDP SOA
+ queries to see if the SOA serial number has changed, reducing the number of
+ downloads.
+ If none of the URLs work, the primaries are tried with IXFR and AXFR.
+
+ For HTTPS, the :ref:`tls-cert-bundle<unbound.conf.tls-cert-bundle>` and
+ the hostname from the url are used to authenticate the connection.
+
+
+@@UAHL@unbound.conf.rpz@allow-notify@@: *<IP address or host name or netblockIP/prefix>*
+ With :ref:`allow-notify<unbound.conf.rpz.allow-notify>` you can specify
+ additional sources of notifies.
+ When notified, the server attempts to first probe and then zone transfer.
+ If the notify is from a primary, it first attempts that primary.
+ Otherwise other primaries are attempted.
+ If there are no primaries, but only urls, the file is downloaded when
+ notified.
+
+ .. note::
+ The primaries from :ref:`primary<unbound.conf.rpz.primary>` and
+ :ref:`url<unbound.conf.rpz.url>` statements are allowed notify by
+ default.
+
+
+@@UAHL@unbound.conf.rpz@zonefile@@: *<filename>*
+ The filename where the zone is stored.
+ 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).
+
+
+@@UAHL@unbound.conf.rpz@rpz-action-override@@: *<action>*
+ Always use this RPZ action for matching triggers from this zone.
+ Possible actions are: *nxdomain*, *nodata*, *passthru*, *drop*, *disabled*
+ and *cname*.
+
+
+@@UAHL@unbound.conf.rpz@rpz-cname-override@@: *<domain>*
+ The CNAME target domain to use if the cname action is configured for
+ :ref:`rpz-action-override<unbound.conf.rpz.rpz-action-override>`.
+
+
+@@UAHL@unbound.conf.rpz@rpz-log@@: *<yes or no>*
+ Log all applied RPZ actions for this RPZ zone.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.rpz@rpz-log-name@@: *<name>*
+ Specify a string to be part of the log line, for easy referencing.
+
+
+@@UAHL@unbound.conf.rpz@rpz-signal-nxdomain-ra@@: *<yes or no>*
+ Signal when a query is blocked by the RPZ with NXDOMAIN with an unset RA
+ flag.
+ This allows certain clients, like dnsmasq, to infer that the domain is
+ externally blocked.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.rpz@for-downstream@@: *<yes or no>*
+ If enabled the zone is authoritatively answered for and queries for the RPZ
+ zone information are answered to downstream clients.
+ This is useful for monitoring scripts, that can then access the SOA
+ information to check if the RPZ information is up to date.
+
+ Default: no
+
+
+@@UAHL@unbound.conf.rpz@tags@@: *"<list of tags>"*
+ Limit the policies from this RPZ clause 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
+ :ref:`access-control-tag<unbound.conf.access-control-tag>` or
+ :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
+ all clients.
+
+Memory Control Example
+----------------------
+
+In the example config settings below memory usage is reduced.
+Some service levels are lower, notable very large data and a high TCP load are
+no longer supported.
+Very large data and high TCP loads are exceptional for the DNS.
+DNSSEC validation is enabled, just add trust anchors.
+If you do not have to worry about programs using more than 3 Mb of memory, the
+below example is not for you.
+Use the defaults to receive full service, which on BSD-32bit tops out at 30-40
+Mb after heavy usage.
+
+.. code-block:: text
+
+ # example settings that reduce memory usage
+ server:
+ num-threads: 1
+ outgoing-num-tcp: 1 # this limits TCP service, uses less buffers.
+ incoming-num-tcp: 1
+ outgoing-range: 60 # uses less memory, but less performance.
+ msg-buffer-size: 8192 # note this limits service, 'no huge stuff'.
+ msg-cache-size: 100k
+ msg-cache-slabs: 1
+ rrset-cache-size: 100k
+ rrset-cache-slabs: 1
+ infra-cache-numhosts: 200
+ infra-cache-slabs: 1
+ key-cache-size: 100k
+ key-cache-slabs: 1
+ neg-cache-size: 10k
+ num-queries-per-thread: 30
+ target-fetch-policy: "2 1 0 0 0 0"
+ harden-large-queries: "yes"
+ harden-short-bufsize: "yes"
+
+Files
+-----
+
+@UNBOUND_RUN_DIR@
+ default Unbound working directory.
+
+@UNBOUND_CHROOT_DIR@
+ default *chroot(2)* location.
+
+@ub_conf_file@
+ Unbound configuration file.
+
+@UNBOUND_PIDFILE@
+ default Unbound pidfile with process ID of the running daemon.
+
+unbound.log
+ Unbound log file.
+ Default is to log to *syslog(3)*.
+
+See Also
+--------
+
+:doc:`unbound(8)</manpages/unbound>`,
+:doc:`unbound-checkonf(8)</manpages/unbound-checkconf>`.
--- /dev/null
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+..
+ WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE
+
+..
+ IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE
+
+..
+ IT HELPS PEOPLE DIFFING THE CHANGES
+
+.. program:: unbound
+
+unbound(8)
+==========
+
+Synopsis
+--------
+
+**unbound** [``-hdpv``] [``-c <cfgfile>``]
+
+Description
+-----------
+
+``unbound`` is a caching DNS resolver.
+
+It uses a built in list of authoritative nameservers for the root zone (``.``),
+the so called root hints.
+On receiving a DNS query it will ask the root nameservers for an answer and
+will in almost all cases receive a delegation to a top level domain (TLD)
+authoritative nameserver.
+It will then ask that nameserver for an answer.
+It will recursively continue until an answer is found or no answer is available
+(NXDOMAIN).
+For performance and efficiency reasons that answer is cached for a certain time
+(the answer's time-to-live or TTL).
+A second query for the same name will then be answered from the cache.
+Unbound can also do DNSSEC validation.
+
+To use a locally running Unbound for resolving put:
+
+.. code-block:: text
+
+ nameserver 127.0.0.1
+
+into *resolv.conf(5)*.
+
+If authoritative DNS is needed as well using :external+nsd:doc:`manpages/nsd`,
+careful setup is required because authoritative nameservers and resolvers are
+using the same port number (53).
+
+The available options are:
+
+.. option:: -h
+
+ Show the version number and commandline option help, and exit.
+
+.. option:: -c <cfgfile>
+
+ Set the config file with settings for unbound to read instead of reading the
+ file at the default location, :file:`@ub_conf_file@`.
+ The syntax is described in :doc:`unbound.conf(5)</manpages/unbound.conf>`.
+
+.. option:: -d
+
+ Debug flag: do not fork into the background, but stay attached to the
+ console.
+ This flag will also delay writing to the log file until the thread-spawn
+ time, so that most config and setup errors appear on stderr.
+ If given twice or more, logging does not switch to the log file or to
+ syslog, but the log messages are printed to stderr all the time.
+
+.. option:: -p
+
+ Don't use a pidfile.
+ This argument should only be used by supervision systems which can ensure
+ that only one instance of Unbound will run concurrently.
+
+.. option:: -v
+
+ Increase verbosity.
+ If given multiple times, more information is logged.
+ This is in addition to the verbosity (if any) from the config file.
+
+.. option:: -V
+
+ Show the version number and build options, and exit.
+
+See Also
+--------
+
+:doc:`unbound.conf(5)</manpages/unbound.conf>`,
+:doc:`unbound-checkconf(8)</manpages/unbound-checkconf>`,
+:external+nsd:doc:`manpages/nsd`.
projects / thirdparty / unbound.git / commitdiff
