1unbound.conf(5)                 unbound 1.17.1                 unbound.conf(5)
2
3
4

NAME

6       unbound.conf - Unbound configuration file.
7

SYNOPSIS

9       unbound.conf
10

DESCRIPTION

12       unbound.conf  is used to configure unbound(8).  The file format has at‐
13       tributes and values. Some attributes have attributes inside them.   The
14       notation is: attribute: value.
15
16       Comments  start with # and last to the end of line. Empty lines are ig‐
17       nored as is whitespace at the beginning of a line.
18
19       The utility unbound-checkconf(8) can  be  used  to  check  unbound.conf
20       prior to usage.
21

EXAMPLE

23       An  example  config  file is shown below. Copy this to /etc/unbound/un‐
24       bound.conf and start the server with:
25
26            $ unbound -c /etc/unbound/unbound.conf
27
28       Most settings are the defaults. Stop the server with:
29
30            $ kill `cat /etc/unbound/unbound.pid`
31
32       Below is a minimal config file. The source distribution contains an ex‐
33       tensive example.conf file with all the options.
34
35       # unbound.conf(5) config file for unbound(8).
36       server:
37            directory: "/etc/unbound"
38            username: unbound
39            # make sure unbound can access entropy from inside the chroot.
40            # e.g. on linux the use these commands (on BSD, devfs(8) is used):
41            #      mount --bind -n /dev/urandom /etc/unbound/dev/urandom
42            # and  mount --bind -n /dev/log /etc/unbound/dev/log
43            chroot: "/etc/unbound"
44            # logfile: "/etc/unbound/unbound.log"  #uncomment to use logfile.
45            pidfile: "/etc/unbound/unbound.pid"
46            # verbosity: 1      # uncomment and increase to get more logging.
47            # listen on all interfaces, answer queries from the local subnet.
48            interface: 0.0.0.0
49            interface: ::0
50            access-control: 10.0.0.0/8 allow
51            access-control: 2001:DB8::/64 allow
52

FILE FORMAT

54       There must be whitespace between keywords.  Attribute keywords end with
55       a colon ':'.  An attribute is followed by a value,  or  its  containing
56       attributes in which case it is referred to as a clause.  Clauses can be
57       repeated throughout the file (or included files)  to  group  attributes
58       under the same clause.
59
60       Files  can be included using the include: directive. It can appear any‐
61       where, it accepts a single file name as argument.  Processing continues
62       as  if  the text from the included file was copied into the config file
63       at that point.  If also using chroot, using full path names for the in‐
64       cluded  files  works, relative pathnames for the included names work if
65       the directory where the daemon is started equals its chroot/working di‐
66       rectory  or  is  specified before the include statement with directory:
67       dir.  Wildcards can be used to include multiple files, see glob(7).
68
69       For a more structural include option, the  include-toplevel:  directive
70       can  be used.  This closes whatever clause is currently active (if any)
71       and forces the use of clauses in the included  files  and  right  after
72       this directive.
73
74   Server Options
75       These options are part of the server: clause.
76
77       verbosity: <number>
78              The  verbosity  number, level 0 means no verbosity, only errors.
79              Level 1 gives operational information.  Level 2  gives  detailed
80              operational  information  including short information per query.
81              Level 3 gives query level information, output per query.   Level
82              4  gives algorithm level information.  Level 5 logs client iden‐
83              tification for cache misses.  Default is level 1.  The verbosity
84              can also be increased from the commandline, see unbound(8).
85
86       statistics-interval: <seconds>
87              The number of seconds between printing statistics to the log for
88              every thread.  Disable with value 0 or "". Default is  disabled.
89              The  histogram  statistics are only printed if replies were sent
90              during  the  statistics  interval,  requestlist  statistics  are
91              printed  for every interval (but can be 0).  This is because the
92              median calculation requires data to be present.
93
94       statistics-cumulative: <yes or no>
95              If enabled, statistics are cumulative  since  starting  Unbound,
96              without  clearing the statistics counters after logging the sta‐
97              tistics. Default is no.
98
99       extended-statistics: <yes or no>
100              If enabled, extended statistics are  printed  from  unbound-con‐
101              trol(8).   Default is off, because keeping track of more statis‐
102              tics takes time.  The counters are listed in unbound-control(8).
103
104       statistics-inhibit-zero: <yes or no>
105              If enabled, selected extended statistics with a value of  0  are
106              inhibited  from  printing  with  unbound-control(8).   These are
107              query types, query classes, query opcodes, answer rcodes (except
108              NOERROR,  FORMERR, SERVFAIL, NXDOMAIN, NOTIMPL, REFUSED) and RPZ
109              actions.  Default is on.
110
111       num-threads: <number>
112              The number of threads to create to serve clients. Use 1  for  no
113              threading.
114
115       port: <port number>
116              The  port  number,  default  53, on which the server responds to
117              queries.
118
119       interface: <ip address or interface name [@port]>
120              Interface to use to connect to the network.  This  interface  is
121              listened to for queries from clients, and answers to clients are
122              given from it.  Can be given multiple times to work  on  several
123              interfaces. If none are given the default is to listen to local‐
124              host.  If an interface name is used instead of  an  ip  address,
125              the list of ip addresses on that interface are used.  The inter‐
126              faces are not changed on  a  reload  (kill  -HUP)  but  only  on
127              restart.   A  port  number  can be specified with @port (without
128              spaces between interface and port number), if not specified  the
129              default port (from port) is used.
130
131       ip-address: <ip address or interface name [@port]>
132              Same as interface: (for ease of compatibility with nsd.conf).
133
134       interface-automatic: <yes or no>
135              Listen  on all addresses on all (current and future) interfaces,
136              detect the source interface on UDP  queries  and  copy  them  to
137              replies.   This  is  a  lot like ip-transparent, but this option
138              services all interfaces whilst with ip-transparent you  can  se‐
139              lect  which  (future)  interfaces  Unbound  provides service on.
140              This feature is experimental, and needs support in your  OS  for
141              particular socket options.  Default value is no.
142
143       interface-automatic-ports: <string>
144              List  the  port  numbers that interface-automatic listens on. If
145              empty, the default port is listened on.  The  port  numbers  are
146              separated by spaces in the string. Default is "".
147
148              This  can  be  used to have interface automatic to deal with the
149              interface, and listen on the normal port number, by including it
150              in  the  list,  and  also  https or dns over tls port numbers by
151              putting them in the list as well.
152
153       outgoing-interface: <ip address or ip6 netblock>
154              Interface to use to connect to the network.  This  interface  is
155              used  to send queries to authoritative servers and receive their
156              replies. Can be given multiple times to work on  several  inter‐
157              faces.  If  none  are  given  the default (all) is used. You can
158              specify the same interfaces in  interface:  and  outgoing-inter‐
159              face:  lines,  the  interfaces  are then used for both purposes.
160              Outgoing queries are sent via a  random  outgoing  interface  to
161              counter spoofing.
162
163              If  an  IPv6 netblock is specified instead of an individual IPv6
164              address, outgoing UDP queries will use a randomised  source  ad‐
165              dress  taken from the netblock to counter spoofing. Requires the
166              IPv6 netblock to be routed to the host running Unbound, and  re‐
167              quires  OS  support  for unprivileged non-local binds (currently
168              only supported on Linux). Several  netblocks  may  be  specified
169              with  multiple  outgoing-interface:  options, but do not specify
170              both an individual IPv6 address and an  IPv6  netblock,  or  the
171              randomisation will be compromised.  Consider combining with pre‐
172              fer-ip6: yes to increase the likelihood of IPv6 nameservers  be‐
173              ing  selected for queries.  On Linux you need these two commands
174              to be able to use the freebind socket option to receive  traffic
175              for  the ip6 netblock: ip -6 addr add mynetblock/64 dev lo && ip
176              -6 route add local mynetblock/64 dev lo
177
178       outgoing-range: <number>
179              Number of ports to open. This number of file descriptors can  be
180              opened  per  thread. Must be at least 1. Default depends on com‐
181              pile options. Larger numbers need extra resources from the oper‐
182              ating  system.   For performance a very large value is best, use
183              libevent to make this possible.
184
185       outgoing-port-permit: <port number or range>
186              Permit Unbound to open this port or range of ports  for  use  to
187              send  queries.   A larger number of permitted outgoing ports in‐
188              creases resilience against spoofing attempts.  Make  sure  these
189              ports  are  not  needed by other daemons.  By default only ports
190              above 1024 that have not been assigned by IANA are used.  Give a
191              port number or a range of the form "low-high", without spaces.
192
193              The  outgoing-port-permit and outgoing-port-avoid statements are
194              processed in the line order of the config file, adding the  per‐
195              mitted  ports  and subtracting the avoided ports from the set of
196              allowed ports.  The processing starts with the  non  IANA  allo‐
197              cated ports above 1024 in the set of allowed ports.
198
199       outgoing-port-avoid: <port number or range>
200              Do  not  permit  Unbound to open this port or range of ports for
201              use to send queries. Use this to make sure Unbound does not grab
202              a  port  that  another  daemon needs. The port is avoided on all
203              outgoing interfaces, both IP4 and IP6.  By  default  only  ports
204              above 1024 that have not been assigned by IANA are used.  Give a
205              port number or a range of the form "low-high", without spaces.
206
207       outgoing-num-tcp: <number>
208              Number of outgoing TCP buffers to allocate per  thread.  Default
209              is  10. If set to 0, or if do-tcp is "no", no TCP queries to au‐
210              thoritative servers are done.  For larger installations increas‐
211              ing this value is a good idea.
212
213       incoming-num-tcp: <number>
214              Number  of  incoming TCP buffers to allocate per thread. Default
215              is 10. If set to 0, or if do-tcp is "no", no  TCP  queries  from
216              clients  are  accepted. For larger installations increasing this
217              value is a good idea.
218
219       edns-buffer-size: <number>
220              Number of bytes size to advertise as the EDNS reassembly  buffer
221              size.   This  is  the  value put into datagrams over UDP towards
222              peers.  The actual buffer size is determined by  msg-buffer-size
223              (both for TCP and UDP).  Do not set higher than that value.  De‐
224              fault is 1232 which is the DNS  Flag  Day  2020  recommendation.
225              Setting  to  512 bypasses even the most stringent path MTU prob‐
226              lems, but is seen as extreme, since the amount of  TCP  fallback
227              generated  is  excessive  (probably also for this resolver, con‐
228              sider tuning the outgoing tcp number).
229
230       max-udp-size: <number>
231              Maximum UDP response size (not applied to TCP response).   65536
232              disables the udp response size maximum, and uses the choice from
233              the client, always.  Suggested values are 512 to  4096.  Default
234              is 4096.
235
236       stream-wait-size: <number>
237              Number  of bytes size maximum to use for waiting stream buffers.
238              Default is 4 megabytes.  A plain number is in bytes, append 'k',
239              'm'  or  'g'  for  kilobytes,  megabytes or gigabytes (1024*1024
240              bytes in a megabyte).  As TCP and TLS streams queue up  multiple
241              results,  the  amount  of memory used for these buffers does not
242              exceed this number, otherwise the responses are  dropped.   This
243              manages  the total memory usage of the server (under heavy use),
244              the number of requests that can be queued up per  connection  is
245              also limited, with further requests waiting in TCP buffers.
246
247       msg-buffer-size: <number>
248              Number  of  bytes  size of the message buffers. Default is 65552
249              bytes, enough for 64 Kb packets, the maximum DNS  message  size.
250              No  message larger than this can be sent or received. Can be re‐
251              duced to use less memory, but some requests for DNS  data,  such
252              as for huge resource records, will result in a SERVFAIL reply to
253              the client.
254
255       msg-cache-size: <number>
256              Number of  bytes  size  of  the  message  cache.  Default  is  4
257              megabytes.   A  plain number is in bytes, append 'k', 'm' or 'g'
258              for kilobytes, megabytes or  gigabytes  (1024*1024  bytes  in  a
259              megabyte).
260
261       msg-cache-slabs: <number>
262              Number  of  slabs  in  the message cache. Slabs reduce lock con‐
263              tention by threads.  Must be  set  to  a  power  of  2.  Setting
264              (close) to the number of cpus is a reasonable guess.
265
266       num-queries-per-thread: <number>
267              The  number of queries that every thread will service simultane‐
268              ously.  If more queries  arrive  that  need  servicing,  and  no
269              queries  can  be  jostled  out  (see  jostle-timeout),  then the
270              queries are dropped. This forces the client to  resend  after  a
271              timeout;  allowing  the  server  time  to  work  on the existing
272              queries. Default depends on compile options, 512 or 1024.
273
274       jostle-timeout: <msec>
275              Timeout used when the server is very busy.  Set to a value  that
276              usually  results  in one roundtrip to the authority servers.  If
277              too many queries arrive, then 50% of the queries are allowed  to
278              run  to  completion, and the other 50% are replaced with the new
279              incoming query if they have already spent more  than  their  al‐
280              lowed  time.   This  protects  against denial of service by slow
281              queries or high query rates.  Default 200 milliseconds.  The ef‐
282              fect  is  that  the  qps for long-lasting queries is about (num‐
283              queriesperthread / 2) / (average time  for  such  long  queries)
284              qps.   The  qps  for  short  queries  can  be about (numqueries‐
285              perthread / 2)  /  (jostletimeout  in  whole  seconds)  qps  per
286              thread, about (1024/2)*5 = 2560 qps by default.
287
288       delay-close: <msec>
289              Extra  delay  for timeouted UDP ports before they are closed, in
290              msec.  Default is 0, and that disables it.  This  prevents  very
291              delayed  answer  packets  from  the upstream (recursive) servers
292              from bouncing against closed ports and setting off all  sort  of
293              close-port  counters,  with eg. 1500 msec.  When timeouts happen
294              you need extra sockets, it checks the ID and remote IP of  pack‐
295              ets,  and  unwanted  packets  are  added  to the unwanted packet
296              counter.
297
298       udp-connect: <yes or no>
299              Perform connect for UDP sockets that mitigates ICMP side channel
300              leakage.  Default is yes.
301
302       unknown-server-time-limit: <msec>
303              The  wait  time in msec for waiting for an unknown server to re‐
304              ply.  Increase this if you are behind a slow satellite link,  to
305              eg. 1128.  That would then avoid re-querying every initial query
306              because it times out.  Default is 376 msec.
307
308       so-rcvbuf: <number>
309              If not 0, then set the SO_RCVBUF socket option to get more  buf‐
310              fer space on UDP port 53 incoming queries.  So that short spikes
311              on busy servers do not drop  packets  (see  counter  in  netstat
312              -su).   Default  is 0 (use system value).  Otherwise, the number
313              of bytes to ask for, try "4m" on a busy server.  The OS caps  it
314              at  a  maximum, on linux Unbound needs root permission to bypass
315              the limit, or the admin can use  sysctl  net.core.rmem_max.   On
316              BSD  change kern.ipc.maxsockbuf in /etc/sysctl.conf.  On OpenBSD
317              change header and recompile kernel. On Solaris ndd -set /dev/udp
318              udp_max_buf 8388608.
319
320       so-sndbuf: <number>
321              If  not 0, then set the SO_SNDBUF socket option to get more buf‐
322              fer space on UDP port 53 outgoing queries.  This for  very  busy
323              servers  handles  spikes in answer traffic, otherwise 'send: re‐
324              source temporarily unavailable' can get logged, the buffer over‐
325              run  is  also  visible by netstat -su.  Default is 0 (use system
326              value).  Specify the number of bytes to ask for, try "4m"  on  a
327              very busy server.  The OS caps it at a maximum, on linux Unbound
328              needs root permission to bypass the limit, or the admin can  use
329              sysctl  net.core.wmem_max.   On BSD, Solaris changes are similar
330              to so-rcvbuf.
331
332       so-reuseport: <yes or no>
333              If yes, then  open  dedicated  listening  sockets  for  incoming
334              queries  for  each thread and try to set the SO_REUSEPORT socket
335              option on each  socket.   May  distribute  incoming  queries  to
336              threads  more evenly.  Default is yes.  On Linux it is supported
337              in kernels >= 3.9.  On other systems, FreeBSD, OSX it  may  also
338              work.   You  can enable it (on any platform and kernel), it then
339              attempts to open the port and passes the option if it was avail‐
340              able  at compile time, if that works it is used, if it fails, it
341              continues silently (unless verbosity 3) without the option.   At
342              extreme load it could be better to turn it off to distribute the
343              queries evenly, reported for Linux systems (4.4.x).
344
345       ip-transparent: <yes or no>
346              If yes, then use IP_TRANSPARENT socket option on  sockets  where
347              Unbound  is listening for incoming traffic.  Default no.  Allows
348              you to bind to non-local interfaces.  For example for  non-exis‐
349              tent  IP  addresses  that are going to exist later on, with host
350              failover configuration.  This is a lot like interface-automatic,
351              but  that  one  services all interfaces and with this option you
352              can select which (future) interfaces  Unbound  provides  service
353              on.   This  option needs Unbound to be started with root permis‐
354              sions on some systems.  The option uses  IP_BINDANY  on  FreeBSD
355              systems and SO_BINDANY on OpenBSD systems.
356
357       ip-freebind: <yes or no>
358              If  yes, then use IP_FREEBIND socket option on sockets where Un‐
359              bound is listening to incoming traffic.  Default no.  Allows you
360              to  bind to IP addresses that are nonlocal or do not exist, like
361              when the network interface or IP address is down.   Exists  only
362              on Linux, where the similar ip-transparent option is also avail‐
363              able.
364
365       ip-dscp: <number>
366              The value of the Differentiated Services Codepoint (DSCP) in the
367              differentiated  services  field  (DS)  of the outgoing IP packet
368              headers.  The field replaces the outdated  IPv4  Type-Of-Service
369              field and the IPv6 traffic class field.
370
371       rrset-cache-size: <number>
372              Number of bytes size of the RRset cache. Default is 4 megabytes.
373              A plain number is in bytes, append 'k', 'm'  or  'g'  for  kilo‐
374              bytes, megabytes or gigabytes (1024*1024 bytes in a megabyte).
375
376       rrset-cache-slabs: <number>
377              Number of slabs in the RRset cache. Slabs reduce lock contention
378              by threads.  Must be set to a power of 2.
379
380       cache-max-ttl: <seconds>
381              Time to live maximum for RRsets and messages in the  cache.  De‐
382              fault is 86400 seconds (1 day).  When the TTL expires, the cache
383              item has expired.  Can be set lower to  force  the  resolver  to
384              query  for  data  often,  and not trust (very large) TTL values.
385              Downstream clients also see the lower TTL.
386
387       cache-min-ttl: <seconds>
388              Time to live minimum for RRsets and messages in the  cache.  De‐
389              fault  is  0.   If  the minimum kicks in, the data is cached for
390              longer than the domain owner intended, and thus less queries are
391              made to look up the data.  Zero makes sure the data in the cache
392              is as the domain owner intended, higher values, especially  more
393              than an hour or so, can lead to trouble as the data in the cache
394              does not match up with the actual data any more.
395
396       cache-max-negative-ttl: <seconds>
397              Time to live maximum for negative responses, these have a SOA in
398              the authority section that is limited in time.  Default is 3600.
399              This applies to nxdomain and nodata answers.
400
401       infra-host-ttl: <seconds>
402              Time to live for entries in the host cache. The host cache  con‐
403              tains  roundtrip  timing, lameness and EDNS support information.
404              Default is 900.
405
406       infra-cache-slabs: <number>
407              Number of slabs in the infrastructure cache. Slabs  reduce  lock
408              contention by threads. Must be set to a power of 2.
409
410       infra-cache-numhosts: <number>
411              Number  of  hosts  for  which  information is cached. Default is
412              10000.
413
414       infra-cache-min-rtt: <msec>
415              Lower limit for dynamic retransmit timeout calculation in infra‐
416              structure cache. Default is 50 milliseconds. Increase this value
417              if using forwarders needing more time to do recursive name reso‐
418              lution.
419
420       infra-cache-max-rtt: <msec>
421              Upper limit for dynamic retransmit timeout calculation in infra‐
422              structure cache. Default is 2 minutes.
423
424       infra-keep-probing: <yes or no>
425              If enabled the server keeps probing hosts that are down, in  the
426              one  probe  at  a  time  regime.  Default is no.  Hosts that are
427              down, eg. they did not respond during the one probe  at  a  time
428              period,  are  marked as down and it may take infra-host-ttl time
429              to get probed again.
430
431       define-tag: <"list of tags">
432              Define the tags that can be used with local-zone and access-con‐
433              trol.   Enclose  the list between quotes ("") and put spaces be‐
434              tween tags.
435
436       do-ip4: <yes or no>
437              Enable or disable whether ip4 queries are  answered  or  issued.
438              Default is yes.
439
440       do-ip6: <yes or no>
441              Enable  or  disable  whether ip6 queries are answered or issued.
442              Default is yes.  If disabled, queries are not answered on  IPv6,
443              and  queries  are  not sent on IPv6 to the internet nameservers.
444              With this option you can disable the IPv6 transport for  sending
445              DNS traffic, it does not impact the contents of the DNS traffic,
446              which may have ip4 and ip6 addresses in it.
447
448       prefer-ip4: <yes or no>
449              If enabled, prefer IPv4 transport for sending DNS queries to in‐
450              ternet  nameservers. Default is no.  Useful if the IPv6 netblock
451              the server has, the entire /64 of that is not owned by one oper‐
452              ator  and  the reputation of the netblock /64 is an issue, using
453              IPv4 then uses the IPv4 filters that the upstream servers have.
454
455       prefer-ip6: <yes or no>
456              If enabled, prefer IPv6 transport for sending DNS queries to in‐
457              ternet nameservers. Default is no.
458
459       do-udp: <yes or no>
460              Enable  or  disable  whether UDP queries are answered or issued.
461              Default is yes.
462
463       do-tcp: <yes or no>
464              Enable or disable whether TCP queries are  answered  or  issued.
465              Default is yes.
466
467       tcp-mss: <number>
468              Maximum segment size (MSS) of TCP socket on which the server re‐
469              sponds to queries. Value lower than common MSS on Ethernet (1220
470              for  example)  will address path MTU problem.  Note that not all
471              platform supports socket option to set  MSS  (TCP_MAXSEG).   De‐
472              fault  is system default MSS determined by interface MTU and ne‐
473              gotiation between server and client.
474
475       outgoing-tcp-mss: <number>
476              Maximum segment size (MSS) of TCP socket  for  outgoing  queries
477              (from  Unbound to other servers). Value lower than common MSS on
478              Ethernet (1220 for example) will address path MTU problem.  Note
479              that  not  all  platform  supports  socket  option  to  set  MSS
480              (TCP_MAXSEG).  Default is system default MSS determined  by  in‐
481              terface MTU and negotiation between Unbound and other servers.
482
483       tcp-idle-timeout: <msec>
484              The  period  Unbound  will wait for a query on a TCP connection.
485              If this timeout expires Unbound closes the connection.  This op‐
486              tion  defaults  to  30000 milliseconds.  When the number of free
487              incoming TCP buffers falls below 50% of the total number config‐
488              ured,  the  option value used is progressively reduced, first to
489              1% of the configured value, then to 0.2% of the configured value
490              if  the number of free buffers falls below 35% of the total num‐
491              ber configured, and finally to 0 if the number of  free  buffers
492              falls  below 20% of the total number configured. A minimum time‐
493              out of 200 milliseconds is observed  regardless  of  the  option
494              value used.
495
496       tcp-reuse-timeout: <msec>
497              The  period Unbound will keep TCP persistent connections open to
498              authority servers. This option defaults to 60000 milliseconds.
499
500       max-reuse-tcp-queries: <number>
501              The maximum number of queries that can be sent on  a  persistent
502              TCP connection.  This option defaults to 200 queries.
503
504       tcp-auth-query-timeout: <number>
505              Timeout  in  milliseconds for TCP queries to auth servers.  This
506              option defaults to 3000 milliseconds.
507
508       edns-tcp-keepalive: <yes or no>
509              Enable or disable EDNS TCP Keepalive. Default is no.
510
511       edns-tcp-keepalive-timeout: <msec>
512              The period Unbound will wait for a query  on  a  TCP  connection
513              when  EDNS  TCP Keepalive is active. If this timeout expires Un‐
514              bound closes the connection. If the client supports the EDNS TCP
515              Keepalive  option, Unbound sends the timeout value to the client
516              to encourage it to close the connection before the server  times
517              out.   This  option  defaults  to 120000 milliseconds.  When the
518              number of free incoming TCP buffers falls below 50% of the total
519              number  configured,  the advertised timeout is progressively re‐
520              duced to 1% of the configured value, then to 0.2% of the config‐
521              ured  value if the number of free buffers falls below 35% of the
522              total number configured, and finally to 0 if the number of  free
523              buffers falls below 20% of the total number configured.  A mini‐
524              mum actual timeout of 200 milliseconds is observed regardless of
525              the advertised timeout.
526
527       tcp-upstream: <yes or no>
528              Enable  or disable whether the upstream queries use TCP only for
529              transport.  Default is no.  Useful in  tunneling  scenarios.  If
530              set  to  no you can specify TCP transport only for selected for‐
531              ward or stub zones using  forward-tcp-upstream  or  stub-tcp-up‐
532              stream respectively.
533
534       udp-upstream-without-downstream: <yes or no>
535              Enable  udp  upstream  even if do-udp is no.  Default is no, and
536              this  does  not  change  anything.   Useful  for   TLS   service
537              providers, that want no udp downstream but use udp to fetch data
538              upstream.
539
540       tls-upstream: <yes or no>
541              Enabled or disable whether the upstream queries use TLS only for
542              transport.   Default is no.  Useful in tunneling scenarios.  The
543              TLS contains plain DNS in TCP wireformat.  The other server must
544              support  this  (see  tls-service-key).  If you enable this, also
545              configure a tls-cert-bundle  or  use  tls-win-cert  or  tls-sys‐
546              tem-cert  to  load CA certs, otherwise the connections cannot be
547              authenticated. This option enables TLS for all of them,  but  if
548              you  do not set this you can configure TLS specifically for some
549              forward  zones  with  forward-tls-upstream.    And   also   with
550              stub-tls-upstream.
551
552       ssl-upstream: <yes or no>
553              Alternate  syntax  for tls-upstream.  If both are present in the
554              config file the last is used.
555
556       tls-service-key: <file>
557              If enabled, the server provides DNS-over-TLS  or  DNS-over-HTTPS
558              service  on  the  TCP  ports marked implicitly or explicitly for
559              these services with tls-port or https-port. The file  must  con‐
560              tain the private key for the TLS session, the public certificate
561              is in the tls-service-pem file and it must also be specified  if
562              tls-service-key  is  specified.   The default is "", turned off.
563              Enabling or disabling this service requires a restart (a  reload
564              is  not  enough), because the key is read while root permissions
565              are held and before chroot (if any).  The ports enabled  implic‐
566              itly  or explicitly via tls-port: and https-port: do not provide
567              normal DNS TCP service. Unbound needs to be compiled  with  lib‐
568              nghttp2 in order to provide DNS-over-HTTPS.
569
570       ssl-service-key: <file>
571              Alternate syntax for tls-service-key.
572
573       tls-service-pem: <file>
574              The  public  key  certificate pem file for the tls service.  De‐
575              fault is "", turned off.
576
577       ssl-service-pem: <file>
578              Alternate syntax for tls-service-pem.
579
580       tls-port: <number>
581              The port number on which to provide  TCP  TLS  service,  default
582              853, only interfaces configured with that port number as @number
583              get the TLS service.
584
585       ssl-port: <number>
586              Alternate syntax for tls-port.
587
588       tls-cert-bundle: <file>
589              If null or "", no file is used.  Set it to the certificate  bun‐
590              dle file, for example "/etc/pki/tls/certs/ca-bundle.crt".  These
591              certificates are used for  authenticating  connections  made  to
592              outside  peers.   For  example auth-zone urls, and also DNS over
593              TLS connections.  It is read at start up before permission  drop
594              and chroot.
595
596       ssl-cert-bundle: <file>
597              Alternate syntax for tls-cert-bundle.
598
599       tls-win-cert: <yes or no>
600              Add  the system certificates to the cert bundle certificates for
601              authentication.  If no cert bundle, it uses only these  certifi‐
602              cates.  Default is no.  On windows this option uses the certifi‐
603              cates from the cert store.  Use the  tls-cert-bundle  option  on
604              other  systems. On other systems, this option enables the system
605              certificates.
606
607       tls-system-cert: <yes or no>
608              This the same setting as the tls-win-cert setting, under a  dif‐
609              ferent name.  Because it is not windows specific.
610
611       tls-additional-port: <portnr>
612              List portnumbers as tls-additional-port, and when interfaces are
613              defined, eg. with the @port suffix, as this  port  number,  they
614              provide  dns over TLS service.  Can list multiple, each on a new
615              statement.
616
617       tls-session-ticket-keys: <file>
618              If not "", lists files with 80 bytes of random contents that are
619              used to perform TLS session resumption for clients using the Un‐
620              bound server.  These files contain the secret key  for  the  TLS
621              session  tickets.  First key use to encrypt and decrypt TLS ses‐
622              sion tickets.  Other keys use to decrypt only.   With  this  you
623              can  roll  over  to new keys, by generating a new first file and
624              allowing decrypt of the old file by listing it after  the  first
625              file for some time, after the wait clients are not using the old
626              key any more and the old key can be removed.  One way to  create
627              the  file  is  dd if=/dev/random bs=1 count=80 of=ticket.dat The
628              first 16 bytes should be different from the old one if you  cre‐
629              ate  a  second  key,  that is the name used to identify the key.
630              Then there is 32 bytes random data for an AES key  and  then  32
631              bytes random data for the HMAC key.
632
633       tls-ciphers: <string with cipher list>
634              Set  the  list of ciphers to allow when serving TLS.  Use "" for
635              defaults, and that is the default.
636
637       tls-ciphersuites: <string with ciphersuites list>
638              Set the list of ciphersuites to allow when serving TLS.  This is
639              for newer TLS 1.3 connections.  Use "" for defaults, and that is
640              the default.
641
642       pad-responses: <yes or no>
643              If enabled, TLS serviced queries that contained an EDNS  Padding
644              option  will  cause  responses padded to the closest multiple of
645              the size specified in pad-responses-block-size.  Default is yes.
646
647       pad-responses-block-size: <number>
648              The block size with which to pad responses  serviced  over  TLS.
649              Only  responses  to  padded  queries will be padded.  Default is
650              468.
651
652       pad-queries: <yes or no>
653              If enabled, all queries sent over TLS upstreams will  be  padded
654              to   the   closest   multiple   of   the   size   specified   in
655              pad-queries-block-size.  Default is yes.
656
657       pad-queries-block-size: <number>
658              The block size with which to  pad  queries  sent  over  TLS  up‐
659              streams.  Default is 128.
660
661       tls-use-sni: <yes or no>
662              Enable  or disable sending the SNI extension on TLS connections.
663              Default is yes.  Changing the value requires a reload.
664
665       https-port: <number>
666              The port number on which to provide DNS-over-HTTPS service,  de‐
667              fault  443,  only interfaces configured with that port number as
668              @number get the HTTPS service.
669
670       http-endpoint: <endpoint string>
671              The HTTP endpoint to provide DNS-over-HTTPS service on.  Default
672              "/dns-query".
673
674       http-max-streams: <number of streams>
675              Number  used in the SETTINGS_MAX_CONCURRENT_STREAMS parameter in
676              the HTTP/2 SETTINGS frame for  DNS-over-HTTPS  connections.  De‐
677              fault 100.
678
679       http-query-buffer-size: <size in bytes>
680              Maximum  number  of bytes used for all HTTP/2 query buffers com‐
681              bined. These buffers contain (partial) DNS queries  waiting  for
682              request  stream completion.  An RST_STREAM frame will be send to
683              streams exceeding this limit. Default is 4  megabytes.  A  plain
684              number  is  in  bytes,  append  'k',  'm'  or 'g' for kilobytes,
685              megabytes or gigabytes (1024*1024 bytes in a megabyte).
686
687       http-response-buffer-size: <size in bytes>
688              Maximum number of bytes used for  all  HTTP/2  response  buffers
689              combined.  These  buffers  contain  DNS  responses waiting to be
690              written back to the clients.  An RST_STREAM frame will  be  send
691              to streams exceeding this limit. Default is 4 megabytes. A plain
692              number is in bytes,  append  'k',  'm'  or  'g'  for  kilobytes,
693              megabytes or gigabytes (1024*1024 bytes in a megabyte).
694
695       http-nodelay: <yes or no>
696              Set  TCP_NODELAY  socket  option on sockets used to provide DNS-
697              over-HTTPS service.  Ignored if the option is not available. De‐
698              fault is yes.
699
700       http-notls-downstream: <yes or no>
701              Disable use of TLS for the downstream DNS-over-HTTP connections.
702              Useful for local back end servers.  Default is no.
703
704       proxy-protocol-port: <portnr>
705              List port numbers as proxy-protocol-port,  and  when  interfaces
706              are  defined,  eg.  with  the @port suffix, as this port number,
707              they support and expect PROXYv2.  In this case the proxy address
708              will  only be used for the network communication and initial ACL
709              (check if the proxy itself is denied/refused by  configuration).
710              The  proxied  address  (if  any)  will  then be used as the true
711              client address and will be used where  applicable  for  logging,
712              ACL,  DNSTAP, RPZ and IP ratelimiting.  PROXYv2 is supported for
713              UDP and TCP/TLS listening interfaces.  There is no  support  for
714              PROXYv2 on a DoH or DNSCrypt listening interface.  Can list mul‐
715              tiple, each on a new statement.
716
717       use-systemd: <yes or no>
718              Enable or disable systemd socket activation.  Default is no.
719
720       do-daemonize: <yes or no>
721              Enable or disable whether the  Unbound  server  forks  into  the
722              background  as  a daemon.  Set the value to no when Unbound runs
723              as systemd service.  Default is yes.
724
725       tcp-connection-limit: <IP netblock> <limit>
726              Allow up to limit simultaneous TCP connections  from  the  given
727              netblock.   When  at the limit, further connections are accepted
728              but closed immediately.  This option  is  experimental  at  this
729              time.
730
731       access-control: <IP netblock> <action>
732              The  netblock  is  given as an IP4 or IP6 address with /size ap‐
733              pended for a classless network block. The action  can  be  deny,
734              refuse,   allow,  allow_setrd,  allow_snoop,  deny_non_local  or
735              refuse_non_local.  The most specific netblock match is used,  if
736              none  match  refuse  is  used.   The order of the access-control
737              statements therefore does not matter.
738
739              The action deny stops queries from hosts from that netblock.
740
741              The action refuse stops queries too, but sends a DNS  rcode  RE‐
742              FUSED error message back.
743
744              The action allow gives access to clients from that netblock.  It
745              gives only access for recursion clients (which  is  what  almost
746              all clients need).  Nonrecursive queries are refused.
747
748              The  allow  action does allow nonrecursive queries to access the
749              local-data that is configured.  The reason is that this does not
750              involve  the  Unbound  server  recursive  lookup  algorithm, and
751              static data is served in the reply.  This supports normal opera‐
752              tions  where nonrecursive queries are made for the authoritative
753              data.  For nonrecursive queries any  replies  from  the  dynamic
754              cache are refused.
755
756              The  allow_setrd  action  ignores the recursion desired (RD) bit
757              and treats all requests as if the recursion desired bit is  set.
758              Note  that  this  behavior violates RFC 1034 which states that a
759              name server should never perform recursive service unless  asked
760              via  the  RD  bit since this interferes with trouble shooting of
761              name servers and their databases. This prohibited  behavior  may
762              be  useful  if another DNS server must forward requests for spe‐
763              cific zones to a resolver DNS server, but only supports stub do‐
764              mains  and  sends queries to the resolver DNS server with the RD
765              bit cleared.
766
767              The action allow_snoop gives nonrecursive access too.  This give
768              both  recursive  and non recursive access.  The name allow_snoop
769              refers to  cache  snooping,  a  technique  to  use  nonrecursive
770              queries  to  examine  the  cache  contents (for malicious acts).
771              However, nonrecursive queries can also be a  valuable  debugging
772              tool (when you want to examine the cache contents). In that case
773              use allow_snoop for your administration host.
774
775              By default only localhost is allowed, the rest is refused.   The
776              default  is  refused, because that is protocol-friendly. The DNS
777              protocol is not designed to handle dropped packets due  to  pol‐
778              icy,  and  dropping  may  result in (possibly excessive) retried
779              queries.
780
781              The deny_non_local and refuse_non_local settings are  for  hosts
782              that are only allowed to query for the authoritative local-data,
783              they are not allowed full recursion but only  the  static  data.
784              With  deny_non_local,  messages that are disallowed are dropped,
785              with refuse_non_local they receive error code REFUSED.
786
787       access-control-tag: <IP netblock> <"list of tags">
788              Assign tags to access-control elements. Clients using  this  ac‐
789              cess  control element use localzones that are tagged with one of
790              these tags. Tags must be defined in define-tags.   Enclose  list
791              of  tags  in  quotes  ("")  and  put spaces between tags. If ac‐
792              cess-control-tag is configured for a netblock that does not have
793              an  access-control,  an access-control element with action allow
794              is configured for this netblock.
795
796       access-control-tag-action: <IP netblock> <tag> <action>
797              Set action for particular tag for given access control  element.
798              If  you have multiple tag values, the tag used to lookup the ac‐
799              tion is the first tag match between access-control-tag  and  lo‐
800              cal-zone-tag  where  "first" comes from the order of the define-
801              tag values.
802
803       access-control-tag-data: <IP netblock> <tag> <"resource record string">
804              Set redirect data for particular tag for  given  access  control
805              element.
806
807       access-control-view: <IP netblock> <view name>
808              Set view for given access control element.
809
810       interface-action: <ip address or interface name [@port]> <action>
811              Similar to access-control: but for interfaces.
812
813              The  action  is  the  same as the ones defined under access-con‐
814              trol:.  Interfaces are refused by default.  By default only  lo‐
815              calhost (the IP netblock, not the loopback interface) is allowed
816              through the default access-control: behavior.
817
818              Note that the interface needs to be already specified  with  in‐
819              terface: and that any access-control*: setting overrides all in‐
820              terface-*: settings for targeted clients.
821
822       interface-tag: <ip address or interface name [@port]> <"list of tags">
823              Similar to access-control-tag: but for interfaces.
824
825              Note that the interface needs to be already specified  with  in‐
826              terface: and that any access-control*: setting overrides all in‐
827              terface-*: settings for targeted clients.
828
829       interface-tag-action: <ip address or interface name [@port]> <tag> <ac‐
830       tion>
831              Similar to access-control-tag-action: but for interfaces.
832
833              Note  that  the interface needs to be already specified with in‐
834              terface: and that any access-control*: setting overrides all in‐
835              terface-*: settings for targeted clients.
836
837       interface-tag-data:  <ip address or interface name [@port]> <tag> <"re‐
838       source record string">
839              Similar to access-control-tag-data: but for interfaces.
840
841              Note that the interface needs to be already specified  with  in‐
842              terface: and that any access-control*: setting overrides all in‐
843              terface-*: settings for targeted clients.
844
845       interface-view: <ip address or interface name [@port]> <view name>
846              Similar to access-control-view: but for interfaces.
847
848              Note that the interface needs to be already specified  with  in‐
849              terface: and that any access-control*: setting overrides all in‐
850              terface-*: settings for targeted clients.
851
852       chroot: <directory>
853              If chroot is enabled, you should pass the configfile  (from  the
854              commandline)  as  a  full path from the original root. After the
855              chroot has been performed the now defunct portion of the  config
856              file  path  is  removed  to be able to reread the config after a
857              reload.
858
859              All other file paths (working dir, logfile, roothints,  and  key
860              files)  can  be  specified  in several ways: as an absolute path
861              relative to the new root, as a relative path to the working  di‐
862              rectory,  or  as an absolute path relative to the original root.
863              In the last case the path is adjusted to remove the unused  por‐
864              tion.
865
866              The  pidfile can be either a relative path to the working direc‐
867              tory, or an absolute path relative to the original root.  It  is
868              written  just prior to chroot and dropping permissions. This al‐
869              lows the pidfile to be /var/run/unbound.pid and the chroot to be
870              /var/unbound,  for example. Note that Unbound is not able to re‐
871              move the pidfile after termination when it is located outside of
872              the chroot directory.
873
874              Additionally,  Unbound  may need to access /dev/urandom (for en‐
875              tropy) from inside the chroot.
876
877              If given a chroot is done to the given directory. By default ch‐
878              root  is  enabled and the default is "/etc/unbound". If you give
879              "" no chroot is performed.
880
881       username: <name>
882              If given,  after  binding  the  port  the  user  privileges  are
883              dropped.  Default is "unbound". If you give username: "" no user
884              change is performed.
885
886              If this user is not capable of binding  the  port,  reloads  (by
887              signal  HUP)  will still retain the opened ports.  If you change
888              the port number in the config file, and that new port number re‐
889              quires privileges, then a reload will fail; a restart is needed.
890
891       directory: <directory>
892              Sets the working directory for the program. Default is "/etc/un‐
893              bound".  On Windows the string "%EXECUTABLE%" tries to change to
894              the  directory  that  unbound.exe  resides  in.   If  you give a
895              server: directory: dir  before  include:  file  statements  then
896              those includes can be relative to the working directory.
897
898       logfile: <filename>
899              If  ""  is given, logging goes to stderr, or nowhere once daemo‐
900              nized.  The logfile is appended to, in the following format:
901              [seconds since 1970] unbound[pid:tid]: type: message.
902              If this option is given, the use-syslog  is  option  is  set  to
903              "no".  The logfile is reopened (for append) when the config file
904              is reread, on SIGHUP.
905
906       use-syslog: <yes or no>
907              Sets Unbound to send log messages to  the  syslogd,  using  sys‐
908              log(3).  The log facility LOG_DAEMON is used, with identity "un‐
909              bound".  The logfile setting is overridden  when  use-syslog  is
910              turned on.  The default is to log to syslog.
911
912       log-identity: <string>
913              If  "" is given (default), then the name of the executable, usu‐
914              ally "unbound" is used to report to the log.  Enter a string  to
915              override  it with that, which is useful on systems that run more
916              than one instance of Unbound, with different configurations,  so
917              that the logs can be easily distinguished against.
918
919       log-time-ascii: <yes or no>
920              Sets  logfile  lines to use a timestamp in UTC ascii. Default is
921              no, which prints the seconds since 1970 in brackets.  No  effect
922              if  using  syslog,  in  that  case  syslog formats the timestamp
923              printed into the log files.
924
925       log-queries: <yes or no>
926              Prints one line per query to the log, with the log timestamp and
927              IP  address, name, type and class.  Default is no.  Note that it
928              takes time to print these lines which makes the server (signifi‐
929              cantly)  slower.   Odd  (nonprintable)  characters  in names are
930              printed as '?'.
931
932       log-replies: <yes or no>
933              Prints one line per reply to the log, with the log timestamp and
934              IP  address,  name,  type,  class, return code, time to resolve,
935              from cache and response size.  Default  is  no.   Note  that  it
936              takes time to print these lines which makes the server (signifi‐
937              cantly) slower.  Odd  (nonprintable)  characters  in  names  are
938              printed as '?'.
939
940       log-tag-queryreply: <yes or no>
941              Prints  the  word  'query'  and  'reply'  with  log-queries  and
942              log-replies.  This makes filtering logs easier.  The default  is
943              off (for backwards compatibility).
944
945       log-local-actions: <yes or no>
946              Print log lines to inform about local zone actions.  These lines
947              are like the local-zone type inform prints  out,  but  they  are
948              also printed for the other types of local zones.
949
950       log-servfail: <yes or no>
951              Print log lines that say why queries return SERVFAIL to clients.
952              This is separate from the verbosity debug  logs,  much  smaller,
953              and printed at the error level, not the info level of debug info
954              from verbosity.
955
956       pidfile: <filename>
957              The process id is written to  the  file.  Default  is  "/run/un‐
958              bound/unbound.pid".  So,
959              kill -HUP `cat /run/unbound/unbound.pid`
960              triggers a reload,
961              kill -TERM `cat /run/unbound/unbound.pid`
962              gracefully terminates.
963
964       root-hints: <filename>
965              Read  the  root  hints from this file. Default is nothing, using
966              builtin hints for the IN class. The file has the format of  zone
967              files,  with  root  nameserver names and addresses only. The de‐
968              fault may become outdated, when servers change, therefore it  is
969              good practice to use a root-hints file.
970
971       hide-identity: <yes or no>
972              If enabled id.server and hostname.bind queries are refused.
973
974       identity: <string>
975              Set  the identity to report. If set to "", the default, then the
976              hostname of the server is returned.
977
978       hide-version: <yes or no>
979              If enabled version.server and version.bind queries are refused.
980
981       version: <string>
982              Set the version to report. If set to "", the default,  then  the
983              package version is returned.
984
985       hide-http-user-agent: <yes or no>
986              If  enabled the HTTP header User-Agent is not set. Use with cau‐
987              tion as some webserver configurations may reject  HTTP  requests
988              lacking  this header.  If needed, it is better to explicitly set
989              the http-user-agent below.
990
991       http-user-agent: <string>
992              Set the HTTP User-Agent header for outgoing  HTTP  requests.  If
993              set  to  "",  the default, then the package name and version are
994              used.
995
996       nsid: <string>
997              Add the specified nsid to the EDNS section of  the  answer  when
998              queried  with an NSID EDNS enabled packet.  As a sequence of hex
999              characters or with ascii_ prefix and then an ascii string.
1000
1001       hide-trustanchor: <yes or no>
1002              If enabled trustanchor.unbound queries are refused.
1003
1004       target-fetch-policy: <"list of numbers">
1005              Set the target fetch policy used by Unbound to determine  if  it
1006              should  fetch nameserver target addresses opportunistically. The
1007              policy is described per dependency depth.
1008
1009              The number of values determines  the  maximum  dependency  depth
1010              that  Unbound  will  pursue in answering a query.  A value of -1
1011              means to fetch all targets opportunistically for that dependency
1012              depth.  A  value  of 0 means to fetch on demand only. A positive
1013              value fetches that many targets opportunistically.
1014
1015              Enclose the list between quotes ("") and put spaces between num‐
1016              bers.   The default is "3 2 1 0 0". Setting all zeroes, "0 0 0 0
1017              0" gives behaviour closer to that of BIND 9, while  setting  "-1
1018              -1  -1  -1  -1" gives behaviour rumoured to be closer to that of
1019              BIND 8.
1020
1021       harden-short-bufsize: <yes or no>
1022              Very small EDNS buffer sizes from queries are  ignored.  Default
1023              is on, as described in the standard.
1024
1025       harden-large-queries: <yes or no>
1026              Very  large queries are ignored. Default is off, since it is le‐
1027              gal protocol wise to send these, and could be necessary for  op‐
1028              eration if TSIG or EDNS payload is very large.
1029
1030       harden-glue: <yes or no>
1031              Will  trust glue only if it is within the servers authority. De‐
1032              fault is yes.
1033
1034       harden-dnssec-stripped: <yes or no>
1035              Require DNSSEC data for trust-anchored zones, if  such  data  is
1036              absent,  the  zone  becomes  bogus. If turned off, and no DNSSEC
1037              data is received (or the DNSKEY data fails  to  validate),  then
1038              the  zone  is made insecure, this behaves like there is no trust
1039              anchor. You could turn this off if you are sometimes  behind  an
1040              intrusive  firewall (of some sort) that removes DNSSEC data from
1041              packets, or a zone changes from  signed  to  unsigned  to  badly
1042              signed  often. If turned off you run the risk of a downgrade at‐
1043              tack that disables security for a zone. Default is yes.
1044
1045       harden-below-nxdomain: <yes or no>
1046              From RFC 8020 (with title "NXDOMAIN: There Really Is Nothing Un‐
1047              derneath"), returns nxdomain to queries for a name below another
1048              name that is already known to be nxdomain.  DNSSEC mandates  no‐
1049              error  for empty nonterminals, hence this is possible.  Very old
1050              software might return nxdomain for empty nonterminals (that usu‐
1051              ally happen for reverse IP address lookups), and thus may be in‐
1052              compatible with this.  To try to avoid this  only  DNSSEC-secure
1053              nxdomains  are  used,  because  the  old  software does not have
1054              DNSSEC.  Default is yes.  The  nxdomain  must  be  secure,  this
1055              means nsec3 with optout is insufficient.
1056
1057       harden-referral-path: <yes or no>
1058              Harden  the  referral  path by performing additional queries for
1059              infrastructure data.  Validates the replies if trust anchors are
1060              configured and the zones are signed.  This enforces DNSSEC vali‐
1061              dation on nameserver NS sets and the nameserver  addresses  that
1062              are encountered on the referral path to the answer.  Default no,
1063              because it burdens the authority servers,  and  it  is  not  RFC
1064              standard,  and could lead to performance problems because of the
1065              extra query load that is generated.   Experimental  option.   If
1066              you  enable  it  consider  adding  more  numbers  after the tar‐
1067              get-fetch-policy to increase the max depth that is checked to.
1068
1069       harden-algo-downgrade: <yes or no>
1070              Harden against algorithm downgrade when multiple algorithms  are
1071              advertised  in  the  DS record.  If no, allows the weakest algo‐
1072              rithm to validate the zone.  Default is no.  Zone  signers  must
1073              produce  zones  that  allow  this feature to work, but sometimes
1074              they do not, and turning this option off avoids that  validation
1075              failure.
1076
1077       use-caps-for-id: <yes or no>
1078              Use  0x20-encoded  random  bits  in  the query to foil spoof at‐
1079              tempts.  This perturbs the  lowercase  and  uppercase  of  query
1080              names  sent  to  authority servers and checks if the reply still
1081              has the correct casing.  Disabled by default.  This  feature  is
1082              an experimental implementation of draft dns-0x20.
1083
1084       caps-exempt: <domain>
1085              Exempt  the  domain so that it does not receive caps-for-id per‐
1086              turbed queries.  For domains that do not support 0x20  and  also
1087              fail  with fallback because they keep sending different answers,
1088              like some load balancers.  Can be given multiple times, for dif‐
1089              ferent domains.
1090
1091       caps-whitelist: <yes or no>
1092              Alternate syntax for caps-exempt.
1093
1094       qname-minimisation: <yes or no>
1095              Send  minimum  amount  of information to upstream servers to en‐
1096              hance privacy.  Only send minimum required labels of  the  QNAME
1097              and  set  QTYPE  to  A when possible. Best effort approach; full
1098              QNAME and original QTYPE will be sent when upstream replies with
1099              a  RCODE other than NOERROR, except when receiving NXDOMAIN from
1100              a DNSSEC signed zone. Default is yes.
1101
1102       qname-minimisation-strict: <yes or no>
1103              QNAME minimisation in strict mode. Do not fall-back  to  sending
1104              full  QNAME  to potentially broken nameservers. A lot of domains
1105              will not be resolvable when this option in enabled. Only use  if
1106              you  know  what you are doing.  This option only has effect when
1107              qname-minimisation is enabled. Default is no.
1108
1109       aggressive-nsec: <yes or no>
1110              Aggressive NSEC uses the DNSSEC NSEC chain to  synthesize  NXDO‐
1111              MAIN  and  other  denials, using information from previous NXDO‐
1112              MAINs answers.  Default is yes.  It helps to  reduce  the  query
1113              rate  towards  targets  that  get  a  very high nonexistent name
1114              lookup rate.
1115
1116       private-address: <IP address or subnet>
1117              Give IPv4 of IPv6 addresses or classless subnets. These are  ad‐
1118              dresses  on  your private network, and are not allowed to be re‐
1119              turned for public internet names.  Any occurrence  of  such  ad‐
1120              dresses  are  removed from DNS answers. Additionally, the DNSSEC
1121              validator may mark the  answers  bogus.  This  protects  against
1122              so-called  DNS  Rebinding, where a user browser is turned into a
1123              network proxy, allowing remote access  through  the  browser  to
1124              other  parts of your private network.  Some names can be allowed
1125              to contain your private addresses, by default all the local-data
1126              that  you  configured  is  allowed to, and you can specify addi‐
1127              tional names using private-domain.  No private addresses are en‐
1128              abled  by  default.   We consider to enable this for the RFC1918
1129              private IP address space by  default  in  later  releases.  That
1130              would  enable  private  addresses  for  10.0.0.0/8 172.16.0.0/12
1131              192.168.0.0/16 169.254.0.0/16 fd00::/8 and fe80::/10, since  the
1132              RFC  standards  say these addresses should not be visible on the
1133              public internet.  Turning on 127.0.0.0/8 would hinder many spam‐
1134              blocklists   as  they  use  that.   Adding  ::ffff:0:0/96  stops
1135              IPv4-mapped IPv6 addresses from bypassing the filter.
1136
1137       private-domain: <domain name>
1138              Allow this domain, and all its subdomains to contain private ad‐
1139              dresses.   Give multiple times to allow multiple domain names to
1140              contain private addresses. Default is none.
1141
1142       unwanted-reply-threshold: <number>
1143              If set, a total number of unwanted replies is kept track  of  in
1144              every thread.  When it reaches the threshold, a defensive action
1145              is taken and a warning is printed to the log.  The defensive ac‐
1146              tion  is to clear the rrset and message caches, hopefully flush‐
1147              ing away any poison.  A value of 10 million is  suggested.   De‐
1148              fault is 0 (turned off).
1149
1150       do-not-query-address: <IP address>
1151              Do  not  query  the  given IP address. Can be IP4 or IP6. Append
1152              /num to indicate a classless delegation  netblock,  for  example
1153              like 10.2.3.4/24 or 2001::11/64.
1154
1155       do-not-query-localhost: <yes or no>
1156              If  yes, localhost is added to the do-not-query-address entries,
1157              both IP6 ::1 and IP4 127.0.0.1/8. If no, then localhost  can  be
1158              used to send queries to. Default is yes.
1159
1160       prefetch: <yes or no>
1161              If yes, message cache elements are prefetched before they expire
1162              to keep the cache up to date.  Default is  no.   Turning  it  on
1163              gives about 10 percent more traffic and load on the machine, but
1164              popular items do not expire from the cache.
1165
1166       prefetch-key: <yes or no>
1167              If yes, fetch the DNSKEYs earlier  in  the  validation  process,
1168              when a DS record is encountered.  This lowers the latency of re‐
1169              quests.  It does use a little more CPU.  Also if  the  cache  is
1170              set to 0, it is no use. Default is no.
1171
1172       deny-any: <yes or no>
1173              If  yes,  deny  queries of type ANY with an empty response.  De‐
1174              fault is no.  If disabled, Unbound responds with a short list of
1175              resource records if some can be found in the cache and makes the
1176              upstream type ANY query if there are none.
1177
1178       rrset-roundrobin: <yes or no>
1179              If yes, Unbound rotates RRSet order in response (the random num‐
1180              ber  is  taken  from the query ID, for speed and thread safety).
1181              Default is yes.
1182
1183       minimal-responses: <yes or no>
1184              If yes, Unbound does not  insert  authority/additional  sections
1185              into  response  messages  when  those sections are not required.
1186              This reduces response size  significantly,  and  may  avoid  TCP
1187              fallback  for  some responses.  This may cause a slight speedup.
1188              The default is yes, even though the DNS  protocol  RFCs  mandate
1189              these  sections,  and the additional content could be of use and
1190              save roundtrips for clients.  Because they are not used, and the
1191              saved  roundtrips are easier saved with prefetch, whilst this is
1192              faster.
1193
1194       disable-dnssec-lame-check: <yes or no>
1195              If true, disables the DNSSEC lameness  check  in  the  iterator.
1196              This check sees if RRSIGs are present in the answer, when dnssec
1197              is expected, and retries another authority if RRSIGs  are  unex‐
1198              pectedly  missing.   The  validator  will  insist  in RRSIGs for
1199              DNSSEC signed domains regardless of this setting, if a trust an‐
1200              chor is loaded.
1201
1202       module-config: <"module names">
1203              Module  configuration,  a list of module names separated by spa‐
1204              ces, surround the string with quotes (""). The  modules  can  be
1205              respip,  validator,  or iterator (and possibly more, see below).
1206              Setting this to just "iterator" will result in a  non-validating
1207              server.   Setting  this  to  "validator  iterator"  will turn on
1208              DNSSEC validation.  The ordering of the modules is  significant,
1209              the  order  decides  the order of processing.  You must also set
1210              trust-anchors for validation to be useful.  Adding respip to the
1211              front  will cause RPZ processing to be done on all queries.  The
1212              default is "validator iterator".
1213
1214              When the server is built with EDNS client subnet support the de‐
1215              fault  is  "subnetcache  validator iterator".  Most modules that
1216              need to be listed here have to be listed at the beginning of the
1217              line.  The subnetcachedb module has to be listed just before the
1218              iterator.  The python module can be listed in different  places,
1219              it  then  processes  the output of the module it is just before.
1220              The dynlib module can be listed pretty much anywhere, it is only
1221              a  very thin wrapper that allows dynamic libraries to run in its
1222              place.
1223
1224       trust-anchor-file: <filename>
1225              File with trusted keys for validation. Both DS  and  DNSKEY  en‐
1226              tries  can  appear  in  the  file. The format of the file is the
1227              standard DNS Zone file format.  Default is "", or no  trust  an‐
1228              chor file.
1229
1230       auto-trust-anchor-file: <filename>
1231              File  with  trust  anchor  for  one  zone, which is tracked with
1232              RFC5011 probes.  The probes are run  several  times  per  month,
1233              thus  the  machine  must be online frequently.  The initial file
1234              can be one with contents as described in trust-anchor-file.  The
1235              file  is  written  to when the anchor is updated, so the Unbound
1236              user must have write permission.  Write permission to the  file,
1237              but  also to the directory it is in (to create a temporary file,
1238              which is necessary to deal with filesystem full events), it must
1239              also be inside the chroot (if that is used).
1240
1241       trust-anchor: <"Resource Record">
1242              A  DS or DNSKEY RR for a key to use for validation. Multiple en‐
1243              tries can be given to specify multiple trusted keys, in addition
1244              to  the  trust-anchor-files.   The resource record is entered in
1245              the same format as 'dig' or 'drill' prints them, the same format
1246              as  in the zone file. Has to be on a single line, with "" around
1247              it. A TTL can be specified for ease of cut and paste, but is ig‐
1248              nored.  A class can be specified, but class IN is default.
1249
1250       trusted-keys-file: <filename>
1251              File  with  trusted  keys  for validation. Specify more than one
1252              file with several entries, one file per  entry.  Like  trust-an‐
1253              chor-file  but  has  a  different  file format. Format is BIND-9
1254              style format, the trusted-keys { name flag proto algo "key";  };
1255              clauses  are  read.   It  is possible to use wildcards with this
1256              statement, the wildcard is expanded on start and on reload.
1257
1258       trust-anchor-signaling: <yes or no>
1259              Send RFC8145 key tag query after trust anchor  priming.  Default
1260              is yes.
1261
1262       root-key-sentinel: <yes or no>
1263              Root key trust anchor sentinel. Default is yes.
1264
1265       domain-insecure: <domain name>
1266              Sets  domain  name  to be insecure, DNSSEC chain of trust is ig‐
1267              nored towards the domain name.  So a trust anchor above the  do‐
1268              main  name can not make the domain secure with a DS record, such
1269              a DS record is then ignored.  Can be  given  multiple  times  to
1270              specify  multiple  domains  that are treated as if unsigned.  If
1271              you set trust anchors for the domain they override this  setting
1272              (and the domain is secured).
1273
1274              This  can  be useful if you want to make sure a trust anchor for
1275              external lookups does not affect an (unsigned) internal  domain.
1276              A  DS  record externally can create validation failures for that
1277              internal domain.
1278
1279       val-override-date: <rrsig-style date spec>
1280              Default is "" or "0", which disables this debugging feature.  If
1281              enabled by giving a RRSIG style date, that date is used for ver‐
1282              ifying RRSIG inception and expiration dates, instead of the cur‐
1283              rent  date.  Do  not set this unless you are debugging signature
1284              inception and expiration. The value -1 ignores  the  date  alto‐
1285              gether, useful for some special applications.
1286
1287       val-sig-skew-min: <seconds>
1288              Minimum  number  of  seconds of clock skew to apply to validated
1289              signatures.  A value of 10% of the signature  lifetime  (expira‐
1290              tion  -  inception) is used, capped by this setting.  Default is
1291              3600 (1 hour) which allows  for  daylight  savings  differences.
1292              Lower  this value for more strict checking of short lived signa‐
1293              tures.
1294
1295       val-sig-skew-max: <seconds>
1296              Maximum number of seconds of clock skew to  apply  to  validated
1297              signatures.   A  value of 10% of the signature lifetime (expira‐
1298              tion - inception) is used, capped by this setting.   Default  is
1299              86400  (24  hours) which allows for timezone setting problems in
1300              stable domains.  Setting both min and max very low disables  the
1301              clock skew allowances.  Setting both min and max very high makes
1302              the validator check the signature timestamps less strictly.
1303
1304       val-max-restart: <number>
1305              The maximum number the validator should restart validation  with
1306              another authority in case of failed validation. Default is 5.
1307
1308       val-bogus-ttl: <number>
1309              The  time  to  live for bogus data. This is data that has failed
1310              validation; due to invalid signatures or other checks.  The  TTL
1311              from  that  data  cannot  be trusted, and this value is used in‐
1312              stead. The value is in seconds, default 60.  The  time  interval
1313              prevents repeated revalidation of bogus data.
1314
1315       val-clean-additional: <yes or no>
1316              Instruct  the  validator to remove data from the additional sec‐
1317              tion of secure messages that are not signed  properly.  Messages
1318              that are insecure, bogus, indeterminate or unchecked are not af‐
1319              fected. Default is yes. Use this setting to  protect  the  users
1320              that  rely on this validator for authentication from potentially
1321              bad data in the additional section.
1322
1323       val-log-level: <number>
1324              Have the validator print validation failures to  the  log.   Re‐
1325              gardless  of  the  verbosity setting.  Default is 0, off.  At 1,
1326              for every user query that fails a line is printed to  the  logs.
1327              This  way  you  can monitor what happens with validation.  Use a
1328              diagnosis tool, such as dig or drill, to find out why validation
1329              is  failing  for  these  queries.  At 2, not only the query that
1330              failed is printed but also the reason why Unbound thought it was
1331              wrong and which server sent the faulty data.
1332
1333       val-permissive-mode: <yes or no>
1334              Instruct  the validator to mark bogus messages as indeterminate.
1335              The security checks are performed, but if the  result  is  bogus
1336              (failed  security),  the  reply  is not withheld from the client
1337              with SERVFAIL as usual. The client receives the bogus data.  For
1338              messages  that  are  found  to  be  secure  the AD bit is set in
1339              replies. Also logging is performed as for full validation.   The
1340              default value is "no".
1341
1342       ignore-cd-flag: <yes or no>
1343              Instruct  Unbound  to ignore the CD flag from clients and refuse
1344              to return bogus answers to them.  Thus, the  CD  (Checking  Dis‐
1345              abled)  flag does not disable checking any more.  This is useful
1346              if legacy (w2008) servers that set the CD flag but cannot  vali‐
1347              date  DNSSEC  themselves  are the clients, and then Unbound pro‐
1348              vides them with DNSSEC protection.  The default value is "no".
1349
1350       serve-expired: <yes or no>
1351              If enabled, Unbound attempts to serve old responses  from  cache
1352              with  a  TTL  of serve-expired-reply-ttl in the response without
1353              waiting for the actual resolution to finish.  The actual resolu‐
1354              tion answer ends up in the cache later on.  Default is "no".
1355
1356       serve-expired-ttl: <seconds>
1357              Limit  serving  of expired responses to configured seconds after
1358              expiration. 0 disables the limit.  This option only applies when
1359              serve-expired is enabled.  A suggested value per RFC 8767 is be‐
1360              tween 86400 (1 day) and 259200 (3 days).  The default is 0.
1361
1362       serve-expired-ttl-reset: <yes or no>
1363              Set the TTL of expired records to  the  serve-expired-ttl  value
1364              after  a  failed  attempt  to retrieve the record from upstream.
1365              This makes sure that the expired records will be served as  long
1366              as there are queries for it.  Default is "no".
1367
1368       serve-expired-reply-ttl: <seconds>
1369              TTL  value to use when replying with expired data.  If serve-ex‐
1370              pired-client-timeout is also used then it is RECOMMENDED to  use
1371              30 as the value (RFC 8767).  The default is 30.
1372
1373       serve-expired-client-timeout: <msec>
1374              Time  in milliseconds before replying to the client with expired
1375              data.  This essentially  enables  the  serve-stale  behavior  as
1376              specified in RFC 8767 that first tries to resolve before immedi‐
1377              ately responding with expired data.  A recommended value per RFC
1378              8767  is  1800.   Setting  this to 0 will disable this behavior.
1379              Default is 0.
1380
1381       serve-original-ttl: <yes or no>
1382              If enabled, Unbound will always return the original TTL  as  re‐
1383              ceived  from the upstream name server rather than the decrement‐
1384              ing TTL as stored in the cache.  This feature may be  useful  if
1385              Unbound  serves  as  a  front-end to a hidden authoritative name
1386              server. Enabling this feature does not impact cache  expiry,  it
1387              only  changes  the  TTL  Unbound embeds in responses to queries.
1388              Note that enabling this feature implicitly disables  enforcement
1389              of  the  configured  minimum  and  maximum TTL, as it is assumed
1390              users who enable this feature do not want Unbound to change  the
1391              TTL  obtained from an upstream server.  Thus, the values set us‐
1392              ing cache-min-ttl and cache-max-ttl  are  ignored.   Default  is
1393              "no".
1394
1395       val-nsec3-keysize-iterations: <"list of values">
1396              List of keysize and iteration count values, separated by spaces,
1397              surrounded by quotes. Default is "1024 150 2048 150  4096  150".
1398              This determines the maximum allowed NSEC3 iteration count before
1399              a message is simply marked insecure instead  of  performing  the
1400              many hashing iterations. The list must be in ascending order and
1401              have at least one entry. If you set it to "1024 65535" there  is
1402              no  restriction  to  NSEC3 iteration values.  This table must be
1403              kept short; a very long list could cause slower operation.
1404
1405       zonemd-permissive-mode: <yes or no>
1406              If enabled the ZONEMD verification failures are only logged  and
1407              do  not  cause  the zone to be blocked and only return servfail.
1408              Useful for testing out if it works,  or  if  the  operator  only
1409              wants  to  be  notified of a problem without disrupting service.
1410              Default is no.
1411
1412       add-holddown: <seconds>
1413              Instruct the auto-trust-anchor-file probe mechanism for  RFC5011
1414              autotrust  updates to add new trust anchors only after they have
1415              been visible for this time.  Default is 30 days as per the RFC.
1416
1417       del-holddown: <seconds>
1418              Instruct the auto-trust-anchor-file probe mechanism for  RFC5011
1419              autotrust  updates  to  remove  revoked trust anchors after they
1420              have been kept in the revoked list for this long.  Default is 30
1421              days as per the RFC.
1422
1423       keep-missing: <seconds>
1424              Instruct  the auto-trust-anchor-file probe mechanism for RFC5011
1425              autotrust updates to remove missing  trust  anchors  after  they
1426              have  been  unseen for this long.  This cleans up the state file
1427              if the target zone does not perform trust anchor revocation,  so
1428              this makes the auto probe mechanism work with zones that perform
1429              regular (non-5011) rollovers.  The default  is  366  days.   The
1430              value 0 does not remove missing anchors, as per the RFC.
1431
1432       permit-small-holddown: <yes or no>
1433              Debug  option  that allows the autotrust 5011 rollover timers to
1434              assume very small values.  Default is no.
1435
1436       key-cache-size: <number>
1437              Number of bytes size of the key cache. Default is  4  megabytes.
1438              A  plain  number  is  in bytes, append 'k', 'm' or 'g' for kilo‐
1439              bytes, megabytes or gigabytes (1024*1024 bytes in a megabyte).
1440
1441       key-cache-slabs: <number>
1442              Number of slabs in the key cache. Slabs reduce  lock  contention
1443              by threads.  Must be set to a power of 2. Setting (close) to the
1444              number of cpus is a reasonable guess.
1445
1446       neg-cache-size: <number>
1447              Number of bytes size of the aggressive negative  cache.  Default
1448              is  1  megabyte.  A plain number is in bytes, append 'k', 'm' or
1449              'g' for kilobytes, megabytes or gigabytes (1024*1024 bytes in  a
1450              megabyte).
1451
1452       unblock-lan-zones: <yes or no>
1453              Default  is  disabled.   If  enabled,  then  for private address
1454              space, the reverse lookups are no longer filtered.  This  allows
1455              Unbound  when running as dns service on a host where it provides
1456              service for that host, to put out all of  the  queries  for  the
1457              'lan' upstream.  When enabled, only localhost, 127.0.0.1 reverse
1458              and ::1 reverse zones are configured with default  local  zones.
1459              Disable the option when Unbound is running as a (DHCP-) DNS net‐
1460              work resolver for a group of machines, where such lookups should
1461              be  filtered  (RFC  compliance),  this also stops potential data
1462              leakage about the local network to the upstream DNS servers.
1463
1464       insecure-lan-zones: <yes or no>
1465              Default is disabled.  If enabled, then reverse lookups  in  pri‐
1466              vate  address space are not validated.  This is usually required
1467              whenever unblock-lan-zones is used.
1468
1469       local-zone: <zone> <type>
1470              Configure a local zone. The type determines the answer  to  give
1471              if  there  is  no  match  from  local-data.  The types are deny,
1472              refuse, static, transparent, redirect, nodefault,  typetranspar‐
1473              ent,  inform,  inform_deny, inform_redirect, always_transparent,
1474              always_refuse, always_nxdomain, always_null, noview, and are ex‐
1475              plained  below.  After that the default settings are listed. Use
1476              local-data: to enter data into the local zone. Answers for local
1477              zones  are  authoritative  DNS answers. By default the zones are
1478              class IN.
1479
1480              If you need more complicated authoritative data, with referrals,
1481              wildcards, CNAME/DNAME support, or DNSSEC authoritative service,
1482              setup a stub-zone for it as detailed in the  stub  zone  section
1483              below.  A  stub-zone can be used to have unbound send queries to
1484              another server, an authoritative server, to fetch  the  informa‐
1485              tion.  With  a  forward-zone,  unbound sends queries to a server
1486              that is a recursive server to fetch  the  information.  With  an
1487              auth-zone  a  zone  can  be loaded from file and used, it can be
1488              used like a local-zone for users downstream,  or  the  auth-zone
1489              information can be used to fetch information from when resolving
1490              like it is an upstream server. The  forward-zone  and  auth-zone
1491              options  are  described in their sections below.  If you want to
1492              perform filtering of the information that the users  can  fetch,
1493              the  local-zone  and  local-data  statements allow for this, but
1494              also the rpz functionality can be used,  described  in  the  RPZ
1495              section.
1496
1497            deny Do  not  send an answer, drop the query.  If there is a match
1498                 from local data, the query is answered.
1499
1500            refuse
1501                 Send an error message reply, with rcode REFUSED.  If there is
1502                 a match from local data, the query is answered.
1503
1504            static
1505                 If  there  is a match from local data, the query is answered.
1506                 Otherwise, the query is answered  with  nodata  or  nxdomain.
1507                 For  a  negative  answer  a  SOA is included in the answer if
1508                 present as local-data for the zone apex domain.
1509
1510            transparent
1511                 If there is a match from local data, the query  is  answered.
1512                 Otherwise if the query has a different name, the query is re‐
1513                 solved normally.  If the query is for a name given in  local‐
1514                 data  but  no such type of data is given in localdata, then a
1515                 noerror nodata answer is returned.  If no local-zone is given
1516                 local-data  causes  a  transparent  zone to be created by de‐
1517                 fault.
1518
1519            typetransparent
1520                 If there is a match from local data, the query  is  answered.
1521                 If  the  query  is for a different name, or for the same name
1522                 but for a different type, the  query  is  resolved  normally.
1523                 So,  similar  to transparent but types that are not listed in
1524                 local data are resolved normally, so if an A record is in the
1525                 local  data  that  does  not  cause  a  nodata reply for AAAA
1526                 queries.
1527
1528            redirect
1529                 The query is answered from the local data for the zone  name.
1530                 There  may  be no local data beneath the zone name.  This an‐
1531                 swers queries for the zone, and all subdomains  of  the  zone
1532                 with the local data for the zone.  It can be used to redirect
1533                 a domain to return a different  address  record  to  the  end
1534                 user,   with  local-zone:  "example.com."  redirect  and  lo‐
1535                 cal-data: "example.com. A 127.0.0.1"  queries  for  www.exam‐
1536                 ple.com and www.foo.example.com are redirected, so that users
1537                 with web browsers  cannot  access  sites  with  suffix  exam‐
1538                 ple.com.
1539
1540            inform
1541                 The  query  is  answered  normally, same as transparent.  The
1542                 client IP address (@portnumber) is printed  to  the  logfile.
1543                 The  log  message  is: timestamp, unbound-pid, info: zonename
1544                 inform IP@port queryname type class.  This option can be used
1545                 for normal resolution, but machines looking up infected names
1546                 are logged, eg. to run antivirus on them.
1547
1548            inform_deny
1549                 The query is dropped, like 'deny', and logged, like 'inform'.
1550                 Ie. find infected machines without answering the queries.
1551
1552            inform_redirect
1553                 The  query  is  redirected, like 'redirect', and logged, like
1554                 'inform'.  Ie. answer queries with fixed data  and  also  log
1555                 the machines that ask.
1556
1557            always_transparent
1558                 Like  transparent,  but  ignores local data and resolves nor‐
1559                 mally.
1560
1561            always_refuse
1562                 Like refuse, but ignores local data and refuses the query.
1563
1564            always_nxdomain
1565                 Like static, but ignores local data and returns nxdomain  for
1566                 the query.
1567
1568            always_nodata
1569                 Like  static,  but  ignores local data and returns nodata for
1570                 the query.
1571
1572            always_deny
1573                 Like deny, but ignores local data and drops the query.
1574
1575            always_null
1576                 Always returns 0.0.0.0 or ::0 for every  name  in  the  zone.
1577                 Like  redirect  with zero data for A and AAAA.  Ignores local
1578                 data in the zone.  Used for some block lists.
1579
1580            noview
1581                 Breaks out of that view and moves towards  the  global  local
1582                 zones  for  answer  to  the  query.  If the view first is no,
1583                 it'll resolve normally.  If  view  first  is  enabled,  it'll
1584                 break  perform  that  step and check the global answers.  For
1585                 when the view has view specific overrides but some  zone  has
1586                 to be answered from global local zone contents.
1587
1588            nodefault
1589                 Used  to turn off default contents for AS112 zones. The other
1590                 types also turn off default contents for the zone. The 'node‐
1591                 fault'  option  has  no other effect than turning off default
1592                 contents for the given zone.  Use nodefault if  you  use  ex‐
1593                 actly  that zone, if you want to use a subzone, use transpar‐
1594                 ent.
1595
1596       The default  zones  are  localhost,  reverse  127.0.0.1  and  ::1,  the
1597       home.arpa,  the  onion,  test,  invalid  and the AS112 zones. The AS112
1598       zones are reverse DNS zones for private use and reserved  IP  addresses
1599       for  which  the servers on the internet cannot provide correct answers.
1600       They are configured by default to give nxdomain  (no  reverse  informa‐
1601       tion)  answers.  The  defaults can be turned off by specifying your own
1602       local-zone of that name, or using the 'nodefault' type. Below is a list
1603       of the default zone contents.
1604
1605            localhost
1606                 The  IP4  and  IP6 localhost information is given. NS and SOA
1607                 records are provided for completeness and to satisfy some DNS
1608                 update tools. Default content:
1609                 local-zone: "localhost." redirect
1610                 local-data: "localhost. 10800 IN NS localhost."
1611                 local-data: "localhost. 10800 IN
1612                     SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1613                 local-data: "localhost. 10800 IN A 127.0.0.1"
1614                 local-data: "localhost. 10800 IN AAAA ::1"
1615
1616            reverse IPv4 loopback
1617                 Default content:
1618                 local-zone: "127.in-addr.arpa." static
1619                 local-data: "127.in-addr.arpa. 10800 IN NS localhost."
1620                 local-data: "127.in-addr.arpa. 10800 IN
1621                     SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1622                 local-data: "1.0.0.127.in-addr.arpa. 10800 IN
1623                     PTR localhost."
1624
1625            reverse IPv6 loopback
1626                 Default content:
1627                 local-zone: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
1628                     0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." static
1629                 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
1630                     0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
1631                     NS localhost."
1632                 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
1633                     0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
1634                     SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1635                 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
1636                     0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
1637                     PTR localhost."
1638
1639            home.arpa (RFC 8375)
1640                 Default content:
1641                 local-zone: "home.arpa." static
1642                 local-data: "home.arpa. 10800 IN NS localhost."
1643                 local-data: "home.arpa. 10800 IN
1644                     SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1645
1646            onion (RFC 7686)
1647                 Default content:
1648                 local-zone: "onion." static
1649                 local-data: "onion. 10800 IN NS localhost."
1650                 local-data: "onion. 10800 IN
1651                     SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1652
1653            test (RFC 6761)
1654                 Default content:
1655                 local-zone: "test." static
1656                 local-data: "test. 10800 IN NS localhost."
1657                 local-data: "test. 10800 IN
1658                     SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1659
1660            invalid (RFC 6761)
1661                 Default content:
1662                 local-zone: "invalid." static
1663                 local-data: "invalid. 10800 IN NS localhost."
1664                 local-data: "invalid. 10800 IN
1665                     SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1666
1667            reverse RFC1918 local use zones
1668                 Reverse  data  for zones 10.in-addr.arpa, 16.172.in-addr.arpa
1669                 to  31.172.in-addr.arpa,   168.192.in-addr.arpa.    The   lo‐
1670                 cal-zone: is set static and as local-data: SOA and NS records
1671                 are provided.
1672
1673            reverse RFC3330 IP4 this, link-local, testnet and broadcast
1674                 Reverse data for zones 0.in-addr.arpa,  254.169.in-addr.arpa,
1675                 2.0.192.in-addr.arpa  (TEST  NET  1), 100.51.198.in-addr.arpa
1676                 (TEST  NET   2),   113.0.203.in-addr.arpa   (TEST   NET   3),
1677                 255.255.255.255.in-addr.arpa.   And  from 64.100.in-addr.arpa
1678                 to 127.100.in-addr.arpa (Shared Address Space).
1679
1680            reverse RFC4291 IP6 unspecified
1681                 Reverse data for zone
1682                 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
1683                 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa.
1684
1685            reverse RFC4193 IPv6 Locally Assigned Local Addresses
1686                 Reverse data for zone D.F.ip6.arpa.
1687
1688            reverse RFC4291 IPv6 Link Local Addresses
1689                 Reverse data for zones 8.E.F.ip6.arpa to B.E.F.ip6.arpa.
1690
1691            reverse IPv6 Example Prefix
1692                 Reverse data for zone 8.B.D.0.1.0.0.2.ip6.arpa. This zone  is
1693                 used  for tutorials and examples. You can remove the block on
1694                 this zone with:
1695                   local-zone: 8.B.D.0.1.0.0.2.ip6.arpa. nodefault
1696                 You can also selectively unblock a part of the zone by making
1697                 that part transparent with a local-zone statement.  This also
1698                 works with the other default zones.
1699
1700       local-data: "<resource record string>"
1701            Configure local data, which is served in reply to queries for  it.
1702            The query has to match exactly unless you configure the local-zone
1703            as redirect. If not matched exactly, the  local-zone  type  deter‐
1704            mines  further processing. If local-data is configured that is not
1705            a subdomain of a local-zone, a transparent local-zone  is  config‐
1706            ured.   For record types such as TXT, use single quotes, as in lo‐
1707            cal-data: 'example. TXT "text"'.
1708
1709            If you need more complicated authoritative data,  with  referrals,
1710            wildcards,  CNAME/DNAME  support, or DNSSEC authoritative service,
1711            setup a stub-zone for it as detailed in the stub zone section  be‐
1712            low.
1713
1714       local-data-ptr: "IPaddr name"
1715            Configure  local data shorthand for a PTR record with the reversed
1716            IPv4 or IPv6 address and the host name.   For  example  "192.0.2.4
1717            www.example.com".   TTL  can  be  inserted like this: "2001:DB8::4
1718            7200 www.example.com"
1719
1720       local-zone-tag: <zone> <"list of tags">
1721            Assign tags to localzones. Tagged localzones will only be  applied
1722            when the used access-control element has a matching tag. Tags must
1723            be defined in define-tags.  Enclose list of tags  in  quotes  ("")
1724            and  put  spaces  between  tags.   When there are multiple tags it
1725            checks if the intersection of the list of tags for the  query  and
1726            local-zone-tag is non-empty.
1727
1728       local-zone-override: <zone> <IP netblock> <type>
1729            Override  the  localzone  type for queries from addresses matching
1730            netblock.  Use this localzone type, regardless the type configured
1731            for  the  local-zone (both tagged and untagged) and regardless the
1732            type configured using access-control-tag-action.
1733
1734       response-ip: <IP-netblock> <action>
1735            This requires use of the "respip" module.
1736
1737            If the IP address in an AAAA or A RR in the answer  section  of  a
1738            response  matches  the specified IP netblock, the specified action
1739            will apply.  <action> has generally the same semantics as that for
1740            access-control-tag-action, but there are some exceptions.
1741
1742            Actions for response-ip are different from those for local-zone in
1743            that in case of the former there is no point of such conditions as
1744            "the  query  matches  it  but there is no local data".  Because of
1745            this difference, the semantics of response-ip actions are modified
1746            or  simplified  as follows: The static, refuse, transparent, type‐
1747            transparent, and nodefault actions are  invalid  for  response-ip.
1748            Using  any of these will cause the configuration to be rejected as
1749            faulty. The deny action is non-conditional, i.e. it always results
1750            in dropping the corresponding query.  The resolution result before
1751            applying the deny action is still cached and can be used for other
1752            queries.
1753
1754       response-ip-data: <IP-netblock> <"resource record string">
1755            This requires use of the "respip" module.
1756
1757            This  specifies  the action data for response-ip with action being
1758            to redirect as specified by "resource record  string".   "Resource
1759            record  string"  is  similar to that of access-control-tag-action,
1760            but it must be of either AAAA, A or CNAME types.  If  the  IP-net‐
1761            block  is  an  IPv6/IPv4 prefix, the record must be AAAA/A respec‐
1762            tively, unless it is a CNAME (which can be used for both  versions
1763            of  IP netblocks).  If it is CNAME there must not be more than one
1764            response-ip-data for the same IP-netblock.  Also, CNAME and  other
1765            types  of  records must not coexist for the same IP-netblock, fol‐
1766            lowing the normal rules for CNAME  records.   The  textual  domain
1767            name  for the CNAME does not have to be explicitly terminated with
1768            a dot ("."); the root name is assumed to be  the  origin  for  the
1769            name.
1770
1771       response-ip-tag: <IP-netblock> <"list of tags">
1772            This requires use of the "respip" module.
1773
1774            Assign  tags  to  response  IP-netblocks.  If the IP address in an
1775            AAAA or A RR in the answer section of a response matches the spec‐
1776            ified  IP-netblock,  the specified tags are assigned to the IP ad‐
1777            dress.  Then, if an access-control-tag is defined for  the  client
1778            and  it  includes  one of the tags for the response IP, the corre‐
1779            sponding access-control-tag-action will apply.  Tag matching  rule
1780            is  the  same as that for access-control-tag and local-zones.  Un‐
1781            like local-zone-tag, response-ip-tag can be defined for an IP-net‐
1782            block  even  if  no  response-ip is defined for that netblock.  If
1783            multiple response-ip-tag options are specified for  the  same  IP-
1784            netblock  in  different  statements, all but the first will be ig‐
1785            nored.  However, this will not be flagged as a  configuration  er‐
1786            ror, but the result is probably not what was intended.
1787
1788            Actions  specified  in  an  access-control-tag-action  that  has a
1789            matching tag with response-ip-tag can be those that are  "invalid"
1790            for response-ip listed above, since access-control-tag-actions can
1791            be shared with local zones.  For these  actions,  if  they  behave
1792            differently  depending on whether local data exists or not in case
1793            of local zones, the behavior for response-ip-data  will  generally
1794            result  in NOERROR/NODATA instead of NXDOMAIN, since the response-
1795            ip data are inherently type specific, and  non-existence  of  data
1796            does not indicate anything about the existence or non-existence of
1797            the qname itself.  For example, if  the  matching  tag  action  is
1798            static but there is no data for the corresponding response-ip con‐
1799            figuration, then the result will be NOERROR/NODATA.  The only case
1800            where  NXDOMAIN  is returned is when an always_nxdomain action ap‐
1801            plies.
1802
1803       ratelimit: <number or 0>
1804            Enable ratelimiting of queries sent to nameserver  for  performing
1805            recursion.  If 0, the default, it is disabled.  This option is ex‐
1806            perimental at this time.  The ratelimit is in queries  per  second
1807            that  are  allowed.   More  queries  are turned away with an error
1808            (servfail).  This stops recursive floods, eg. random query  names,
1809            but not spoofed reflection floods.  Cached responses are not rate‐
1810            limited by this setting.  The zone of the query is  determined  by
1811            examining  the  nameservers  for it, the zone name is used to keep
1812            track of the rate.  For example, 1000 may be a suitable  value  to
1813            stop the server from being overloaded with random names, and keeps
1814            Unbound from sending traffic to the nameservers for  those  zones.
1815            Configured forwarders are excluded from ratelimiting.
1816
1817       ratelimit-size: <memory size>
1818            Give  the  size of the data structure in which the current ongoing
1819            rates are kept track in.  Default 4m.  In bytes  or  use  m(mega),
1820            k(kilo),  g(giga).  The ratelimit structure is small, so this data
1821            structure likely does not need to be large.
1822
1823       ratelimit-slabs: <number>
1824            Give power of 2 number of slabs, this is used to reduce lock  con‐
1825            tention  in  the  ratelimit tracking data structure.  Close to the
1826            number of cpus is a fairly good setting.
1827
1828       ratelimit-factor: <number>
1829            Set the amount of queries to rate limit  when  the  limit  is  ex‐
1830            ceeded.   If  set  to 0, all queries are dropped for domains where
1831            the limit is exceeded.  If set to another value, 1 in that  number
1832            is  allowed  through  to  complete.   Default is 10, allowing 1/10
1833            traffic to flow normally.  This can make ordinary queries complete
1834            (if repeatedly queried for), and enter the cache, whilst also mit‐
1835            igating the traffic flow by the factor given.
1836
1837       ratelimit-backoff: <yes or no>
1838            If enabled, the ratelimit is treated as a hard failure instead  of
1839            the  default  maximum  allowed  constant  rate.  When the limit is
1840            reached, traffic is ratelimited and demand continues  to  be  kept
1841            track  of  for a 2 second rate window.  No traffic is allowed, ex‐
1842            cept for ratelimit-factor, until demand decreases below  the  con‐
1843            figured ratelimit for a 2 second rate window.  Useful to set rate‐
1844            limit to a suspicious rate to aggressively  limit  unusually  high
1845            traffic.  Default is off.
1846
1847       ratelimit-for-domain: <domain> <number qps or 0>
1848            Override  the global ratelimit for an exact match domain name with
1849            the listed number.  You can give this for  any  number  of  names.
1850            For  example, for a top-level-domain you may want to have a higher
1851            limit than other names.  A value of 0  will  disable  ratelimiting
1852            for that domain.
1853
1854       ratelimit-below-domain: <domain> <number qps or 0>
1855            Override  the global ratelimit for a domain name that ends in this
1856            name.  You can give this multiple times, it then describes differ‐
1857            ent  settings  in  different  parts of the namespace.  The closest
1858            matching suffix is used to determine the qps limit.  The rate  for
1859            the   exact  matching  domain  name  is  not  changed,  use  rate‐
1860            limit-for-domain to set that, you might want to use different set‐
1861            tings  for  a  top-level-domain and subdomains.  A value of 0 will
1862            disable ratelimiting for domain names that end in this name.
1863
1864       ip-ratelimit: <number or 0>
1865            Enable global ratelimiting of queries accepted per IP address.  If
1866            0,  the  default,  it is disabled.  This option is experimental at
1867            this time.  The ratelimit is in queries per second  that  are  al‐
1868            lowed.  More queries are completely dropped and will not receive a
1869            reply, SERVFAIL or  otherwise.   IP  ratelimiting  happens  before
1870            looking in the cache. This may be useful for mitigating amplifica‐
1871            tion attacks.
1872
1873       ip-ratelimit-size: <memory size>
1874            Give the size of the data structure in which the  current  ongoing
1875            rates  are  kept  track in.  Default 4m.  In bytes or use m(mega),
1876            k(kilo), g(giga).  The ip ratelimit structure is  small,  so  this
1877            data structure likely does not need to be large.
1878
1879       ip-ratelimit-slabs: <number>
1880            Give  power of 2 number of slabs, this is used to reduce lock con‐
1881            tention in the ip ratelimit tracking data structure.  Close to the
1882            number of cpus is a fairly good setting.
1883
1884       ip-ratelimit-factor: <number>
1885            Set  the  amount  of  queries  to rate limit when the limit is ex‐
1886            ceeded.  If set to 0, all queries are dropped for addresses  where
1887            the  limit is exceeded.  If set to another value, 1 in that number
1888            is allowed through to complete.   Default  is  10,  allowing  1/10
1889            traffic to flow normally.  This can make ordinary queries complete
1890            (if repeatedly queried for), and enter the cache, whilst also mit‐
1891            igating the traffic flow by the factor given.
1892
1893       ip-ratelimit-backoff: <yes or no>
1894            If  enabled, the ratelimit is treated as a hard failure instead of
1895            the default maximum allowed constant  rate.   When  the  limit  is
1896            reached,  traffic  is  ratelimited and demand continues to be kept
1897            track of for a 2 second rate window.  No traffic is  allowed,  ex‐
1898            cept  for  ip-ratelimit-factor,  until  demand decreases below the
1899            configured ratelimit for a 2 second rate window.   Useful  to  set
1900            ip-ratelimit  to a suspicious rate to aggressively limit unusually
1901            high traffic.  Default is off.
1902
1903       outbound-msg-retry: <number>
1904            The number of retries, per upstream nameserver  in  a  delegation,
1905            that  Unbound  will  attempt  in  case a throwaway response is re‐
1906            ceived.  No response (timeout) contributes to the  retry  counter.
1907            If  a forward/stub zone is used, this is the number of retries per
1908            nameserver in the zone.  Default is 5.
1909
1910       max-sent-count: <number>
1911            Hard limit on the number of outgoing  queries  Unbound  will  make
1912            while  resolving  a  name,  making sure large NS sets do not loop.
1913            Results in SERVFAIL when reached.  It  resets  on  query  restarts
1914            (e.g., CNAME) and referrals.  Default is 32.
1915
1916       max-query-restarts: <number>
1917            Hard  limit on the number of times Unbound is allowed to restart a
1918            query upon encountering a CNAME record.  Results in SERVFAIL  when
1919            reached.   Changing  this value needs caution as it can allow long
1920            CNAME chains to be accepted, where Unbound needs  to  verify  (re‐
1921            solve) each link individually.  Default is 11.
1922
1923       fast-server-permil: <number>
1924            Specify how many times out of 1000 to pick from the set of fastest
1925            servers.  0 turns the feature off.  A value of 900 would pick from
1926            the fastest servers 90 percent of the time, and would perform nor‐
1927            mal exploration of random servers for  the  remaining  time.  When
1928            prefetch  is  enabled  (or serve-expired), such prefetches are not
1929            sped up, because there is no one waiting for it, and it presents a
1930            good moment to perform server exploration. The fast-server-num op‐
1931            tion can be used to specify the size of the fastest  servers  set.
1932            The default for fast-server-permil is 0.
1933
1934       fast-server-num: <number>
1935            Set  the number of servers that should be used for fast server se‐
1936            lection. Only use the fastest specified number of servers with the
1937            fast-server-permil  option, that turns this on or off. The default
1938            is to use the fastest 3 servers.
1939
1940       edns-client-string: <IP netblock> <string>
1941            Include an EDNS0 option  containing  configured  ascii  string  in
1942            queries  with  destination address matching the configured IP net‐
1943            block.  This configuration option can be used multiple times.  The
1944            most specific match will be used.
1945
1946       edns-client-string-opcode: <opcode>
1947            EDNS0  option  code  for  the edns-client-string option, from 0 to
1948            65535.  A value from the `Reserved for  Local/Experimental`  range
1949            (65001-65534) should be used.  Default is 65001.
1950
1951       ede: <yes or no>
1952            If  enabled,  Unbound  will  respond with Extended DNS Error codes
1953            (RFC8914).  These EDEs attach informative error messages to a  re‐
1954            sponse for various errors. Default is "no".
1955
1956            When the val-log-level option is also set to 2, responses with Ex‐
1957            tended DNS Errors concerning DNSSEC failures that are  not  served
1958            from cache, will also contain a descriptive text message about the
1959            reason for the failure.
1960
1961       ede-serve-expired: <yes or no>
1962            If enabled, Unbound will attach an Extended  DNS  Error  (RFC8914)
1963            Code  3  -  Stale  Answer as EDNS0 option to the expired response.
1964            Note that this will not attach the EDE code  without  setting  the
1965            global ede option to "yes" as well.  Default is "no".
1966
1967   Remote Control Options
1968       In  the remote-control: clause are the declarations for the remote con‐
1969       trol facility.  If this is enabled, the unbound-control(8) utility  can
1970       be  used  to  send  commands to the running Unbound server.  The server
1971       uses these clauses to setup TLSv1 security for the connection.  The un‐
1972       bound-control(8)  utility also reads the remote-control section for op‐
1973       tions.  To setup the  correct  self-signed  certificates  use  the  un‐
1974       bound-control-setup(8) utility.
1975
1976       control-enable: <yes or no>
1977            The  option is used to enable remote control, default is "no".  If
1978            turned off, the server does not listen for control commands.
1979
1980       control-interface: <ip address or interface name or path>
1981            Give IPv4 or IPv6 addresses or local socket path to listen on  for
1982            control  commands.   If an interface name is used instead of an ip
1983            address, the list of ip addresses on that interface are used.   By
1984            default localhost (127.0.0.1 and ::1) is listened to.  Use 0.0.0.0
1985            and ::0 to listen to all interfaces.  If you change this and  per‐
1986            missions  have  been  dropped, you must restart the server for the
1987            change to take effect.
1988
1989            If you set it to an absolute path, a unix domain socket  is  used.
1990            This socket does not use the certificates and keys, so those files
1991            need not be present.  To restrict access, Unbound sets permissions
1992            on  the  file to the user and group that is configured, the access
1993            bits are set to allow the group  members  to  access  the  control
1994            socket file.  Put users that need to access the socket in the that
1995            group.  To restrict access further, create a directory to put  the
1996            control socket in and restrict access to that directory.
1997
1998       control-port: <port number>
1999            The  port number to listen on for IPv4 or IPv6 control interfaces,
2000            default is 8953.  If you change this  and  permissions  have  been
2001            dropped,  you  must  restart the server for the change to take ef‐
2002            fect.
2003
2004       control-use-cert: <yes or no>
2005            For localhost control-interface you can disable the use of TLS  by
2006            setting this option to "no", default is "yes".  For local sockets,
2007            TLS is disabled and the value of this option is ignored.
2008
2009       server-key-file: <private key file>
2010            Path to the server private  key,  by  default  unbound_server.key.
2011            This file is generated by the unbound-control-setup utility.  This
2012            file is used by the Unbound server, but not by unbound-control.
2013
2014       server-cert-file: <certificate file.pem>
2015            Path to  the  server  self  signed  certificate,  by  default  un‐
2016            bound_server.pem.   This  file  is  generated  by the unbound-con‐
2017            trol-setup utility.  This file is used by the Unbound server,  and
2018            also by unbound-control.
2019
2020       control-key-file: <private key file>
2021            Path  to  the  control client private key, by default unbound_con‐
2022            trol.key.  This file is  generated  by  the  unbound-control-setup
2023            utility.  This file is used by unbound-control.
2024
2025       control-cert-file: <certificate file.pem>
2026            Path  to  the  control client certificate, by default unbound_con‐
2027            trol.pem.  This certificate has to be signed with the server  cer‐
2028            tificate.   This  file  is  generated by the unbound-control-setup
2029            utility.  This file is used by unbound-control.
2030
2031   Stub Zone Options
2032       There may be multiple stub-zone: clauses. Each with a name: and zero or
2033       more  hostnames  or IP addresses.  For the stub zone this list of name‐
2034       servers is used. Class IN is assumed.  The servers should be  authority
2035       servers,  not  recursors; Unbound performs the recursive processing it‐
2036       self for stub zones.
2037
2038       The stub zone can be used to configure authoritative data to be used by
2039       the resolver that cannot be accessed using the public internet servers.
2040       This is useful for company-local data or private zones.  Setup  an  au‐
2041       thoritative  server  on  a  different host (or different port). Enter a
2042       config entry for Unbound with stub-addr: <ip address  of  host[@port]>.
2043       The Unbound resolver can then access the data, without referring to the
2044       public internet for it.
2045
2046       This setup allows DNSSEC signed zones to be served by  that  authorita‐
2047       tive  server, in which case a trusted key entry with the public key can
2048       be put in config, so that Unbound can validate the data and set the  AD
2049       bit  on  replies for the private zone (authoritative servers do not set
2050       the AD bit).  This setup makes Unbound capable of answering queries for
2051       the private zone, and can even set the AD bit ('authentic'), but the AA
2052       ('authoritative') bit is not set on these replies.
2053
2054       Consider adding server: statements for  domain-insecure:  and  for  lo‐
2055       cal-zone:  name  nodefault for the zone if it is a locally served zone.
2056       The insecure clause stops DNSSEC from invalidating the zone.  The local
2057       zone nodefault (or transparent) clause makes the (reverse-) zone bypass
2058       Unbound's filtering of RFC1918 zones.
2059
2060       name: <domain name>
2061              Name of the stub zone. This is the full domain name of the zone.
2062
2063       stub-host: <domain name>
2064              Name of stub zone nameserver. Is itself resolved  before  it  is
2065              used.  To use a nondefault port for DNS communication append '@'
2066              with the port number.  If tls is enabled, then you can append  a
2067              '#' and a name, then it'll check the tls authentication certifi‐
2068              cates with that name.  If you combine the '@' and '#',  the  '@'
2069              comes  first.   If only '#' is used the default port is the con‐
2070              figured tls-port.
2071
2072       stub-addr: <IP address>
2073              IP address of stub zone nameserver. Can be IP 4 or IP 6.  To use
2074              a nondefault port for DNS communication append '@' with the port
2075              number.  If tls is enabled, then you can  append  a  '#'  and  a
2076              name,  then it'll check the tls authentication certificates with
2077              that name.  If you combine the '@' and '#', the '@' comes first.
2078              If only '#' is used the default port is the configured tls-port.
2079
2080       stub-prime: <yes or no>
2081              This  option  is  by  default no.  If enabled it performs NS set
2082              priming, which is similar to root hints, where it  starts  using
2083              the  list of nameservers currently published by the zone.  Thus,
2084              if the hint list is slightly outdated, the resolver picks  up  a
2085              correct list online.
2086
2087       stub-first: <yes or no>
2088              If  enabled,  a query is attempted without the stub clause if it
2089              fails.  The data could not be retrieved and  would  have  caused
2090              SERVFAIL  because  the  servers  are  unreachable, instead it is
2091              tried without this clause.  The default is no.
2092
2093       stub-tls-upstream: <yes or no>
2094              Enabled or disable whether the queries to this stub use TLS  for
2095              transport.  Default is no.
2096
2097       stub-ssl-upstream: <yes or no>
2098              Alternate syntax for stub-tls-upstream.
2099
2100       stub-tcp-upstream: <yes or no>
2101              If  it  is  set  to "yes" then upstream queries use TCP only for
2102              transport regardless of global flag  tcp-upstream.   Default  is
2103              no.
2104
2105       stub-no-cache: <yes or no>
2106              Default  is no.  If enabled, data inside the stub is not cached.
2107              This is useful when you want immediate changes to be visible.
2108
2109   Forward Zone Options
2110       There may be multiple forward-zone: clauses. Each with a name: and zero
2111       or  more  hostnames or IP addresses.  For the forward zone this list of
2112       nameservers is used to forward the queries to. The  servers  listed  as
2113       forward-host:  and  forward-addr:  have to handle further recursion for
2114       the query.  Thus, those servers are  not  authority  servers,  but  are
2115       (just  like Unbound is) recursive servers too; Unbound does not perform
2116       recursion itself for the forward zone, it lets the remote server do it.
2117       Class  IN  is assumed.  CNAMEs are chased by Unbound itself, asking the
2118       remote server for every name in the indirection chain, to  protect  the
2119       local cache from illegal indirect referenced items.  A forward-zone en‐
2120       try with name "." and a forward-addr target will forward all queries to
2121       that other server (unless it can answer from the cache).
2122
2123       name: <domain name>
2124              Name  of  the  forward zone. This is the full domain name of the
2125              zone.
2126
2127       forward-host: <domain name>
2128              Name of server to forward to. Is itself resolved  before  it  is
2129              used.  To use a nondefault port for DNS communication append '@'
2130              with the port number.  If tls is enabled, then you can append  a
2131              '#' and a name, then it'll check the tls authentication certifi‐
2132              cates with that name.  If you combine the '@' and '#',  the  '@'
2133              comes  first.   If only '#' is used the default port is the con‐
2134              figured tls-port.
2135
2136       forward-addr: <IP address>
2137              IP address of server to forward to. Can be IP 4 or IP 6.  To use
2138              a nondefault port for DNS communication append '@' with the port
2139              number.  If tls is enabled, then you can  append  a  '#'  and  a
2140              name,  then it'll check the tls authentication certificates with
2141              that name.  If you combine the '@' and '#', the '@' comes first.
2142              If only '#' is used the default port is the configured tls-port.
2143
2144              At high verbosity it logs the TLS certificate, with TLS enabled.
2145              If you leave out the '#' and auth name  from  the  forward-addr,
2146              any  name  is  accepted.  The cert must also match a CA from the
2147              tls-cert-bundle.
2148
2149       forward-first: <yes or no>
2150              If a forwarded query is met with a SERVFAIL error, and this  op‐
2151              tion is enabled, Unbound will fall back to normal recursive res‐
2152              olution for this query as if no query forwarding had been speci‐
2153              fied.  The default is "no".
2154
2155       forward-tls-upstream: <yes or no>
2156              Enabled or disable whether the queries to this forwarder use TLS
2157              for transport.  Default is no.  If you enable this, also config‐
2158              ure a tls-cert-bundle or use tls-win-cert to load CA certs, oth‐
2159              erwise the connections cannot be authenticated.
2160
2161       forward-ssl-upstream: <yes or no>
2162              Alternate syntax for forward-tls-upstream.
2163
2164       forward-tcp-upstream: <yes or no>
2165              If it is set to "yes" then upstream queries  use  TCP  only  for
2166              transport  regardless  of  global flag tcp-upstream.  Default is
2167              no.
2168
2169       forward-no-cache: <yes or no>
2170              Default is no.  If enabled,  data  inside  the  forward  is  not
2171              cached.   This  is  useful when you want immediate changes to be
2172              visible.
2173
2174   Authority Zone Options
2175       Authority zones are configured with auth-zone:, and each one must  have
2176       a  name:.   There  can  be multiple ones, by listing multiple auth-zone
2177       clauses, each with a different name, pertaining to  that  part  of  the
2178       namespace.  The authority zone with the name closest to the name looked
2179       up is used.  Authority zones are processed after local-zones and before
2180       cache  (for-downstream: yes), and when used in this manner make Unbound
2181       respond like an authority server.  Authority zones are  also  processed
2182       after  cache, just before going to the network to fetch information for
2183       recursion (for-upstream: yes), and when used in this manner  provide  a
2184       local copy of an authority server that speeds up lookups of that data.
2185
2186       Authority zones can be read from zonefile.  And can be kept updated via
2187       AXFR and IXFR.  After update the zonefile  is  rewritten.   The  update
2188       mechanism uses the SOA timer values and performs SOA UDP queries to de‐
2189       tect zone changes.
2190
2191       If the update fetch fails, the timers in the SOA  record  are  used  to
2192       time  another  fetch  attempt.   Until the SOA expiry timer is reached.
2193       Then the zone is expired.  When a zone is expired,  queries  are  SERV‐
2194       FAIL,  and  any new serial number is accepted from the primary (even if
2195       older), and if fallback is enabled, the  fallback  activates  to  fetch
2196       from the upstream instead of the SERVFAIL.
2197
2198       name: <zone name>
2199              Name of the authority zone.
2200
2201       primary: <IP address or host name>
2202              Where  to  download a copy of the zone from, with AXFR and IXFR.
2203              Multiple primaries can be specified.  They are all tried if  one
2204              fails.   To  use  a nondefault port for DNS communication append
2205              '@' with the port number.  You can append a '#' and a name, then
2206              AXFR  over  TLS  can be used and the tls authentication certifi‐
2207              cates will be checked with that name.  If you  combine  the  '@'
2208              and  '#',  the  '@' comes first.  If you point it at another Un‐
2209              bound instance, it would not work because that does not  support
2210              AXFR/IXFR  for  the  zone,  but if you used url: to download the
2211              zonefile as a text file from a webserver that  would  work.   If
2212              you  specify  the  hostname,  you cannot use the domain from the
2213              zonefile, because it may not  have  that  when  retrieving  that
2214              data,  instead use a plain IP address to avoid a circular depen‐
2215              dency on retrieving that IP address.
2216
2217       master: <IP address or host name>
2218              Alternate syntax for primary.
2219
2220       url: <url to zonefile>
2221              Where to download a zonefile for the zone.  With http or  https.
2222              An   example   for   the  url  is  "http://www.example.com/exam
2223              ple.org.zone".  Multiple url statements can be given,  they  are
2224              tried  in turn.  If only urls are given the SOA refresh timer is
2225              used to wait for making new downloads.  If  also  primaries  are
2226              listed,  the  primaries are first probed with UDP SOA queries to
2227              see if the SOA serial number has changed, reducing the number of
2228              downloads.   If  none  of the urls work, the primaries are tried
2229              with IXFR and AXFR.  For  https,  the  tls-cert-bundle  and  the
2230              hostname  from  the url are used to authenticate the connection.
2231              If you specify a hostname in the URL, you cannot use the  domain
2232              from  the zonefile, because it may not have that when retrieving
2233              that data, instead use a plain IP address to  avoid  a  circular
2234              dependency on retrieving that IP address.  Avoid dependencies on
2235              name lookups by using a notation like "http://192.0.2.1/unbound-
2236              primaries/example.com.zone", with an explicit IP address.
2237
2238       allow-notify: <IP address or host name or netblockIP/prefix>
2239              With  allow-notify  you  can specify additional sources of noti‐
2240              fies.  When notified, the server attempts  to  first  probe  and
2241              then  zone  transfer.  If the notify is from a primary, it first
2242              attempts that primary.  Otherwise other primaries are attempted.
2243              If there are no primaries, but only urls, the file is downloaded
2244              when notified.  The primaries from primary: and url:  statements
2245              are allowed notify by default.
2246
2247       fallback-enabled: <yes or no>
2248              Default  no.  If enabled, Unbound falls back to querying the in‐
2249              ternet as a resolver for this zone when lookups fail.  For exam‐
2250              ple for DNSSEC validation failures.
2251
2252       for-downstream: <yes or no>
2253              Default  yes.  If enabled, Unbound serves authority responses to
2254              downstream clients for this zone.  This option makes Unbound be‐
2255              have,  for  the queries with names in this zone, like one of the
2256              authority servers for that zone.  Turn it off if  you  want  Un‐
2257              bound to provide recursion for the zone but have a local copy of
2258              zone data.  If for-downstream is no  and  for-upstream  is  yes,
2259              then  Unbound  will DNSSEC validate the contents of the zone be‐
2260              fore serving the zone contents to clients and  store  validation
2261              results in the cache.
2262
2263       for-upstream: <yes or no>
2264              Default  yes.   If  enabled, Unbound fetches data from this data
2265              collection for answering recursion queries.  Instead of  sending
2266              queries  over  the  internet  to  the authority servers for this
2267              zone, it'll fetch the data directly from the zone data.  Turn it
2268              on  when  you  want  Unbound to provide recursion for downstream
2269              clients, and use the zone data as  a  local  copy  to  speed  up
2270              lookups.
2271
2272       zonemd-check: <yes or no>
2273              Enable  this option to check ZONEMD records in the zone. Default
2274              is disabled.  The ZONEMD record is  a  checksum  over  the  zone
2275              data.  This  includes  glue  in  the zone and data from the zone
2276              file, and excludes comments from the zone file.  When there is a
2277              DNSSEC chain of trust, DNSSEC signatures are checked too.
2278
2279       zonemd-reject-absence: <yes or no>
2280              Enable  this  option to reject the absence of the ZONEMD record.
2281              Without it, when zonemd is not there it is not checked.   It  is
2282              useful  to enable for a nonDNSSEC signed zone where the operator
2283              wants to require the verification of a ZONEMD, hence  a  missing
2284              ZONEMD  is  a failure.  The action upon failure is controlled by
2285              the zonemd-permissive-mode option, for log only  or  also  block
2286              the zone.  The default is no.
2287
2288              Without  the  option  absence of a ZONEMD is only a failure when
2289              the zone is DNSSEC signed, and we have a trust anchor,  and  the
2290              DNSSEC  verification  of  the absence of the ZONEMD fails.  With
2291              the option enabled, the absence of a ZONEMD is always a failure,
2292              also for nonDNSSEC signed zones.
2293
2294       zonefile: <filename>
2295              The  filename  where  the  zone is stored.  If not given then no
2296              zonefile is used.  If the file does not exist or is  empty,  Un‐
2297              bound  will  attempt  to  fetch  zone data (eg. from the primary
2298              servers).
2299
2300   View Options
2301       There may be multiple view: clauses. Each with a name: and zero or more
2302       local-zone  and local-data elements. Views can also contain view-first,
2303       response-ip, response-ip-data and local-data-ptr elements.  View can be
2304       mapped  to  requests  by  specifying  the  view  name in an access-con‐
2305       trol-view element. Options from matching views will override global op‐
2306       tions.  Global  options  will  be used if no matching view is found, or
2307       when the matching view does not have the option specified.
2308
2309       name: <view name>
2310              Name of the view. Must be unique.  This  name  is  used  in  ac‐
2311              cess-control-view elements.
2312
2313       local-zone: <zone> <type>
2314              View specific local-zone elements. Has the same types and behav‐
2315              iour as the global local-zone elements. When there is  at  least
2316              one  local-zone  specified and view-first is no, the default lo‐
2317              cal-zones will be added to this view.  Defaults can be  disabled
2318              using  the nodefault type. When view-first is yes or when a view
2319              does not have a local-zone, the global local-zone will  be  used
2320              including it's default zones.
2321
2322       local-data: "<resource record string>"
2323              View specific local-data elements. Has the same behaviour as the
2324              global local-data elements.
2325
2326       local-data-ptr: "IPaddr name"
2327              View specific local-data-ptr elements. Has the same behaviour as
2328              the global local-data-ptr elements.
2329
2330       view-first: <yes or no>
2331              If  enabled,  it  attempts  to use the global local-zone and lo‐
2332              cal-data if there is no match in the view specific options.  The
2333              default is no.
2334
2335   Python Module Options
2336       The  python: clause gives the settings for the python(1) script module.
2337       This module acts like the iterator and validator modules do, on queries
2338       and  answers.   To  enable the script module it has to be compiled into
2339       the daemon, and the word "python" has to be put in  the  module-config:
2340       option (usually first, or between the validator and iterator). Multiple
2341       instances of the  python  module  are  supported  by  adding  the  word
2342       "python" more than once.
2343
2344       If the chroot: option is enabled, you should make sure Python's library
2345       directory structure is bind mounted in the new  root  environment,  see
2346       mount(8).  Also the python-script: path should be specified as an abso‐
2347       lute path relative to the new root, or as a relative path to the  work‐
2348       ing directory.
2349
2350       python-script: <python file>
2351              The  script  file  to  load. Repeat this option for every python
2352              module instance added to the module-config: option.
2353
2354   Dynamic Library Module Options
2355       The dynlib: clause gives the settings for the dynlib module.  This mod‐
2356       ule  is  only  a  very  small wrapper that allows dynamic modules to be
2357       loaded on runtime instead of being compiled into  the  application.  To
2358       enable the dynlib module it has to be compiled into the daemon, and the
2359       word "dynlib" has to be put in the module-config: option. Multiple  in‐
2360       stances  of dynamic libraries are supported by adding the word "dynlib"
2361       more than once.
2362
2363       The dynlib-file: path should be specified as an absolute path  relative
2364       to  the  new  path  set by chroot: option, or as a relative path to the
2365       working directory.
2366
2367       dynlib-file: <dynlib file>
2368              The dynamic library file to load. Repeat this option  for  every
2369              dynlib module instance added to the module-config: option.
2370
2371   DNS64 Module Options
2372       The  dns64  module must be configured in the module-config: "dns64 val‐
2373       idator iterator" directive and be compiled into the daemon  to  be  en‐
2374       abled.  These settings go in the server: section.
2375
2376       dns64-prefix: <IPv6 prefix>
2377              This  sets  the  DNS64  prefix to use to synthesize AAAA records
2378              with.  It must  be  /96  or  shorter.   The  default  prefix  is
2379              64:ff9b::/96.
2380
2381       dns64-synthall: <yes or no>
2382              Debug  option,  default  no.   If  enabled,  synthesize all AAAA
2383              records despite the presence of actual AAAA records.
2384
2385       dns64-ignore-aaaa: <name>
2386              List domain for which the AAAA records are  ignored  and  the  A
2387              record is used by dns64 processing instead.  Can be entered mul‐
2388              tiple times, list a new domain for which  it  applies,  one  per
2389              line.  Applies also to names underneath the name given.
2390
2391   DNSCrypt Options
2392       The  dnscrypt: clause gives the settings of the dnscrypt channel. While
2393       those options are available, they are only meaningful  if  Unbound  was
2394       compiled with --enable-dnscrypt.  Currently certificate and secret/pub‐
2395       lic keys cannot be generated by Unbound.  You can use  dnscrypt-wrapper
2396       to  generate those: https://github.com/cofyc/dnscrypt-wrapper/blob/mas
2397       ter/README.md#usage
2398
2399       dnscrypt-enable: <yes or no>
2400              Whether or not the dnscrypt config should be  enabled.  You  may
2401              define configuration but not activate it.  The default is no.
2402
2403       dnscrypt-port: <port number>
2404              On which port should dnscrypt should be activated. Note that you
2405              should have a matching interface option defined  in  the  server
2406              section for this port.
2407
2408       dnscrypt-provider: <provider name>
2409              The  provider name to use to distribute certificates. This is of
2410              the form: 2.dnscrypt-cert.example.com.. The name MUST end with a
2411              dot.
2412
2413       dnscrypt-secret-key: <path to secret key file>
2414              Path  to  the  time  limited secret key file. This option may be
2415              specified multiple times.
2416
2417       dnscrypt-provider-cert: <path to cert file>
2418              Path to the certificate  related  to  the  dnscrypt-secret-keys.
2419              This option may be specified multiple times.
2420
2421       dnscrypt-provider-cert-rotated: <path to cert file>
2422              Path  to  a certificate that we should be able to serve existing
2423              connection  from   but   do   not   want   to   advertise   over
2424              dnscrypt-provider's  TXT  record  certs distribution.  A typical
2425              use case is when rotating  certificates,  existing  clients  may
2426              still  use  the  client magic from the old cert in their queries
2427              until they fetch and update the new cert. Likewise, it would al‐
2428              low  one  to prime the new cert/key without distributing the new
2429              cert yet, this can be useful when using a network of servers us‐
2430              ing  anycast  and on which the configuration may not get updated
2431              at the exact same time. By priming the  cert,  the  servers  can
2432              handle  both  old  and new certs traffic while distributing only
2433              one.  This option may be specified multiple times.
2434
2435       dnscrypt-shared-secret-cache-size: <memory size>
2436              Give the size of the data structure in which the  shared  secret
2437              keys  are  kept  in.   Default  4m.   In  bytes  or use m(mega),
2438              k(kilo), g(giga).  The shared secret cache is used when  a  same
2439              client  is making multiple queries using the same public key. It
2440              saves a substantial amount of CPU.
2441
2442       dnscrypt-shared-secret-cache-slabs: <number>
2443              Give power of 2 number of slabs, this is  used  to  reduce  lock
2444              contention  in  the dnscrypt shared secrets cache.  Close to the
2445              number of cpus is a fairly good setting.
2446
2447       dnscrypt-nonce-cache-size: <memory size>
2448              Give the size of the data structure in which the  client  nonces
2449              are  kept  in.   Default  4m.  In bytes or use m(mega), k(kilo),
2450              g(giga).  The nonce cache is used to  prevent  dnscrypt  message
2451              replaying.  Client nonce should be unique for any pair of client
2452              pk/server sk.
2453
2454       dnscrypt-nonce-cache-slabs: <number>
2455              Give power of 2 number of slabs, this is  used  to  reduce  lock
2456              contention  in the dnscrypt nonce cache.  Close to the number of
2457              cpus is a fairly good setting.
2458
2459   EDNS Client Subnet Module Options
2460       The ECS module must be configured in  the  module-config:  "subnetcache
2461       validator iterator" directive and be compiled into the daemon to be en‐
2462       abled.  These settings go in the server: section.
2463
2464       If the destination address is allowed in the configuration Unbound will
2465       add  the  EDNS0 option to the query containing the relevant part of the
2466       client's address.  When an answer contains the ECS option the  response
2467       and  the option are placed in a specialized cache. If the authority in‐
2468       dicated no support, the response is stored in the regular cache.
2469
2470       Additionally, when a client includes the option in its queries, Unbound
2471       will  forward  the  option when sending the query to addresses that are
2472       explicitly allowed in the configuration using  send-client-subnet.  The
2473       option  will  always be forwarded, regardless the allowed addresses, if
2474       client-subnet-always-forward is set to yes. In this case the lookup  in
2475       the regular cache is skipped.
2476
2477       The  maximum size of the ECS cache is controlled by 'msg-cache-size' in
2478       the configuration file. On top of that, for each query only 100 differ‐
2479       ent subnets are allowed to be stored for each address family. Exceeding
2480       that number, older entries will be purged from cache.
2481
2482       This module does not interact with the serve-expired* and prefetch: op‐
2483       tions.
2484
2485       send-client-subnet: <IP address>
2486              Send client source address to this authority. Append /num to in‐
2487              dicate  a  classless  delegation  netblock,  for  example   like
2488              10.2.3.4/24 or 2001::11/64. Can be given multiple times. Author‐
2489              ities not listed will not receive edns-subnet  information,  un‐
2490              less domain in query is specified in client-subnet-zone.
2491
2492       client-subnet-zone: <domain>
2493              Send  client  source  address in queries for this domain and its
2494              subdomains. Can be given multiple times. Zones not  listed  will
2495              not  receive edns-subnet information, unless hosted by authority
2496              specified in send-client-subnet.
2497
2498       client-subnet-always-forward: <yes or no>
2499              Specify  whether  the  ECS  address  check   (configured   using
2500              send-client-subnet)  is  applied  for  all  queries, even if the
2501              triggering query contains an ECS record, or only for queries for
2502              which the ECS record is generated using the querier address (and
2503              therefore did not contain ECS data in the client query). If  en‐
2504              abled,  the  address check is skipped when the client query con‐
2505              tains an ECS record. And the lookup  in  the  regular  cache  is
2506              skipped.  Default is no.
2507
2508       max-client-subnet-ipv6: <number>
2509              Specifies the maximum prefix length of the client source address
2510              we are willing to expose to third parties for IPv6.  Defaults to
2511              56.
2512
2513       max-client-subnet-ipv4: <number>
2514              Specifies the maximum prefix length of the client source address
2515              we are willing to expose to third parties for IPv4. Defaults  to
2516              24.
2517
2518       min-client-subnet-ipv6: <number>
2519              Specifies  the  minimum prefix length of the IPv6 source mask we
2520              are willing to accept in queries. Shorter source masks result in
2521              REFUSED answers. Source mask of 0 is always accepted. Default is
2522              0.
2523
2524       min-client-subnet-ipv4: <number>
2525              Specifies the minimum prefix length of the IPv4 source  mask  we
2526              are willing to accept in queries. Shorter source masks result in
2527              REFUSED answers. Source mask of 0 is always accepted. Default is
2528              0.
2529
2530       max-ecs-tree-size-ipv4: <number>
2531              Specifies  the maximum number of subnets ECS answers kept in the
2532              ECS radix tree.  This number applies for each qname/qclass/qtype
2533              tuple. Defaults to 100.
2534
2535       max-ecs-tree-size-ipv6: <number>
2536              Specifies  the maximum number of subnets ECS answers kept in the
2537              ECS radix tree.  This number applies for each qname/qclass/qtype
2538              tuple. Defaults to 100.
2539
2540   Opportunistic IPsec Support Module Options
2541       The  IPsec  module  must  be configured in the module-config: "ipsecmod
2542       validator iterator" directive and be compiled  into  Unbound  by  using
2543       --enable-ipsecmod to be enabled.  These settings go in the server: sec‐
2544       tion.
2545
2546       When Unbound receives an A/AAAA query that is  not  in  the  cache  and
2547       finds a valid answer, it will withhold returning the answer and instead
2548       will generate an IPSECKEY subquery for the same domain name.  If an an‐
2549       swer  was found, Unbound will call an external hook passing the follow‐
2550       ing arguments:
2551
2552            QNAME
2553                 Domain name of the A/AAAA and IPSECKEY query.  In string for‐
2554                 mat.
2555
2556            IPSECKEY TTL
2557                 TTL of the IPSECKEY RRset.
2558
2559            A/AAAA
2560                 String  of space separated IP addresses present in the A/AAAA
2561                 RRset.  The IP addresses are in string format.
2562
2563            IPSECKEY
2564                 String of space  separated  IPSECKEY  RDATA  present  in  the
2565                 IPSECKEY  RRset.   The IPSECKEY RDATA are in DNS presentation
2566                 format.
2567
2568       The A/AAAA answer is then cached and returned to the  client.   If  the
2569       external  hook  was called the TTL changes to ensure it doesn't surpass
2570       ipsecmod-max-ttl.
2571
2572       The same procedure is also followed when prefetch:  is  used,  but  the
2573       A/AAAA answer is given to the client before the hook is called.  ipsec‐
2574       mod-max-ttl ensures that the A/AAAA answer given from  cache  is  still
2575       relevant for opportunistic IPsec.
2576
2577       ipsecmod-enabled: <yes or no>
2578              Specifies whether the IPsec module is enabled or not.  The IPsec
2579              module still needs to be defined in  the  module-config:  direc‐
2580              tive.  This option facilitates turning on/off the module without
2581              restarting/reloading Unbound.  Defaults to yes.
2582
2583       ipsecmod-hook: <filename>
2584              Specifies the external hook that Unbound  will  call  with  sys‐
2585              tem(3).  The file can be specified as an absolute/relative path.
2586              The file needs the proper permissions to be able to be  executed
2587              by the same user that runs Unbound.  It must be present when the
2588              IPsec module is defined in the module-config: directive.
2589
2590       ipsecmod-strict: <yes or no>
2591              If enabled Unbound requires the external hook to return  a  suc‐
2592              cess value of 0.  Failing to do so Unbound will reply with SERV‐
2593              FAIL.  The A/AAAA answer will also not be cached.   Defaults  to
2594              no.
2595
2596       ipsecmod-max-ttl: <seconds>
2597              Time to live maximum for A/AAAA cached records after calling the
2598              external hook.  Defaults to 3600.
2599
2600       ipsecmod-ignore-bogus: <yes or no>
2601              Specifies the behaviour of Unbound when the IPSECKEY  answer  is
2602              bogus.   If  set  to yes, the hook will be called and the A/AAAA
2603              answer will be returned to the client.  If set to no,  the  hook
2604              will  not  be  called and the answer to the A/AAAA query will be
2605              SERVFAIL.  Mainly used for testing.  Defaults to no.
2606
2607       ipsecmod-allow: <domain>
2608              Allow the ipsecmod functionality for the domain so that the mod‐
2609              ule  logic  will  be executed.  Can be given multiple times, for
2610              different domains.  If the option is not specified, all  domains
2611              are treated as being allowed (default).
2612
2613       ipsecmod-whitelist: <yes or no>
2614              Alternate syntax for ipsecmod-allow.
2615
2616   Cache DB Module Options
2617       The Cache DB module must be configured in the module-config: "validator
2618       cachedb iterator" directive and be compiled into the daemon with  --en‐
2619       able-cachedb.   If this module is enabled and configured, the specified
2620       backend database works as a second level  cache:  When  Unbound  cannot
2621       find  an answer to a query in its built-in in-memory cache, it consults
2622       the specified backend.  If it finds a valid answer in the backend,  Un‐
2623       bound  uses it to respond to the query without performing iterative DNS
2624       resolution.  If Unbound cannot even find an answer in the  backend,  it
2625       resolves the query as usual, and stores the answer in the backend.
2626
2627       This  module  interacts with the serve-expired-* options and will reply
2628       with expired data if Unbound is configured for that.  Currently the use
2629       of  serve-expired-client-timeout:  and  serve-expired-reply-ttl: is not
2630       consistent for data originating from the external cache as  these  will
2631       result  in  a reply with 0 TTL without trying to update the data first,
2632       ignoring the configured values.
2633
2634       If Unbound was built with --with-libhiredis on a system  that  has  in‐
2635       stalled the hiredis C client library of Redis, then the "redis" backend
2636       can be used.  This backend communicates with the specified Redis server
2637       over a TCP connection to store and retrieve cache data.  It can be used
2638       as a persistent and/or shared cache backend.  It should be  noted  that
2639       Unbound  never  removes  data  stored in the Redis server, even if some
2640       data have expired in terms of DNS TTL or the Redis  server  has  cached
2641       too  much  data;  if  necessary  the Redis server must be configured to
2642       limit the cache size, preferably with some kind of  least-recently-used
2643       eviction  policy.  Additionally, the redis-expire-records option can be
2644       used in order to set the relative DNS TTL of the message as timeout  to
2645       the Redis records; keep in mind that some additional memory is used per
2646       key and that the expire information is stored as  absolute  Unix  time‐
2647       stamps in Redis (computer time must be stable).  This backend uses syn‐
2648       chronous communication with the Redis server based  on  the  assumption
2649       that  the  communication  is  stable and sufficiently fast.  The thread
2650       waiting for a response from the Redis server cannot  handle  other  DNS
2651       queries.   Although  the  backend  has  the ability to reconnect to the
2652       server when the connection is closed unexpectedly and there is  a  con‐
2653       figurable  timeout in case the server is overly slow or hangs up, these
2654       cases are assumed to be very rare.  If connection close or timeout hap‐
2655       pens too often, Unbound will be effectively unusable with this backend.
2656       It's the administrator's responsibility to make the assumption hold.
2657
2658       The cachedb: clause gives custom settings of the cache DB module.
2659
2660       backend: <backend name>
2661              Specify the backend database name.  The default database is  the
2662              in-memory  backend  named  "testframe",  which, as the name sug‐
2663              gests, is not of any practical use.  Depending on the build-time
2664              configuration,  "redis"  backend  may  also be used as described
2665              above.
2666
2667       secret-seed: <"secret string">
2668              Specify a seed to calculate a hash value from query information.
2669              This  value  will be used as the key of the corresponding answer
2670              for the backend database and  can  be  customized  if  the  hash
2671              should  not  be predictable operationally.  If the backend data‐
2672              base is shared by multiple Unbound instances, all instances must
2673              use the same secret seed.  This option defaults to "default".
2674
2675       The following cachedb options are specific to the redis backend.
2676
2677       redis-server-host: <server address or name>
2678              The  IP  (either  v6  or v4) address or domain name of the Redis
2679              server.  In general an IP address should be specified as  other‐
2680              wise  Unbound  will have to resolve the name of the server every
2681              time it establishes a connection to the server.  This option de‐
2682              faults to "127.0.0.1".
2683
2684       redis-server-port: <port number>
2685              The  TCP  port number of the Redis server.  This option defaults
2686              to 6379.
2687
2688       redis-timeout: <msec>
2689              The period until when Unbound waits for a response from the  Re‐
2690              dis  sever.   If this timeout expires Unbound closes the connec‐
2691              tion, treats it as if the Redis server does  not  have  the  re‐
2692              quested  data,  and  will  try  to re-establish a new connection
2693              later.  This option defaults to 100 milliseconds.
2694
2695       redis-expire-records: <yes or no>
2696              If Redis record expiration is enabled.   If  yes,  Unbound  sets
2697              timeout for Redis records so that Redis can evict keys that have
2698              expired automatically.  If Unbound is configured with  serve-ex‐
2699              pired  and serve-expired-ttl is 0, this option is internally re‐
2700              verted to "no".  Redis SETEX support is required for this option
2701              (Redis >= 2.0.0).  This option defaults to no.
2702
2703   DNSTAP Logging Options
2704       DNSTAP  support,  when compiled in by using --enable-dnstap, is enabled
2705       in the dnstap: section.  This starts an  extra  thread  (when  compiled
2706       with threading) that writes the log information to the destination.  If
2707       Unbound is compiled without threading it does not spawn a  thread,  but
2708       connects per-process to the destination.
2709
2710       dnstap-enable: <yes or no>
2711              If  dnstap  is enabled.  Default no.  If yes, it connects to the
2712              dnstap server and if any of the  dnstap-log-..-messages  options
2713              is enabled it sends logs for those messages to the server.
2714
2715       dnstap-bidirectional: <yes or no>
2716              Use  frame streams in bidirectional mode to transfer DNSTAP mes‐
2717              sages. Default is yes.
2718
2719       dnstap-socket-path: <file name>
2720              Sets the unix socket file name for connecting to the server that
2721              is   listening   on   that   socket.    Default   is   "/etc/un‐
2722              bound/dnstap.sock".
2723
2724       dnstap-ip: <IPaddress[@port]>
2725              If "", the unix socket is used, if set with an IP address  (IPv4
2726              or IPv6) that address is used to connect to the server.
2727
2728       dnstap-tls: <yes or no>
2729              Set  this  to  use  TLS  to  connect  to the server specified in
2730              dnstap-ip.  The default is yes.  If set to no, TCP  is  used  to
2731              connect to the server.
2732
2733       dnstap-tls-server-name: <name of TLS authentication>
2734              The  TLS server name to authenticate the server with.  Used when
2735              dnstap-tls is enabled.  If "" it is ignored, default "".
2736
2737       dnstap-tls-cert-bundle: <file name of cert bundle>
2738              The pem file with certs to verify the TLS server certificate. If
2739              ""  the  server default cert bundle is used, or the windows cert
2740              bundle on windows.  Default is "".
2741
2742       dnstap-tls-client-key-file: <file name>
2743              The client key file for TLS client authentication. If ""  client
2744              authentication is not used.  Default is "".
2745
2746       dnstap-tls-client-cert-file: <file name>
2747              The  client cert file for TLS client authentication.  Default is
2748              "".
2749
2750       dnstap-send-identity: <yes or no>
2751              If enabled, the server identity is included in the log messages.
2752              Default is no.
2753
2754       dnstap-send-version: <yes or no>
2755              If  enabled, the server version if included in the log messages.
2756              Default is no.
2757
2758       dnstap-identity: <string>
2759              The identity to send with messages, if "" the hostname is  used.
2760              Default is "".
2761
2762       dnstap-version: <string>
2763              The  version to send with messages, if "" the package version is
2764              used.  Default is "".
2765
2766       dnstap-log-resolver-query-messages: <yes or no>
2767              Enable to log resolver query messages.  Default  is  no.   These
2768              are messages from Unbound to upstream servers.
2769
2770       dnstap-log-resolver-response-messages: <yes or no>
2771              Enable to log resolver response messages.  Default is no.  These
2772              are replies from upstream servers to Unbound.
2773
2774       dnstap-log-client-query-messages: <yes or no>
2775              Enable to log client query messages.  Default is no.  These  are
2776              client queries to Unbound.
2777
2778       dnstap-log-client-response-messages: <yes or no>
2779              Enable  to  log client response messages.  Default is no.  These
2780              are responses from Unbound to clients.
2781
2782       dnstap-log-forwarder-query-messages: <yes or no>
2783              Enable to log forwarder query messages.  Default is no.
2784
2785       dnstap-log-forwarder-response-messages: <yes or no>
2786              Enable to log forwarder response messages.  Default is no.
2787
2788   Response Policy Zone Options
2789       Response Policy Zones are configured with rpz:, and each one must  have
2790       a  name:.  There can be multiple ones, by listing multiple rpz clauses,
2791       each with a different name. RPZ clauses are applied in order of config‐
2792       uration.  The  respip  module  needs  to be added to the module-config,
2793       e.g.: module-config: "respip validator iterator".
2794
2795       QNAME, Response IP Address, nsdname, nsip  and  clientip  triggers  are
2796       supported.   Supported  actions  are: NXDOMAIN, NODATA, PASSTHRU, DROP,
2797       Local Data, tcp-only and drop.  RPZ QNAME triggers  are  applied  after
2798       local-zones and before auth-zones.
2799
2800       The  rpz zone is formatted with a SOA start record as usual.  The items
2801       in the zone are entries, that specify what to act on (the trigger)  and
2802       what  to  do  (the  action).   The trigger to act on is recorded in the
2803       name, the action to do is recorded as the resource record.   The  names
2804       all end in the zone name, so you could type the trigger names without a
2805       trailing dot in the zonefile.
2806
2807       An example RPZ record, that answers example.com with NXDOMAIN
2808            example.com CNAME .
2809
2810       The triggers are encoded in the name on the left
2811            name                          query name
2812            netblock.rpz-client-ip        client IP address
2813            netblock.rpz-ip               response IP address in the answer
2814            name.rpz-nsdname              nameserver name
2815            netblock.rpz-nsip             nameserver IP address
2816       The netblock is written as <netblocklen>.<ip address in reverse>.   For
2817       IPv6 use 'zz' for '::'.  Specify individual addresses with scope length
2818       of 32 or 128.  For example, 24.10.100.51.198.rpz-ip is 198.51.100.10/24
2819       and 32.10.zz.db8.2001.rpz-ip is 2001:db8:0:0:0:0:0:10/32.
2820
2821       The actions are specified with the record on the right
2822            CNAME .                      nxdomain reply
2823            CNAME *.                     nodata reply
2824            CNAME rpz-passthru.          do nothing, allow to continue
2825            CNAME rpz-drop.              the query is dropped
2826            CNAME rpz-tcp-only.          answer over TCP
2827            A 192.0.2.1                  answer with this IP address
2828       Other  records like AAAA, TXT and other CNAMEs (not rpz-..) can also be
2829       used to answer queries with that content.
2830
2831       The RPZ zones can be configured in the config file with these  settings
2832       in the rpz: block.
2833
2834       name: <zone name>
2835              Name of the authority zone.
2836
2837       primary: <IP address or host name>
2838              Where  to  download a copy of the zone from, with AXFR and IXFR.
2839              Multiple primaries can be specified.  They are all tried if  one
2840              fails.   To  use  a nondefault port for DNS communication append
2841              '@' with the port number.  You can append a '#' and a name, then
2842              AXFR  over  TLS  can be used and the tls authentication certifi‐
2843              cates will be checked with that name.  If you  combine  the  '@'
2844              and  '#',  the  '@' comes first.  If you point it at another Un‐
2845              bound instance, it would not work because that does not  support
2846              AXFR/IXFR  for  the  zone,  but if you used url: to download the
2847              zonefile as a text file from a webserver that  would  work.   If
2848              you  specify  the  hostname,  you cannot use the domain from the
2849              zonefile, because it may not  have  that  when  retrieving  that
2850              data,  instead use a plain IP address to avoid a circular depen‐
2851              dency on retrieving that IP address.
2852
2853       master: <IP address or host name>
2854              Alternate syntax for primary.
2855
2856       url: <url to zonefile>
2857              Where to download a zonefile for the zone.  With http or  https.
2858              An   example   for   the  url  is  "http://www.example.com/exam
2859              ple.org.zone".  Multiple url statements can be given,  they  are
2860              tried  in turn.  If only urls are given the SOA refresh timer is
2861              used to wait for making new downloads.  If  also  primaries  are
2862              listed,  the  primaries are first probed with UDP SOA queries to
2863              see if the SOA serial number has changed, reducing the number of
2864              downloads.   If  none  of the urls work, the primaries are tried
2865              with IXFR and AXFR.  For  https,  the  tls-cert-bundle  and  the
2866              hostname from the url are used to authenticate the connection.
2867
2868       allow-notify: <IP address or host name or netblockIP/prefix>
2869              With  allow-notify  you  can specify additional sources of noti‐
2870              fies.  When notified, the server attempts  to  first  probe  and
2871              then  zone  transfer.  If the notify is from a primary, it first
2872              attempts that primary.  Otherwise other primaries are attempted.
2873              If there are no primaries, but only urls, the file is downloaded
2874              when notified.  The primaries from primary: and url:  statements
2875              are allowed notify by default.
2876
2877       zonefile: <filename>
2878              The  filename  where  the  zone is stored.  If not given then no
2879              zonefile is used.  If the file does not exist or is  empty,  Un‐
2880              bound  will  attempt  to  fetch  zone data (eg. from the primary
2881              servers).
2882
2883       rpz-action-override: <action>
2884              Always use this RPZ action for matching triggers from this zone.
2885              Possible  action are: nxdomain, nodata, passthru, drop, disabled
2886              and cname.
2887
2888       rpz-cname-override: <domain>
2889              The CNAME target domain to use if the cname action is configured
2890              for rpz-action-override.
2891
2892       rpz-log: <yes or no>
2893              Log all applied RPZ actions for this RPZ zone. Default is no.
2894
2895       rpz-log-name: <name>
2896              Specify  a string to be part of the log line, for easy referenc‐
2897              ing.
2898
2899       rpz-signal-nxdomain-ra: <yes or no>
2900              Signal when a query is blocked by the RPZ with NXDOMAIN with  an
2901              unset  RA  flag.   This allows certain clients, like dnsmasq, to
2902              infer that the domain is externally blocked. Default is no.
2903
2904       for-downstream: <yes or no>
2905              If enabled the zone is authoritatively answered for and  queries
2906              for the RPZ zone information are answered to downstream clients.
2907              This is useful for monitoring scripts, that can then access  the
2908              SOA  information  to check if the rpz information is up to date.
2909              Default is no.
2910
2911       tags: <list of tags>
2912              Limit the policies from this RPZ clause to clients with a match‐
2913              ing  tag.  Tags  need to be defined in define-tag and can be as‐
2914              signed to client  addresses  using  access-control-tag.  Enclose
2915              list  of  tags in quotes ("") and put spaces between tags. If no
2916              tags are specified the policies from this clause will be applied
2917              for all clients.
2918

MEMORY CONTROL EXAMPLE

2920       In the example config settings below memory usage is reduced. Some ser‐
2921       vice levels are lower, notable very large data and a high TCP load  are
2922       no longer supported. Very large data and high TCP loads are exceptional
2923       for the DNS.  DNSSEC validation is enabled, just add trust anchors.  If
2924       you do not have to worry about programs using more than 3 Mb of memory,
2925       the below example is not for you. Use the defaults to receive full ser‐
2926       vice, which on BSD-32bit tops out at 30-40 Mb after heavy usage.
2927
2928       # example settings that reduce memory usage
2929       server:
2930            num-threads: 1
2931            outgoing-num-tcp: 1 # this limits TCP service, uses less buffers.
2932            incoming-num-tcp: 1
2933            outgoing-range: 60  # uses less memory, but less performance.
2934            msg-buffer-size: 8192   # note this limits service, 'no huge stuff'.
2935            msg-cache-size: 100k
2936            msg-cache-slabs: 1
2937            rrset-cache-size: 100k
2938            rrset-cache-slabs: 1
2939            infra-cache-numhosts: 200
2940            infra-cache-slabs: 1
2941            key-cache-size: 100k
2942            key-cache-slabs: 1
2943            neg-cache-size: 10k
2944            num-queries-per-thread: 30
2945            target-fetch-policy: "2 1 0 0 0 0"
2946            harden-large-queries: "yes"
2947            harden-short-bufsize: "yes"
2948

FILES

2950       /etc/unbound
2951              default Unbound working directory.
2952
2953       /etc/unbound
2954              default chroot(2) location.
2955
2956       /etc/unbound/unbound.conf
2957              Unbound configuration file.
2958
2959       /run/unbound/unbound.pid
2960              default Unbound pidfile with process ID of the running daemon.
2961
2962       unbound.log
2963              Unbound log file. default is to log to syslog(3).
2964

SEE ALSO

2966       unbound(8), unbound-checkconf(8).
2967

AUTHORS

2969       Unbound  was written by NLnet Labs. Please see CREDITS file in the dis‐
2970       tribution for further details.
2971
2972
2973
2974NLnet Labs                       Jan 12, 2023                  unbound.conf(5)
Impressum