upstream/unbound
1
0
Fork 0
mirror of https://github.com/NLnetLabs/unbound.git synced 2025-12-23 16:20:26 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

- Add missing configure flags for optional features in the

Browse source 
documentation.
- Fix Unbound capitalization in the documentation.
This commit is contained in:
George Thessalonikefs 2021-12-13 12:46:08 +01:00
parent 83c712ca60
commit 983c716feb
8 changed files with 182 additions and 168 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
doc/Changelog
View file

@ -1,3 +1,8 @@
13 December 2021: George
- Add missing configure flags for optional features in the
documentation.
- Fix Unbound capitalization in the documentation.
13 December 2021: Wouter 13 December 2021: Wouter
- Fix to pick up other class local zone information before unlock. - Fix to pick up other class local zone information before unlock.

49
doc/example.conf.in
View file

@ -82,13 +82,13 @@ server:
# num-queries-per-thread, or, use as many as the OS will allow you. # num-queries-per-thread, or, use as many as the OS will allow you.
# outgoing-range: 4096 # outgoing-range: 4096
# permit unbound to use this port number or port range for # permit Unbound to use this port number or port range for
# making outgoing queries, using an outgoing interface. # making outgoing queries, using an outgoing interface.
# outgoing-port-permit: 32768 # outgoing-port-permit: 32768
# deny unbound the use this of port number or port range for # deny Unbound the use this of port number or port range for
# making outgoing queries, using an outgoing interface. # making outgoing queries, using an outgoing interface.
# Use this to make sure unbound does not grab a UDP port that some # Use this to make sure Unbound does not grab a UDP port that some
# other server on this computer needs. The default is to avoid # other server on this computer needs. The default is to avoid
# IANA-assigned port numbers. # IANA-assigned port numbers.
# If multiple outgoing-port-permit and outgoing-port-avoid options # If multiple outgoing-port-permit and outgoing-port-avoid options
@ -254,7 +254,7 @@ server:
# use-systemd: no # use-systemd: no
# Detach from the terminal, run in background, "yes" or "no". # Detach from the terminal, run in background, "yes" or "no".
# Set the value to "no" when unbound runs as systemd service. # Set the value to "no" when Unbound runs as systemd service.
# do-daemonize: yes # do-daemonize: yes
# control which clients are allowed to make (recursive) queries # control which clients are allowed to make (recursive) queries
@ -307,7 +307,7 @@ server:
# The pid file can be absolute and outside of the chroot, it is # The pid file can be absolute and outside of the chroot, it is
# written just prior to performing the chroot and dropping permissions. # written just prior to performing the chroot and dropping permissions.
# #
# Additionally, unbound may need to access /dev/urandom (for entropy). # Additionally, Unbound may need to access /dev/urandom (for entropy).
# How to do this is specific to your OS. # How to do this is specific to your OS.
# #
# If you give "" no chroot is performed. The path must not end in a /. # If you give "" no chroot is performed. The path must not end in a /.
@ -517,7 +517,7 @@ server:
# Use several entries, one per domain name, to track multiple zones. # Use several entries, one per domain name, to track multiple zones.
# #
# If you want to perform DNSSEC validation, run unbound-anchor before # If you want to perform DNSSEC validation, run unbound-anchor before
# you start unbound (i.e. in the system boot scripts). # you start Unbound (i.e. in the system boot scripts).
# And then enable the auto-trust-anchor-file config item. # And then enable the auto-trust-anchor-file config item.
# Please note usage of unbound-anchor root anchor is at your own risk # Please note usage of unbound-anchor root anchor is at your own risk
# and under the terms of our LICENSE (see that file in the source). # and under the terms of our LICENSE (see that file in the source).
@ -585,7 +585,7 @@ server:
# val-permissive-mode: no # val-permissive-mode: no
# Ignore the CD flag in incoming queries and refuse them bogus data. # Ignore the CD flag in incoming queries and refuse them bogus data.
# Enable it if the only clients of unbound are legacy servers (w2008) # Enable it if the only clients of Unbound are legacy servers (w2008)
# that set CD but cannot validate themselves. # that set CD but cannot validate themselves.
# ignore-cd-flag: no # ignore-cd-flag: no
@ -615,7 +615,7 @@ server:
# Return the original TTL as received from the upstream name server rather # Return the original TTL as received from the upstream name server rather
# than the decrementing TTL as stored in the cache. Enabling this feature # than the decrementing TTL as stored in the cache. Enabling this feature
# does not impact cache expiry, it only changes the TTL unbound embeds in # does not impact cache expiry, it only changes the TTL Unbound embeds in
# responses to queries. Note that enabling this feature implicitly disables # responses to queries. Note that enabling this feature implicitly disables
# enforcement of the configured minimum and maximum TTL. # enforcement of the configured minimum and maximum TTL.
# serve-original-ttl: no # serve-original-ttl: no
@ -709,9 +709,9 @@ server:
# Add example.com into ipset # Add example.com into ipset
# local-zone: "example.com" ipset # local-zone: "example.com" ipset
# If unbound is running service for the local host then it is useful # If Unbound is running service for the local host then it is useful
# to perform lan-wide lookups to the upstream, and unblock the # to perform lan-wide lookups to the upstream, and unblock the
# long list of local-zones above. If this unbound is a dns server # long list of local-zones above. If this Unbound is a dns server
# for a network of computers, disabled is better and stops information # for a network of computers, disabled is better and stops information
# leakage of local lan information. # leakage of local lan information.
# unblock-lan-zones: no # unblock-lan-zones: no
@ -889,7 +889,7 @@ server:
# the number of servers that will be used in the fast server selection. # the number of servers that will be used in the fast server selection.
# fast-server-num: 3 # fast-server-num: 3
# Specific options for ipsecmod. unbound needs to be configured with # Specific options for ipsecmod. Unbound needs to be configured with
# --enable-ipsecmod for these to take effect. # --enable-ipsecmod for these to take effect.
# #
# Enable or disable ipsecmod (it still needs to be defined in # Enable or disable ipsecmod (it still needs to be defined in
@ -901,7 +901,7 @@ server:
# listed in module-config (above). # listed in module-config (above).
# ipsecmod-hook: "./my_executable" # ipsecmod-hook: "./my_executable"
# #
# When enabled unbound will reply with SERVFAIL if the return value of # When enabled Unbound will reply with SERVFAIL if the return value of
# the ipsecmod-hook is not 0. # the ipsecmod-hook is not 0.
# ipsecmod-strict: no # ipsecmod-strict: no
# #
@ -966,10 +966,10 @@ remote-control:
# For local sockets this option is ignored, and TLS is not used. # For local sockets this option is ignored, and TLS is not used.
# control-use-cert: "yes" # control-use-cert: "yes"
# unbound server key file. # Unbound server key file.
# server-key-file: "@UNBOUND_RUN_DIR@/unbound_server.key" # server-key-file: "@UNBOUND_RUN_DIR@/unbound_server.key"
# unbound server certificate file. # Unbound server certificate file.
# server-cert-file: "@UNBOUND_RUN_DIR@/unbound_server.pem" # server-cert-file: "@UNBOUND_RUN_DIR@/unbound_server.pem"
# unbound-control key file. # unbound-control key file.
@ -1072,8 +1072,9 @@ remote-control:
# local-zone: "example.com" refuse # local-zone: "example.com" refuse
# DNSCrypt # DNSCrypt
# To enable, use --enable-dnscrypt to configure before compiling.
# Caveats: # Caveats:
# 1. the keys/certs cannot be produced by unbound. You can use dnscrypt-wrapper # 1. the keys/certs cannot be produced by Unbound. You can use dnscrypt-wrapper
# for this: https://github.com/cofyc/dnscrypt-wrapper/blob/master/README.md#usage # for this: https://github.com/cofyc/dnscrypt-wrapper/blob/master/README.md#usage
# 2. dnscrypt channel attaches to an interface. you MUST set interfaces to # 2. dnscrypt channel attaches to an interface. you MUST set interfaces to
# listen on `dnscrypt-port` with the follo0wing snippet: # listen on `dnscrypt-port` with the follo0wing snippet:
@ -1092,7 +1093,9 @@ remote-control:
# dnscrypt-provider-cert: /path/unbound-conf/keys2/1.cert # dnscrypt-provider-cert: /path/unbound-conf/keys2/1.cert
# CacheDB # CacheDB
# Enable external backend DB as auxiliary cache. Specify the backend name # External backend DB as auxiliary cache.
# To enable, use --enable-cachedb to configure before compiling.
# Specify the backend name
# (default is "testframe", which has no use other than for debugging and # (default is "testframe", which has no use other than for debugging and
# testing) and backend-specific options. The 'cachedb' module must be # testing) and backend-specific options. The 'cachedb' module must be
# included in module-config, just before the iterator module. # included in module-config, just before the iterator module.
@ -1102,6 +1105,7 @@ remote-control:
# secret-seed: "default" # secret-seed: "default"
# #
# # For "redis" backend: # # For "redis" backend:
# # (to enable, use --with-libhiredis to configure before compiling)
# # redis server's IP address or host name # # redis server's IP address or host name
# redis-server-host: 127.0.0.1 # redis-server-host: 127.0.0.1
# # redis server's TCP port # # redis server's TCP port
@ -1113,7 +1117,9 @@ remote-control:
# IPSet # IPSet
# Add specify domain into set via ipset. # Add specify domain into set via ipset.
# Note: To enable ipset unbound needs to run as root user. # To enable:
# o use --enable-ipset to configure before compiling;
# o Unbound then needs to run as root user.
# ipset: # ipset:
# # set name for ip v4 addresses # # set name for ip v4 addresses
# name-v4: "list-v4" # name-v4: "list-v4"
@ -1121,9 +1127,10 @@ remote-control:
# name-v6: "list-v6" # name-v6: "list-v6"
# #
# Dnstap logging support, if compiled in. To enable, set the dnstap-enable # Dnstap logging support, if compiled in by using --enable-dnstap to configure.
# to yes and also some of dnstap-log-..-messages to yes. And select an # To enable, set the dnstap-enable to yes and also some of
# upstream log destination, by socket path, TCP or TLS destination. # dnstap-log-..-messages to yes. And select an upstream log destination, by
# socket path, TCP or TLS destination.
# dnstap: # dnstap:
# dnstap-enable: no # dnstap-enable: no
# # if set to yes frame streams will be used in bidirectional mode # # if set to yes frame streams will be used in bidirectional mode
@ -1136,7 +1143,7 @@ remote-control:
# dnstap-tls: yes # dnstap-tls: yes
# # name for authenticating the upstream server. or "" disabled. # # name for authenticating the upstream server. or "" disabled.
# dnstap-tls-server-name: "" # dnstap-tls-server-name: ""
# # if "", it uses the cert bundle from the main unbound config. # # if "", it uses the cert bundle from the main Unbound config.
# dnstap-tls-cert-bundle: "" # dnstap-tls-cert-bundle: ""
# # key file for client authentication, or "" disabled. # # key file for client authentication, or "" disabled.
# dnstap-tls-client-key-file: "" # dnstap-tls-client-key-file: ""

6
doc/unbound-checkconf.8.in
View file

@ -9,7 +9,7 @@
.\" .\"
.SH "NAME" .SH "NAME"
unbound\-checkconf unbound\-checkconf
\- Check unbound configuration file for errors. \- Check Unbound configuration file for errors.
.SH "SYNOPSIS" .SH "SYNOPSIS"
.B unbound\-checkconf .B unbound\-checkconf
.RB [ \-h ] .RB [ \-h ]
@ -38,7 +38,7 @@ If given, after checking the config file the value of this option is
printed to stdout. For "" (disabled) options an empty line is printed. printed to stdout. For "" (disabled) options an empty line is printed.
.TP .TP
.I cfgfile .I cfgfile
The config file to read with settings for unbound. It is checked. The config file to read with settings for Unbound. It is checked.
If omitted, the config file at the default location is checked. If omitted, the config file at the default location is checked.
.SH "EXIT CODE" .SH "EXIT CODE"
The unbound\-checkconf program exits with status code 1 on error, The unbound\-checkconf program exits with status code 1 on error,
@ -46,7 +46,7 @@ The unbound\-checkconf program exits with status code 1 on error,
.SH "FILES" .SH "FILES"
.TP .TP
.I @ub_conf_file@ .I @ub_conf_file@
unbound configuration file. Unbound configuration file.
.SH "SEE ALSO" .SH "SEE ALSO"
\fIunbound.conf\fR(5), \fIunbound.conf\fR(5),
\fIunbound\fR(8). \fIunbound\fR(8).

34
doc/unbound-control.8.in
View file

@ -22,7 +22,7 @@
.SH "DESCRIPTION" .SH "DESCRIPTION"
.B Unbound\-control .B Unbound\-control
performs remote administration on the \fIunbound\fR(8) DNS server. performs remote administration on the \fIunbound\fR(8) DNS server.
It reads the configuration file, contacts the unbound server over SSL It reads the configuration file, contacts the Unbound server over SSL
sends the command and displays the result. sends the command and displays the result.
.P .P
The available options are: The available options are:
@ -44,7 +44,7 @@ quiet, if the option is given it does not print anything if it works ok.
There are several commands that the server understands. There are several commands that the server understands.
.TP .TP
.B start .B start
Start the server. Simply execs \fIunbound\fR(8). The unbound executable 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 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. with the config file specified using \fI\-c\fR or the default config file.
.TP .TP
@ -187,7 +187,7 @@ 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 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, 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 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. in libunbound, where all values work because Unbound has not been initialized.
.IP .IP
The values that work are: statistics\-interval, statistics\-cumulative, 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,
@ -227,31 +227,31 @@ List the local data RRs in use. The resource records are printed.
.TP .TP
.B insecure_add \fIzone .B insecure_add \fIzone
Add a \fBdomain\-insecure\fR for the given zone, like the statement in unbound.conf. 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 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. still be bogus, use \fBflush_zone\fR to remove it), does not affect the config file.
.TP .TP
.B insecure_remove \fIzone .B insecure_remove \fIzone
Removes domain\-insecure for the given zone. Removes domain\-insecure for the given zone.
.TP .TP
.B forward_add \fR[\fI+i\fR] \fIzone addr ... .B forward_add \fR[\fI+i\fR] \fIzone addr ...
Add a new forward zone to running unbound. With +i option also adds a 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 \fIdomain\-insecure\fR for the zone (so it can resolve insecurely if you have
a DNSSEC root trust anchor configured for other names). a DNSSEC root trust anchor configured for other names).
The addr can be IP4, IP6 or nameserver names, like \fIforward-zone\fR config The addr can be IP4, IP6 or nameserver names, like \fIforward-zone\fR config
in unbound.conf. in unbound.conf.
.TP .TP
.B forward_remove \fR[\fI+i\fR] \fIzone .B forward_remove \fR[\fI+i\fR] \fIzone
Remove a forward zone from running unbound. The +i also removes a Remove a forward zone from running Unbound. The +i also removes a
\fIdomain\-insecure\fR for the zone. \fIdomain\-insecure\fR for the zone.
.TP .TP
.B stub_add \fR[\fI+ip\fR] \fIzone addr ... .B stub_add \fR[\fI+ip\fR] \fIzone addr ...
Add a new stub zone to running unbound. With +i option also adds a 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, \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 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. names, like the \fIstub-zone\fR config in unbound.conf.
.TP .TP
.B stub_remove \fR[\fI+i\fR] \fIzone .B stub_remove \fR[\fI+i\fR] \fIzone
Remove a stub zone from running unbound. The +i also removes a Remove a stub zone from running Unbound. The +i also removes a
\fIdomain\-insecure\fR for the zone. \fIdomain\-insecure\fR for the zone.
.TP .TP
.B forward \fR[\fIoff\fR | \fIaddr ...\fR ] .B forward \fR[\fIoff\fR | \fIaddr ...\fR ]
@ -296,7 +296,7 @@ status, indicating if the zone is expired and current serial number.
Reload the auth zone from zonefile. The zonefile is read in overwriting Reload the auth zone from zonefile. The zonefile is read in overwriting
the current contents of the zone in memory. This changes the auth zone the current contents of the zone in memory. This changes the auth zone
contents itself, not the cache contents. Such cache contents exists if 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 you set Unbound to validate with for-upstream yes and that can be cleared
with \fBflush_zone\fR \fIzone\fR. with \fBflush_zone\fR \fIzone\fR.
.TP .TP
.B auth_zone_transfer \fIzone\fR .B auth_zone_transfer \fIzone\fR
@ -544,27 +544,27 @@ The total number of queries over all threads with query opcode QUERY.
Also printed for other opcodes, UPDATE, ... Also printed for other opcodes, UPDATE, ...
.TP .TP
.I num.query.tcp .I num.query.tcp
Number of queries that were made using TCP towards the unbound server. Number of queries that were made using TCP towards the Unbound server.
.TP .TP
.I num.query.tcpout .I num.query.tcpout
Number of queries that the unbound server made using TCP outgoing towards Number of queries that the Unbound server made using TCP outgoing towards
other servers. other servers.
.TP .TP
.I num.query.tls .I num.query.tls
Number of queries that were made using TLS towards the unbound server. Number of queries that were made using TLS towards the Unbound server.
These are also counted in num.query.tcp, because TLS uses TCP. These are also counted in num.query.tcp, because TLS uses TCP.
.TP .TP
.I num.query.tls.resume .I num.query.tls.resume
Number of TLS session resumptions, these are queries over TLS towards Number of TLS session resumptions, these are queries over TLS towards
the unbound server where the client negotiated a TLS session resumption key. the Unbound server where the client negotiated a TLS session resumption key.
.TP .TP
.I num.query.https .I num.query.https
Number of queries that were made using HTTPS towards the unbound server. 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 These are also counted in num.query.tcp and num.query.tls, because HTTPS
uses TLS and TCP. uses TLS and TCP.
.TP .TP
.I num.query.ipv6 .I num.query.ipv6
Number of queries that were made using IPv6 towards the unbound server. Number of queries that were made using IPv6 towards the Unbound server.
.TP .TP
.I num.query.flags.RD .I num.query.flags.RD
The number of queries that had the RD flag set in the header. The number of queries that had the RD flag set in the header.
@ -644,7 +644,7 @@ per delegation point, and their validation status.
.I dnscrypt_shared_secret.cache.count .I dnscrypt_shared_secret.cache.count
The number of items in the shared secret cache. These are precomputed shared 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 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 are CPU intensive and this cache allows Unbound to avoid recomputing the
shared secret when multiple dnscrypt queries are sent from the same client. shared secret when multiple dnscrypt queries are sent from the same client.
.TP .TP
.I dnscrypt_nonce.cache.count .I dnscrypt_nonce.cache.count
@ -689,7 +689,7 @@ disabled, and cname\-override.
.SH "FILES" .SH "FILES"
.TP .TP
.I @ub_conf_file@ .I @ub_conf_file@
unbound configuration file. Unbound configuration file.
.TP .TP
.I @UNBOUND_RUN_DIR@ .I @UNBOUND_RUN_DIR@
directory with private keys (unbound_server.key and unbound_control.key) and directory with private keys (unbound_server.key and unbound_control.key) and

4
doc/unbound-host.1.in
View file

@ -28,12 +28,12 @@
.I hostname .I hostname
.SH "DESCRIPTION" .SH "DESCRIPTION"
.B Unbound\-host .B Unbound\-host
uses the unbound validating resolver to query for the hostname and display uses the Unbound validating resolver to query for the hostname and display
results. With the \fB\-v\fR option it displays validation results. With the \fB\-v\fR option it displays validation
status: secure, insecure, bogus (security failure). status: secure, insecure, bogus (security failure).
.P .P
By default it reads no configuration file whatsoever. It attempts to reach 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 the internet root servers. With \fB\-C\fR an Unbound config file and with
\fB\-r\fR resolv.conf can be read. \fB\-r\fR resolv.conf can be read.
.P .P
The available options are: The available options are:

4
doc/unbound.8.in
View file

@ -57,7 +57,7 @@ The available options are:
Show the version number and commandline option help, and exit. Show the version number and commandline option help, and exit.
.TP .TP
.B \-c\fI cfgfile .B \-c\fI cfgfile
Set the config file with settings for unbound to read instead of reading the 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 file at the default location, @ub_conf_file@. The syntax is
described in \fIunbound.conf\fR(5). described in \fIunbound.conf\fR(5).
.TP .TP
@ -70,7 +70,7 @@ or to syslog, but the log messages are printed to stderr all the time.
.TP .TP
.B \-p .B \-p
Don't use a pidfile. This argument should only be used by supervision 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 systems which can ensure that only one instance of Unbound will run
concurrently. concurrently.
.TP .TP
.B \-v .B \-v

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

@ -104,7 +104,7 @@ requestlist statistics are printed for every interval (but can be 0).
This is because the median calculation requires data to be present. This is because the median calculation requires data to be present.
.TP .TP
.B statistics\-cumulative: \fI<yes or no> .B statistics\-cumulative: \fI<yes or no>
If enabled, statistics are cumulative since starting unbound, without clearing If enabled, statistics are cumulative since starting Unbound, without clearing
the statistics counters after logging the statistics. Default is no. the statistics counters after logging the statistics. Default is no.
.TP .TP
.B extended\-statistics: \fI<yes or no> .B extended\-statistics: \fI<yes or no>
@ -136,7 +136,7 @@ Same as interface: (for ease of compatibility with nsd.conf).
Listen on all addresses on all (current and future) interfaces, detect the 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 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, but this option services all interfaces whilst with
ip\-transparent you can select which (future) interfaces unbound provides ip\-transparent you can select which (future) interfaces Unbound provides
service on. This feature is experimental, and needs support in your OS for service on. This feature is experimental, and needs support in your OS for
particular socket options. Default value is no. particular socket options. Default value is no.
.TP .TP
@ -154,7 +154,7 @@ sent via a random outgoing interface to counter spoofing.
If an IPv6 netblock is specified instead of an individual IPv6 address, If an IPv6 netblock is specified instead of an individual IPv6 address,
outgoing UDP queries will use a randomised source address taken from the 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 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 host running Unbound, and requires OS support for unprivileged non-local binds
(currently only supported on Linux). Several netblocks may be specified with (currently only supported on Linux). Several netblocks may be specified with
multiple multiple
.B outgoing\-interface: .B outgoing\-interface:
@ -174,7 +174,7 @@ numbers need extra resources from the operating system. For performance a
very large value is best, use libevent to make this possible. very large value is best, use libevent to make this possible.
.TP .TP
.B outgoing\-port\-permit: \fI<port number or range> .B outgoing\-port\-permit: \fI<port number or range>
Permit unbound to open this port or range of ports for use to send queries. 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 A larger number of permitted outgoing ports increases resilience against
spoofing attempts. Make sure these ports are not needed by other daemons. 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. By default only ports above 1024 that have not been assigned by IANA are used.
@ -187,8 +187,8 @@ processing starts with the non IANA allocated ports above 1024 in the set
of allowed ports. of allowed ports.
.TP .TP
.B outgoing\-port\-avoid: \fI<port number or range> .B outgoing\-port\-avoid: \fI<port number or range>
Do not permit unbound to open this port or range of ports for use to send 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 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. 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. 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. Give a port number or a range of the form "low\-high", without spaces.
@ -289,7 +289,7 @@ 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 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 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 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 "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 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. 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 On OpenBSD change header and recompile kernel. On Solaris ndd \-set
@ -302,7 +302,7 @@ in answer traffic, otherwise 'send: resource temporarily unavailable'
can get logged, the buffer overrun is also visible by netstat \-su. can get logged, the buffer overrun is also visible by netstat \-su.
Default is 0 (use system value). Specify the number of bytes to ask Default is 0 (use system value). Specify the number of bytes to ask
for, try "4m" on a very busy server. The OS caps it at a maximum, on for, try "4m" on a very busy server. The OS caps it at a maximum, on
linux unbound needs root permission to bypass the limit, or the admin 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 can use sysctl net.core.wmem_max. On BSD, Solaris changes are similar
to so\-rcvbuf. to so\-rcvbuf.
.TP .TP
@ -319,18 +319,18 @@ At extreme load it could be better to turn it off to distribute the queries
evenly, reported for Linux systems (4.4.x). evenly, reported for Linux systems (4.4.x).
.TP .TP
.B ip\-transparent: \fI<yes or no> .B ip\-transparent: \fI<yes or no>
If yes, then use IP_TRANSPARENT socket option on sockets where unbound If yes, then use IP_TRANSPARENT socket option on sockets where Unbound
is listening for incoming traffic. Default no. Allows you to bind to is listening for incoming traffic. Default no. Allows you to bind to
non\-local interfaces. For example for non\-existent IP addresses that non\-local interfaces. For example for non\-existent IP addresses that
are going to exist later on, with host failover configuration. This is are going to exist later on, with host failover configuration. This is
a lot like interface\-automatic, but that one services all interfaces a lot like interface\-automatic, but that one services all interfaces
and with this option you can select which (future) interfaces unbound and with this option you can select which (future) interfaces Unbound
provides service on. This option needs unbound to be started with root provides service on. This option needs Unbound to be started with root
permissions on some systems. The option uses IP_BINDANY on FreeBSD systems permissions on some systems. The option uses IP_BINDANY on FreeBSD systems
and SO_BINDANY on OpenBSD systems. and SO_BINDANY on OpenBSD systems.
.TP .TP
.B ip\-freebind: \fI<yes or no> .B ip\-freebind: \fI<yes or no>
If yes, then use IP_FREEBIND socket option on sockets where unbound If yes, then use IP_FREEBIND socket option on sockets where Unbound
is listening to incoming traffic. Default no. Allows you to bind to 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 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 interface or IP address is down. Exists only on Linux, where the similar
@ -560,7 +560,7 @@ service. Can list multiple, each on a new statement.
.TP .TP
.B tls-session-ticket-keys: \fI<file> .B tls-session-ticket-keys: \fI<file>
If not "", lists files with 80 bytes of random contents that are used to If not "", lists files with 80 bytes of random contents that are used to
perform TLS session resumption for clients using the unbound server. perform TLS session resumption for clients using the Unbound server.
These files contain the secret key for the TLS session tickets. These files contain the secret key for the TLS session tickets.
First key use to encrypt and decrypt 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, Other keys use to decrypt only. With this you can roll over to new keys,
@ -642,8 +642,8 @@ Enable or disable systemd socket activation.
Default is no. Default is no.
.TP .TP
.B do\-daemonize: \fI<yes or no> .B do\-daemonize: \fI<yes or no>
Enable or disable whether the unbound server forks into the background as 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. a daemon. Set the value to \fIno\fR when Unbound runs as systemd service.
Default is yes. Default is yes.
.TP .TP
.B tcp\-connection\-limit: \fI<IP netblock> <limit> .B tcp\-connection\-limit: \fI<IP netblock> <limit>
@ -670,7 +670,7 @@ what almost all clients need). Nonrecursive queries are refused.
.IP .IP
The \fIallow\fR action does allow nonrecursive queries to access the The \fIallow\fR action does allow nonrecursive queries to access the
local\-data that is configured. The reason is that this does not involve local\-data that is configured. The reason is that this does not involve
the unbound server recursive lookup algorithm, and static data is served the Unbound server recursive lookup algorithm, and static data is served
in the reply. This supports normal operations where nonrecursive queries in the reply. This supports normal operations where nonrecursive queries
are made for the authoritative data. For nonrecursive queries any replies are made for the authoritative data. For nonrecursive queries any replies
from the dynamic cache are refused. from the dynamic cache are refused.
@ -742,7 +742,7 @@ to chroot and dropping permissions. This allows the pidfile to be
Unbound is not able to remove the pidfile after termination when it is located Unbound is not able to remove the pidfile after termination when it is located
outside of the chroot directory. outside of the chroot directory.
.IP .IP
Additionally, unbound may need to access /dev/urandom (for entropy) Additionally, Unbound may need to access /dev/urandom (for entropy)
from inside the chroot. from inside the chroot.
.IP .IP
If given a chroot is done to the given directory. By default chroot is If given a chroot is done to the given directory. By default chroot is
@ -776,7 +776,7 @@ The logfile is reopened (for append) when the config file is reread, on
SIGHUP. SIGHUP.
.TP .TP
.B use\-syslog: \fI<yes or no> .B use\-syslog: \fI<yes or no>
Sets unbound to send log messages to the syslogd, using Sets Unbound to send log messages to the syslogd, using
\fIsyslog\fR(3). \fIsyslog\fR(3).
The log facility LOG_DAEMON is used, with identity "unbound". The log facility LOG_DAEMON is used, with identity "unbound".
The logfile setting is overridden when use\-syslog is turned on. The logfile setting is overridden when use\-syslog is turned on.
@ -786,7 +786,7 @@ The default is to log to syslog.
If "" is given (default), then the name of the executable, usually "unbound" 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 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 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 Unbound, with different configurations, so that the logs can be easily
distinguished against. distinguished against.
.TP .TP
.B log\-time\-ascii: \fI<yes or no> .B log\-time\-ascii: \fI<yes or no>
@ -874,12 +874,12 @@ with ascii_ prefix and then an ascii string.
If enabled trustanchor.unbound queries are refused. If enabled trustanchor.unbound queries are refused.
.TP .TP
.B target\-fetch\-policy: \fI<"list of numbers"> .B target\-fetch\-policy: \fI<"list of numbers">
Set the target fetch policy used by unbound to determine if it should fetch 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. dependency depth.
.IP .IP
The number of values determines the maximum dependency depth The number of values determines the maximum dependency depth
that unbound will pursue in answering a query. that Unbound will pursue in answering a query.
A value of \-1 means to fetch all targets opportunistically for that dependency 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 depth. A value of 0 means to fetch on demand only. A positive value fetches
that many targets opportunistically. that many targets opportunistically.
@ -1030,7 +1030,7 @@ a little more CPU. Also if the cache is set to 0, it is no use. Default is no.
.TP .TP
.B deny\-any: \fI<yes or no> .B deny\-any: \fI<yes or no>
If yes, deny queries of type ANY with an empty response. Default is no. If yes, deny queries of type ANY with an empty response. Default is no.
If disabled, unbound responds with a short list of resource records if some 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 can be found in the cache and makes the upstream type ANY query if there
are none. are none.
.TP .TP
@ -1090,7 +1090,7 @@ File with trust anchor for one zone, which is tracked with RFC5011 probes.
The probes are run several times per month, thus the machine must be online 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 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, \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, 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 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 necessary to deal with filesystem full events), it must also be inside the
chroot (if that is used). chroot (if that is used).
@ -1176,7 +1176,7 @@ 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 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, 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 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 the query that failed is printed but also the reason why Unbound thought
it was wrong and which server sent the faulty data. it was wrong and which server sent the faulty data.
.TP .TP
.B val\-permissive\-mode: \fI<yes or no> .B val\-permissive\-mode: \fI<yes or no>
@ -1188,15 +1188,15 @@ is set in replies. Also logging is performed as for full validation.
The default value is "no". The default value is "no".
.TP .TP
.B ignore\-cd\-flag: \fI<yes or no> .B ignore\-cd\-flag: \fI<yes or no>
Instruct unbound to ignore the CD flag from clients and refuse to Instruct Unbound to ignore the CD flag from clients and refuse to
return bogus answers to them. Thus, the CD (Checking Disabled) flag return bogus answers to them. Thus, the CD (Checking Disabled) flag
does not disable checking any more. This is useful if legacy (w2008) does not disable checking any more. This is useful if legacy (w2008)
servers that set the CD flag but cannot validate DNSSEC themselves are servers that set the CD flag but cannot validate DNSSEC themselves are
the clients, and then unbound provides them with DNSSEC protection. the clients, and then Unbound provides them with DNSSEC protection.
The default value is "no". The default value is "no".
.TP .TP
.B serve\-expired: \fI<yes or no> .B serve\-expired: \fI<yes or no>
If enabled, unbound attempts to serve old responses from cache with a If enabled, Unbound attempts to serve old responses from cache with a
TTL of \fBserve\-expired\-reply\-ttl\fR in the response without waiting for the TTL of \fBserve\-expired\-reply\-ttl\fR in the response without waiting for the
actual resolution to finish. The actual resolution answer ends up in the cache actual resolution to finish. The actual resolution answer ends up in the cache
later on. Default is "no". later on. Default is "no".
@ -1227,14 +1227,14 @@ RFC 8767 is 1800. Setting this to 0 will disable this
behavior. Default is 0. behavior. Default is 0.
.TP .TP
.B serve\-original\-ttl: \fI<yes or no> .B serve\-original\-ttl: \fI<yes or no>
If enabled, unbound will always return the original TTL as received from If enabled, Unbound will always return the original TTL as received from
the upstream name server rather than the decrementing TTL as the upstream name server rather than the decrementing TTL as
stored in the cache. This feature may be useful if unbound serves as a 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 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 not impact cache expiry, it only changes the TTL Unbound embeds in responses to
queries. Note that enabling this feature implicitly disables enforcement of queries. Note that enabling this feature implicitly disables enforcement of
the configured minimum and maximum TTL, as it is assumed users who enable this 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. 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 Thus, the values set using \fBcache\-min\-ttl\fR and \fBcache\-max\-ttl\fR are
ignored. ignored.
Default is "no". Default is "no".
@ -1295,11 +1295,11 @@ or gigabytes (1024*1024 bytes in a megabyte).
.TP .TP
.B unblock\-lan\-zones: \fI<yes or no> .B unblock\-lan\-zones: \fI<yes or no>
Default is disabled. If enabled, then for private address space, Default is disabled. If enabled, then for private address space,
the reverse lookups are no longer filtered. This allows unbound when 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, 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, 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 only localhost, 127.0.0.1 reverse and ::1 reverse zones are configured
with default local zones. Disable the option when unbound is running with default local zones. Disable the option when Unbound is running
as a (DHCP-) DNS network resolver for a group of machines, where such as a (DHCP-) DNS network resolver for a group of machines, where such
lookups should be filtered (RFC compliance), this also stops potential lookups should be filtered (RFC compliance), this also stops potential
data leakage about the local network to the upstream DNS servers. data leakage about the local network to the upstream DNS servers.
@ -1647,7 +1647,7 @@ query names, but not spoofed reflection floods. Cached responses are not
ratelimited by this setting. The zone of the query is determined by examining 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. 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 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 overloaded with random names, and keeps Unbound from sending traffic to the
nameservers for those zones. nameservers for those zones.
.TP 5 .TP 5
.B ratelimit\-size: \fI<memory size> .B ratelimit\-size: \fI<memory size>
@ -1714,7 +1714,7 @@ and enter the cache, whilst also mitigating the traffic flow by the
factor given. factor given.
.TP 5 .TP 5
.B outbound\-msg\-retry: \fI<number> .B outbound\-msg\-retry: \fI<number>
The number of retries unbound will do in case of a non positive response is The number of retries Unbound will do in case of a non positive response is
received. If a forward nameserver is used, this is the number of retries per received. If a forward nameserver is used, this is the number of retries per
forward nameserver in case of throwaway response. forward nameserver in case of throwaway response.
.TP 5 .TP 5
@ -1747,7 +1747,7 @@ In the
.B remote\-control: .B remote\-control:
clause are the declarations for the remote control facility. If this is clause are the declarations for the remote control facility. If this is
enabled, the \fIunbound\-control\fR(8) utility can be used to send enabled, the \fIunbound\-control\fR(8) utility can be used to send
commands to the running unbound server. The server uses these clauses commands to the running Unbound server. The server uses these clauses
to setup TLSv1 security for the connection. The to setup TLSv1 security for the connection. The
\fIunbound\-control\fR(8) utility also reads the \fBremote\-control\fR \fIunbound\-control\fR(8) utility also reads the \fBremote\-control\fR
section for options. To setup the correct self\-signed certificates use the section for options. To setup the correct self\-signed certificates use the
@ -1767,7 +1767,7 @@ the server for the change to take effect.
.IP .IP
If you set it to an absolute path, a local socket is used. The local socket If you set it to an absolute path, a local socket is used. The local socket
does not use the certificates and keys, so those files need not be present. 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 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 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 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 in the that group. To restrict access further, create a directory to put
@ -1787,12 +1787,12 @@ and the value of this option is ignored.
.B server\-key\-file: \fI<private key file> .B server\-key\-file: \fI<private key file>
Path to the server private key, by default unbound_server.key. 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 generated by the \fIunbound\-control\-setup\fR utility.
This file is used by the unbound server, but not by \fIunbound\-control\fR. This file is used by the Unbound server, but not by \fIunbound\-control\fR.
.TP 5 .TP 5
.B server\-cert\-file: \fI<certificate file.pem> .B server\-cert\-file: \fI<certificate file.pem>
Path to the server self signed certificate, by default unbound_server.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 generated by the \fIunbound\-control\-setup\fR utility.
This file is used by the unbound server, and also by \fIunbound\-control\fR. This file is used by the Unbound server, and also by \fIunbound\-control\fR.
.TP 5 .TP 5
.B control\-key\-file: \fI<private key file> .B control\-key\-file: \fI<private key file>
Path to the control client private key, by default unbound_control.key. Path to the control client private key, by default unbound_control.key.
@ -1810,24 +1810,24 @@ There may be multiple
.B stub\-zone: .B stub\-zone:
clauses. Each with a name: and zero or more hostnames or IP addresses. 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. 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 servers should be authority servers, not recursors; Unbound performs
the recursive processing itself for stub zones. the recursive processing itself for stub zones.
.P .P
The stub zone can be used to configure authoritative data to be used 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. by the resolver that cannot be accessed using the public internet servers.
This is useful for company\-local data or private zones. Setup an This is useful for company\-local data or private zones. Setup an
authoritative server on a different host (or different port). Enter a config authoritative server on a different host (or different port). Enter a config
entry for unbound with entry for Unbound with
.B stub\-addr: .B stub\-addr:
<ip address of host[@port]>. <ip address of host[@port]>.
The unbound resolver can then access the data, without referring to the The Unbound resolver can then access the data, without referring to the
public internet for it. public internet for it.
.P .P
This setup allows DNSSEC signed zones to be served by that This setup allows DNSSEC signed zones to be served by that
authoritative server, in which case a trusted key entry with the public key 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 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 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 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 private zone, and can even set the AD bit ('authentic'), but the AA
('authoritative') bit is not set on these replies. ('authoritative') bit is not set on these replies.
.P .P
@ -1835,7 +1835,7 @@ 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 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 served zone. The insecure clause stops DNSSEC from invalidating the
zone. The local zone nodefault (or \fItransparent\fR) clause makes the zone. The local zone nodefault (or \fItransparent\fR) clause makes the
(reverse\-) zone bypass unbound's filtering of RFC1918 zones. (reverse\-) zone bypass Unbound's filtering of RFC1918 zones.
.TP .TP
.B name: \fI<domain name> .B name: \fI<domain name>
Name of the stub zone. This is the full domain name of the zone. Name of the stub zone. This is the full domain name of the zone.
@ -1884,10 +1884,10 @@ 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 addresses. For the forward zone this list of nameservers is used to
forward the queries to. The servers listed as \fBforward\-host:\fR and forward the queries to. The servers listed as \fBforward\-host:\fR and
\fBforward\-addr:\fR have to handle further recursion for the query. Thus, \fBforward\-addr:\fR have to handle further recursion for the query. Thus,
those servers are not authority servers, but are (just like unbound is) those servers are not authority servers, but are (just like Unbound is)
recursive servers too; unbound does not perform recursion itself for the recursive servers too; Unbound does not perform recursion itself for the
forward zone, it lets the remote server do it. Class IN is assumed. 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 CNAMEs are chased by Unbound itself, asking the remote server for every
name in the indirection chain, to protect the local cache from illegal name in the indirection chain, to protect the local cache from illegal
indirect referenced items. indirect referenced items.
A forward\-zone entry with name "." and a forward\-addr target will A forward\-zone entry with name "." and a forward\-addr target will
@ -1913,7 +1913,7 @@ name is accepted. The cert must also match a CA from the tls\-cert\-bundle.
.TP .TP
.B forward\-first: \fI<yes or no> .B forward\-first: \fI<yes or no>
If a forwarded query is met with a SERVFAIL error, and this option is 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 enabled, Unbound will fall back to normal recursive resolution for this
query as if no query forwarding had been specified. The default is "no". query as if no query forwarding had been specified. The default is "no".
.TP .TP
.B forward\-tls\-upstream: \fI<yes or no> .B forward\-tls\-upstream: \fI<yes or no>
@ -1939,7 +1939,7 @@ have a \fBname:\fR. There can be multiple ones, by listing multiple auth\-zone
The authority zone with the name closest to the name looked up is used. The authority zone with the name closest to the name looked up is used.
Authority zones are processed after \fBlocal\-zones\fR and before Authority zones are processed after \fBlocal\-zones\fR and before
cache (\fBfor\-downstream:\fR \fIyes\fR), and when used in this manner cache (\fBfor\-downstream:\fR \fIyes\fR), and when used in this manner
make unbound respond like an authority server. Authority zones are also make Unbound respond like an authority server. Authority zones are also
processed after cache, just before going to the network to fetch processed after cache, just before going to the network to fetch
information for recursion (\fBfor\-upstream:\fR \fIyes\fR), and when used information for recursion (\fBfor\-upstream:\fR \fIyes\fR), and when used
in this manner provide a local copy of an authority server that speeds up in this manner provide a local copy of an authority server that speeds up
@ -2000,25 +2000,25 @@ file is downloaded when notified. The primaries from primary: statements are
allowed notify by default. allowed notify by default.
.TP .TP
.B fallback\-enabled: \fI<yes or no> .B fallback\-enabled: \fI<yes or no>
Default no. If enabled, unbound falls back to querying the internet as Default no. If enabled, Unbound falls back to querying the internet as
a resolver for this zone when lookups fail. For example for DNSSEC a resolver for this zone when lookups fail. For example for DNSSEC
validation failures. validation failures.
.TP .TP
.B for\-downstream: \fI<yes or no> .B for\-downstream: \fI<yes or no>
Default yes. If enabled, unbound serves authority responses to Default yes. If enabled, Unbound serves authority responses to
downstream clients for this zone. This option makes unbound behave, for 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 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 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 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 for\-upstream is yes, then Unbound will DNSSEC validate the contents of the
zone before serving the zone contents to clients and store validation zone before serving the zone contents to clients and store validation
results in the cache. results in the cache.
.TP .TP
.B for\-upstream: \fI<yes or no> .B for\-upstream: \fI<yes or no>
Default yes. If enabled, unbound fetches data from this data collection Default yes. If enabled, Unbound fetches data from this data collection
for answering recursion queries. Instead of sending queries over the internet 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 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 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. downstream clients, and use the zone data as a local copy to speed up lookups.
.TP .TP
.B zonemd\-check: \fI<yes or no> .B zonemd\-check: \fI<yes or no>
@ -2042,7 +2042,7 @@ a ZONEMD is always a failure, also for nonDNSSEC signed zones.
.TP .TP
.B zonefile: \fI<filename> .B zonefile: \fI<filename>
The filename where the zone is stored. If not given then no zonefile is used. 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 If the file does not exist or is empty, Unbound will attempt to fetch zone
data (eg. from the primary servers). data (eg. from the primary servers).
.SS "View Options" .SS "View Options"
.LP .LP
@ -2142,9 +2142,9 @@ underneath the name given.
The The
.B dnscrypt: .B dnscrypt:
clause gives the settings of the dnscrypt channel. While those options are clause gives the settings of the dnscrypt channel. While those options are
available, they are only meaningful if unbound was compiled with available, they are only meaningful if Unbound was compiled with
\fB\-\-enable\-dnscrypt\fR. \fB\-\-enable\-dnscrypt\fR.
Currently certificate and secret/public keys cannot be generated by unbound. Currently certificate and secret/public keys cannot be generated by Unbound.
You can use dnscrypt-wrapper to generate those: https://github.com/cofyc/\ You can use dnscrypt-wrapper to generate those: https://github.com/cofyc/\
dnscrypt-wrapper/blob/master/README.md#usage dnscrypt-wrapper/blob/master/README.md#usage
.TP .TP
@ -2276,12 +2276,13 @@ This number applies for each qname/qclass/qtype tuple. Defaults to 100.
.SS "Opportunistic IPsec Support Module Options" .SS "Opportunistic IPsec Support Module Options"
.LP .LP
The IPsec module must be configured in the \fBmodule\-config:\fR "ipsecmod The IPsec module must be configured in the \fBmodule\-config:\fR "ipsecmod
validator iterator" directive and be compiled into the daemon to be validator iterator" directive and be compiled into Unbound by using
enabled. These settings go in the \fBserver:\fR section. \fB\-\-enable\-ipsecmod\fR to be enabled.
These settings go in the \fBserver:\fR section.
.LP .LP
When unbound receives an A/AAAA query that is not in the cache and finds a 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 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 an IPSECKEY subquery for the same domain name. If an answer was found, Unbound
will call an external hook passing the following arguments: will call an external hook passing the following arguments:
.TP 10 .TP 10
\h'5'\fIQNAME\fR \h'5'\fIQNAME\fR
@ -2310,19 +2311,19 @@ relevant for opportunistic IPsec.
.B ipsecmod-enabled: \fI<yes or no>\fR .B ipsecmod-enabled: \fI<yes or no>\fR
Specifies whether the IPsec module is enabled or not. The IPsec module still 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 needs to be defined in the \fBmodule\-config:\fR directive. This option
facilitates turning on/off the module without restarting/reloading unbound. facilitates turning on/off the module without restarting/reloading Unbound.
Defaults to yes. Defaults to yes.
.TP .TP
.B ipsecmod\-hook: \fI<filename>\fR .B ipsecmod\-hook: \fI<filename>\fR
Specifies the external hook that unbound will call with \fIsystem\fR(3). The 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 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 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 must be present when the IPsec module is defined in the \fBmodule\-config:\fR
directive. directive.
.TP .TP
.B ipsecmod-strict: \fI<yes or no>\fR .B ipsecmod-strict: \fI<yes or no>\fR
If enabled unbound requires the external hook to return a success value of 0. 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 Failing to do so Unbound will reply with SERVFAIL. The A/AAAA answer will also
not be cached. Defaults to no. not be cached. Defaults to no.
.TP .TP
.B ipsecmod\-max-ttl: \fI<seconds>\fR .B ipsecmod\-max-ttl: \fI<seconds>\fR
@ -2330,7 +2331,7 @@ Time to live maximum for A/AAAA cached records after calling the external hook.
Defaults to 3600. Defaults to 3600.
.TP .TP
.B ipsecmod-ignore-bogus: \fI<yes or no>\fR .B ipsecmod-ignore-bogus: \fI<yes or no>\fR
Specifies the behaviour of unbound when the IPSECKEY answer is bogus. If set 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 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 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. A/AAAA query will be SERVFAIL. Mainly used for testing. Defaults to no.
@ -2357,7 +2358,7 @@ If Unbound cannot even find an answer in the backend, it resolves the
query as usual, and stores the answer in the backend. query as usual, and stores the answer in the backend.
.P .P
This module interacts with the \fBserve\-expired\-*\fR options and will reply This module interacts with the \fBserve\-expired\-*\fR options and will reply
with expired data if unbound is configured for that. Currently the use with expired data if Unbound is configured for that. Currently the use
of \fBserve\-expired\-client\-timeout:\fR and of \fBserve\-expired\-client\-timeout:\fR and
\fBserve\-expired\-reply\-ttl:\fR is not consistent for data originating from \fBserve\-expired\-reply\-ttl:\fR is not consistent for data originating from
the external cache as these will result in a reply with 0 TTL without trying to the external cache as these will result in a reply with 0 TTL without trying to
@ -2436,16 +2437,17 @@ re-establish a new connection later.
This option defaults to 100 milliseconds. This option defaults to 100 milliseconds.
.TP .TP
.B redis-expire-records: \fI<yes or no> .B redis-expire-records: \fI<yes or no>
If Redis record expiration is enabled. If yes, unbound sets timeout for Redis 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 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, 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 this option is internally reverted to "no". Redis SETEX support is required
for this option (Redis >= 2.0.0). for this option (Redis >= 2.0.0).
This option defaults to no. This option defaults to no.
.SS DNSTAP Logging Options .SS DNSTAP Logging Options
DNSTAP support, when compiled in, is enabled in the \fBdnstap:\fR section. 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 This starts an extra thread (when compiled with threading) that writes
the log information to the destination. If unbound is compiled without the log information to the destination. If Unbound is compiled without
threading it does not spawn a thread, but connects per-process to the threading it does not spawn a thread, but connects per-process to the
destination. destination.
.TP .TP
@ -2503,19 +2505,19 @@ Default is "".
.TP .TP
.B dnstap-log-resolver-query-messages: \fI<yes or no> .B dnstap-log-resolver-query-messages: \fI<yes or no>
Enable to log resolver query messages. Default is no. Enable to log resolver query messages. Default is no.
These are messages from unbound to upstream servers. These are messages from Unbound to upstream servers.
.TP .TP
.B dnstap-log-resolver-response-messages: \fI<yes or no> .B dnstap-log-resolver-response-messages: \fI<yes or no>
Enable to log resolver response messages. Default is no. Enable to log resolver response messages. Default is no.
These are replies from upstream servers to unbound. These are replies from upstream servers to Unbound.
.TP .TP
.B dnstap-log-client-query-messages: \fI<yes or no> .B dnstap-log-client-query-messages: \fI<yes or no>
Enable to log client query messages. Default is no. Enable to log client query messages. Default is no.
These are client queries to unbound. These are client queries to Unbound.
.TP .TP
.B dnstap-log-client-response-messages: \fI<yes or no> .B dnstap-log-client-response-messages: \fI<yes or no>
Enable to log client response messages. Default is no. Enable to log client response messages. Default is no.
These are responses from unbound to clients. These are responses from Unbound to clients.
.TP .TP
.B dnstap-log-forwarder-query-messages: \fI<yes or no> .B dnstap-log-forwarder-query-messages: \fI<yes or no>
Enable to log forwarder query messages. Default is no. Enable to log forwarder query messages. Default is no.
@ -2614,7 +2616,7 @@ allowed notify by default.
.TP .TP
.B zonefile: \fI<filename> .B zonefile: \fI<filename>
The filename where the zone is stored. If not given then no zonefile is used. 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 If the file does not exist or is empty, Unbound will attempt to fetch zone
data (eg. from the primary servers). data (eg. from the primary servers).
.TP .TP
.B rpz\-action\-override: \fI<action> .B rpz\-action\-override: \fI<action>
@ -2671,7 +2673,7 @@ server:
.SH "FILES" .SH "FILES"
.TP .TP
.I @UNBOUND_RUN_DIR@ .I @UNBOUND_RUN_DIR@
default unbound working directory. default Unbound working directory.
.TP .TP
.I @UNBOUND_CHROOT_DIR@ .I @UNBOUND_CHROOT_DIR@
default default
@ -2679,13 +2681,13 @@ default
location. location.
.TP .TP
.I @ub_conf_file@ .I @ub_conf_file@
unbound configuration file. Unbound configuration file.
.TP .TP
.I @UNBOUND_PIDFILE@ .I @UNBOUND_PIDFILE@
default unbound pidfile with process ID of the running daemon. default Unbound pidfile with process ID of the running daemon.
.TP .TP
.I unbound.log .I unbound.log
unbound log file. default is to log to Unbound log file. default is to log to
\fIsyslog\fR(3). \fIsyslog\fR(3).
.SH "SEE ALSO" .SH "SEE ALSO"
\fIunbound\fR(8), \fIunbound\fR(8),