1unbound.conf(5) unbound 1.6.6 unbound.conf(5)
2
3
4
6 unbound.conf - Unbound configuration file.
7
9 unbound.conf
10
12 unbound.conf is used to configure unbound(8). The file format has
13 attributes and values. Some attributes have attributes inside them.
14 The notation is: attribute: value.
15
16 Comments start with # and last to the end of line. Empty lines are
17 ignored 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
23 An example config file is shown below. Copy this to
24 /etc/unbound/unbound.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
33 extensive 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/random /etc/unbound/dev/random
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
54 There must be whitespace between keywords. Attribute keywords end with
55 a colon ':'. An attribute is followed by its containing attributes, or
56 a value.
57
58 Files can be included using the include: directive. It can appear any‐
59 where, it accepts a single file name as argument. Processing continues
60 as if the text from the included file was copied into the config file
61 at that point. If also using chroot, using full path names for the
62 included files works, relative pathnames for the included names work if
63 the directory where the daemon is started equals its chroot/working
64 directory or is specified before the include statement with directory:
65 dir. Wildcards can be used to include multiple files, see glob(7).
66
67 Server Options
68 These options are part of the server: clause.
69
70 verbosity: <number>
71 The verbosity number, level 0 means no verbosity, only errors.
72 Level 1 gives operational information. Level 2 gives detailed
73 operational information. Level 3 gives query level information,
74 output per query. Level 4 gives algorithm level information.
75 Level 5 logs client identification for cache misses. Default is
76 level 1. The verbosity can also be increased from the command‐
77 line, see unbound(8).
78
79 statistics-interval: <seconds>
80 The number of seconds between printing statistics to the log for
81 every thread. Disable with value 0 or "". Default is disabled.
82 The histogram statistics are only printed if replies were sent
83 during the statistics interval, requestlist statistics are
84 printed for every interval (but can be 0). This is because the
85 median calculation requires data to be present.
86
87 statistics-cumulative: <yes or no>
88 If enabled, statistics are cumulative since starting unbound,
89 without clearing the statistics counters after logging the sta‐
90 tistics. Default is no.
91
92 extended-statistics: <yes or no>
93 If enabled, extended statistics are printed from unbound-con‐
94 trol(8). Default is off, because keeping track of more statis‐
95 tics takes time. The counters are listed in unbound-control(8).
96
97 num-threads: <number>
98 The number of threads to create to serve clients. Use 1 for no
99 threading.
100
101 port: <port number>
102 The port number, default 53, on which the server responds to
103 queries.
104
105 interface: <ip address[@port]>
106 Interface to use to connect to the network. This interface is
107 listened to for queries from clients, and answers to clients are
108 given from it. Can be given multiple times to work on several
109 interfaces. If none are given the default is to listen to local‐
110 host. The interfaces are not changed on a reload (kill -HUP)
111 but only on restart. A port number can be specified with @port
112 (without spaces between interface and port number), if not spec‐
113 ified the default port (from port) is used.
114
115 ip-address: <ip address[@port]>
116 Same as interface: (for easy of compatibility with nsd.conf).
117
118 interface-automatic: <yes or no>
119 Detect source interface on UDP queries and copy them to replies.
120 This feature is experimental, and needs support in your OS for
121 particular socket options. Default value is no.
122
123 outgoing-interface: <ip address or ip6 netblock>
124 Interface to use to connect to the network. This interface is
125 used to send queries to authoritative servers and receive their
126 replies. Can be given multiple times to work on several inter‐
127 faces. If none are given the default (all) is used. You can
128 specify the same interfaces in interface: and outgoing-inter‐
129 face: lines, the interfaces are then used for both purposes.
130 Outgoing queries are sent via a random outgoing interface to
131 counter spoofing.
132
133 If an IPv6 netblock is specified instead of an individual IPv6
134 address, outgoing UDP queries will use a randomised source
135 address taken from the netblock to counter spoofing. Requires
136 the IPv6 netblock to be routed to the host running unbound, and
137 requires OS support for unprivileged non-local binds (currently
138 only supported on Linux). Several netblocks may be specified
139 with multiple outgoing-interface: options, but do not specify
140 both an individual IPv6 address and an IPv6 netblock, or the
141 randomisation will be compromised. Consider combining with pre‐
142 fer-ip6: yes to increase the likelihood of IPv6 nameservers
143 being selected for queries. On Linux you need these two com‐
144 mands to be able to use the freebind socket option to receive
145 traffic for the ip6 netblock: ip -6 addr add mynetblock/64 dev
146 lo && ip -6 route add local mynetblock/64 dev lo
147
148 outgoing-range: <number>
149 Number of ports to open. This number of file descriptors can be
150 opened per thread. Must be at least 1. Default depends on com‐
151 pile options. Larger numbers need extra resources from the oper‐
152 ating system. For performance a very large value is best, use
153 libevent to make this possible.
154
155 outgoing-port-permit: <port number or range>
156 Permit unbound to open this port or range of ports for use to
157 send queries. A larger number of permitted outgoing ports
158 increases resilience against spoofing attempts. Make sure these
159 ports are not needed by other daemons. By default only ports
160 above 1024 that have not been assigned by IANA are used. Give a
161 port number or a range of the form "low-high", without spaces.
162
163 The outgoing-port-permit and outgoing-port-avoid statements are
164 processed in the line order of the config file, adding the per‐
165 mitted ports and subtracting the avoided ports from the set of
166 allowed ports. The processing starts with the non IANA allo‐
167 cated ports above 1024 in the set of allowed ports.
168
169 outgoing-port-avoid: <port number or range>
170 Do not permit unbound to open this port or range of ports for
171 use to send queries. Use this to make sure unbound does not grab
172 a port that another daemon needs. The port is avoided on all
173 outgoing interfaces, both IP4 and IP6. By default only ports
174 above 1024 that have not been assigned by IANA are used. Give a
175 port number or a range of the form "low-high", without spaces.
176
177 outgoing-num-tcp: <number>
178 Number of outgoing TCP buffers to allocate per thread. Default
179 is 10. If set to 0, or if do-tcp is "no", no TCP queries to
180 authoritative servers are done. For larger installations
181 increasing this value is a good idea.
182
183 incoming-num-tcp: <number>
184 Number of incoming TCP buffers to allocate per thread. Default
185 is 10. If set to 0, or if do-tcp is "no", no TCP queries from
186 clients are accepted. For larger installations increasing this
187 value is a good idea.
188
189 edns-buffer-size: <number>
190 Number of bytes size to advertise as the EDNS reassembly buffer
191 size. This is the value put into datagrams over UDP towards
192 peers. The actual buffer size is determined by msg-buffer-size
193 (both for TCP and UDP). Do not set higher than that value.
194 Default is 4096 which is RFC recommended. If you have fragmen‐
195 tation reassembly problems, usually seen as timeouts, then a
196 value of 1472 can fix it. Setting to 512 bypasses even the most
197 stringent path MTU problems, but is seen as extreme, since the
198 amount of TCP fallback generated is excessive (probably also for
199 this resolver, consider tuning the outgoing tcp number).
200
201 max-udp-size: <number>
202 Maximum UDP response size (not applied to TCP response). 65536
203 disables the udp response size maximum, and uses the choice from
204 the client, always. Suggested values are 512 to 4096. Default
205 is 4096.
206
207 msg-buffer-size: <number>
208 Number of bytes size of the message buffers. Default is 65552
209 bytes, enough for 64 Kb packets, the maximum DNS message size.
210 No message larger than this can be sent or received. Can be
211 reduced to use less memory, but some requests for DNS data, such
212 as for huge resource records, will result in a SERVFAIL reply to
213 the client.
214
215 msg-cache-size: <number>
216 Number of bytes size of the message cache. Default is 4
217 megabytes. A plain number is in bytes, append 'k', 'm' or 'g'
218 for kilobytes, megabytes or gigabytes (1024*1024 bytes in a
219 megabyte).
220
221 msg-cache-slabs: <number>
222 Number of slabs in the message cache. Slabs reduce lock con‐
223 tention by threads. Must be set to a power of 2. Setting
224 (close) to the number of cpus is a reasonable guess.
225
226 num-queries-per-thread: <number>
227 The number of queries that every thread will service simultane‐
228 ously. If more queries arrive that need servicing, and no
229 queries can be jostled out (see jostle-timeout), then the
230 queries are dropped. This forces the client to resend after a
231 timeout; allowing the server time to work on the existing
232 queries. Default depends on compile options, 512 or 1024.
233
234 jostle-timeout: <msec>
235 Timeout used when the server is very busy. Set to a value that
236 usually results in one roundtrip to the authority servers. If
237 too many queries arrive, then 50% of the queries are allowed to
238 run to completion, and the other 50% are replaced with the new
239 incoming query if they have already spent more than their
240 allowed time. This protects against denial of service by slow
241 queries or high query rates. Default 200 milliseconds. The
242 effect is that the qps for long-lasting queries is about (num‐
243 queriesperthread / 2) / (average time for such long queries)
244 qps. The qps for short queries can be about (numqueries‐
245 perthread / 2) / (jostletimeout in whole seconds) qps per
246 thread, about (1024/2)*5 = 2560 qps by default.
247
248 delay-close: <msec>
249 Extra delay for timeouted UDP ports before they are closed, in
250 msec. Default is 0, and that disables it. This prevents very
251 delayed answer packets from the upstream (recursive) servers
252 from bouncing against closed ports and setting off all sort of
253 close-port counters, with eg. 1500 msec. When timeouts happen
254 you need extra sockets, it checks the ID and remote IP of pack‐
255 ets, and unwanted packets are added to the unwanted packet
256 counter.
257
258 so-rcvbuf: <number>
259 If not 0, then set the SO_RCVBUF socket option to get more buf‐
260 fer space on UDP port 53 incoming queries. So that short spikes
261 on busy servers do not drop packets (see counter in netstat
262 -su). Default is 0 (use system value). Otherwise, the number
263 of bytes to ask for, try "4m" on a busy server. The OS caps it
264 at a maximum, on linux unbound needs root permission to bypass
265 the limit, or the admin can use sysctl net.core.rmem_max. On
266 BSD change kern.ipc.maxsockbuf in /etc/sysctl.conf. On OpenBSD
267 change header and recompile kernel. On Solaris ndd -set /dev/udp
268 udp_max_buf 8388608.
269
270 so-sndbuf: <number>
271 If not 0, then set the SO_SNDBUF socket option to get more buf‐
272 fer space on UDP port 53 outgoing queries. This for very busy
273 servers handles spikes in answer traffic, otherwise 'send:
274 resource temporarily unavailable' can get logged, the buffer
275 overrun is also visible by netstat -su. Default is 0 (use sys‐
276 tem value). Specify the number of bytes to ask for, try "4m" on
277 a very busy server. The OS caps it at a maximum, on linux
278 unbound needs root permission to bypass the limit, or the admin
279 can use sysctl net.core.wmem_max. On BSD, Solaris changes are
280 similar to so-rcvbuf.
281
282 so-reuseport: <yes or no>
283 If yes, then open dedicated listening sockets for incoming
284 queries for each thread and try to set the SO_REUSEPORT socket
285 option on each socket. May distribute incoming queries to
286 threads more evenly. Default is no. On Linux it is supported
287 in kernels >= 3.9. On other systems, FreeBSD, OSX it may also
288 work. You can enable it (on any platform and kernel), it then
289 attempts to open the port and passes the option if it was avail‐
290 able at compile time, if that works it is used, if it fails, it
291 continues silently (unless verbosity 3) without the option.
292
293 ip-transparent: <yes or no>
294 If yes, then use IP_TRANSPARENT socket option on sockets where
295 unbound is listening for incoming traffic. Default no. Allows
296 you to bind to non-local interfaces. For example for non-exis‐
297 tant IP addresses that are going to exist later on, with host
298 failover configuration. This is a lot like interface-automatic,
299 but that one services all interfaces and with this option you
300 can select which (future) interfaces unbound provides service
301 on. This option needs unbound to be started with root permis‐
302 sions on some systems. The option uses IP_BINDANY on FreeBSD
303 systems.
304
305 ip-freebind: <yes or no>
306 If yes, then use IP_FREEBIND socket option on sockets where
307 unbound is listening to incoming traffic. Default no. Allows
308 you to bind to IP addresses that are nonlocal or do not exist,
309 like when the network interface or IP address is down. Exists
310 only on Linux, where the similar ip-transparent option is also
311 available.
312
313 rrset-cache-size: <number>
314 Number of bytes size of the RRset cache. Default is 4 megabytes.
315 A plain number is in bytes, append 'k', 'm' or 'g' for kilo‐
316 bytes, megabytes or gigabytes (1024*1024 bytes in a megabyte).
317
318 rrset-cache-slabs: <number>
319 Number of slabs in the RRset cache. Slabs reduce lock contention
320 by threads. Must be set to a power of 2.
321
322 cache-max-ttl: <seconds>
323 Time to live maximum for RRsets and messages in the cache.
324 Default is 86400 seconds (1 day). If the maximum kicks in,
325 responses to clients still get decrementing TTLs based on the
326 original (larger) values. When the internal TTL expires, the
327 cache item has expired. Can be set lower to force the resolver
328 to query for data often, and not trust (very large) TTL values.
329
330 cache-min-ttl: <seconds>
331 Time to live minimum for RRsets and messages in the cache.
332 Default is 0. If the minimum kicks in, the data is cached for
333 longer than the domain owner intended, and thus less queries are
334 made to look up the data. Zero makes sure the data in the cache
335 is as the domain owner intended, higher values, especially more
336 than an hour or so, can lead to trouble as the data in the cache
337 does not match up with the actual data any more.
338
339 cache-max-negative-ttl: <seconds>
340 Time to live maximum for negative responses, these have a SOA in
341 the authority section that is limited in time. Default is 3600.
342
343 infra-host-ttl: <seconds>
344 Time to live for entries in the host cache. The host cache con‐
345 tains roundtrip timing, lameness and EDNS support information.
346 Default is 900.
347
348 infra-cache-slabs: <number>
349 Number of slabs in the infrastructure cache. Slabs reduce lock
350 contention by threads. Must be set to a power of 2.
351
352 infra-cache-numhosts: <number>
353 Number of hosts for which information is cached. Default is
354 10000.
355
356 infra-cache-min-rtt: <msec>
357 Lower limit for dynamic retransmit timeout calculation in infra‐
358 structure cache. Default is 50 milliseconds. Increase this value
359 if using forwarders needing more time to do recursive name reso‐
360 lution.
361
362 define-tag: <"list of tags">
363 Define the tags that can be used with local-zone and access-con‐
364 trol. Enclose the list between quotes ("") and put spaces
365 between tags.
366
367 do-ip4: <yes or no>
368 Enable or disable whether ip4 queries are answered or issued.
369 Default is yes.
370
371 do-ip6: <yes or no>
372 Enable or disable whether ip6 queries are answered or issued.
373 Default is yes. If disabled, queries are not answered on IPv6,
374 and queries are not sent on IPv6 to the internet nameservers.
375 With this option you can disable the ipv6 transport for sending
376 DNS traffic, it does not impact the contents of the DNS traffic,
377 which may have ip4 and ip6 addresses in it.
378
379 prefer-ip6: <yes or no>
380 If enabled, prefer IPv6 transport for sending DNS queries to
381 internet nameservers. Default is no.
382
383 do-udp: <yes or no>
384 Enable or disable whether UDP queries are answered or issued.
385 Default is yes.
386
387 do-tcp: <yes or no>
388 Enable or disable whether TCP queries are answered or issued.
389 Default is yes.
390
391 tcp-mss: <number>
392 Maximum segment size (MSS) of TCP socket on which the server
393 responds to queries. Value lower than common MSS on Ethernet
394 (1220 for example) will address path MTU problem. Note that not
395 all platform supports socket option to set MSS (TCP_MAXSEG).
396 Default is system default MSS determined by interface MTU and
397 negotiation between server and client.
398
399 outgoing-tcp-mss: <number>
400 Maximum segment size (MSS) of TCP socket for outgoing queries
401 (from Unbound to other servers). Value lower than common MSS on
402 Ethernet (1220 for example) will address path MTU problem. Note
403 that not all platform supports socket option to set MSS
404 (TCP_MAXSEG). Default is system default MSS determined by
405 interface MTU and negotiation between Unbound and other servers.
406
407 tcp-upstream: <yes or no>
408 Enable or disable whether the upstream queries use TCP only for
409 transport. Default is no. Useful in tunneling scenarios.
410
411 ssl-upstream: <yes or no>
412 Enabled or disable whether the upstream queries use SSL only for
413 transport. Default is no. Useful in tunneling scenarios. The
414 SSL contains plain DNS in TCP wireformat. The other server must
415 support this (see ssl-service-key).
416
417 ssl-service-key: <file>
418 If enabled, the server provider SSL service on its TCP sockets.
419 The clients have to use ssl-upstream: yes. The file is the pri‐
420 vate key for the TLS session. The public certificate is in the
421 ssl-service-pem file. Default is "", turned off. Requires a
422 restart (a reload is not enough) if changed, because the private
423 key is read while root permissions are held and before chroot
424 (if any). Normal DNS TCP service is not provided and gives
425 errors, this service is best run with a different port: config
426 or @port suffixes in the interface config.
427
428 ssl-service-pem: <file>
429 The public key certificate pem file for the ssl service.
430 Default is "", turned off.
431
432 ssl-port: <number>
433 The port number on which to provide TCP SSL service, default
434 853, only interfaces configured with that port number as @number
435 get the SSL service.
436
437 use-systemd: <yes or no>
438 Enable or disable systemd socket activation. Default is no.
439
440 do-daemonize: <yes or no>
441 Enable or disable whether the unbound server forks into the
442 background as a daemon. Set the value to no when unbound runs
443 as systemd service. Default is yes.
444
445 access-control: <IP netblock> <action>
446 The netblock is given as an IP4 or IP6 address with /size
447 appended for a classless network block. The action can be deny,
448 refuse, allow, allow_snoop, deny_non_local or refuse_non_local.
449 The most specific netblock match is used, if none match deny is
450 used.
451
452 The action deny stops queries from hosts from that netblock.
453
454 The action refuse stops queries too, but sends a DNS rcode
455 REFUSED error message back.
456
457 The action allow gives access to clients from that netblock. It
458 gives only access for recursion clients (which is what almost
459 all clients need). Nonrecursive queries are refused.
460
461 The allow action does allow nonrecursive queries to access the
462 local-data that is configured. The reason is that this does not
463 involve the unbound server recursive lookup algorithm, and
464 static data is served in the reply. This supports normal opera‐
465 tions where nonrecursive queries are made for the authoritative
466 data. For nonrecursive queries any replies from the dynamic
467 cache are refused.
468
469 The action allow_snoop gives nonrecursive access too. This give
470 both recursive and non recursive access. The name allow_snoop
471 refers to cache snooping, a technique to use nonrecursive
472 queries to examine the cache contents (for malicious acts).
473 However, nonrecursive queries can also be a valuable debugging
474 tool (when you want to examine the cache contents). In that case
475 use allow_snoop for your administration host.
476
477 By default only localhost is allowed, the rest is refused. The
478 default is refused, because that is protocol-friendly. The DNS
479 protocol is not designed to handle dropped packets due to pol‐
480 icy, and dropping may result in (possibly excessive) retried
481 queries.
482
483 The deny_non_local and refuse_non_local settings are for hosts
484 that are only allowed to query for the authoritative local-data,
485 they are not allowed full recursion but only the static data.
486 With deny_non_local, messages that are disallowed are dropped,
487 with refuse_non_local they receive error code REFUSED.
488
489 access-control-tag: <IP netblock> <"list of tags">
490 Assign tags to access-control elements. Clients using this
491 access control element use localzones that are tagged with one
492 of these tags. Tags must be defined in define-tags. Enclose
493 list of tags in quotes ("") and put spaces between tags. If
494 access-control-tag is configured for a netblock that does not
495 have an access-control, an access-control element with action
496 allow is configured for this netblock.
497
498 access-control-tag-action: <IP netblock> <tag> <action>
499 Set action for particular tag for given access control element.
500 If you have multiple tag values, the tag used to lookup the
501 action is the first tag match between access-control-tag and
502 local-zone-tag where "first" comes from the order of the define-
503 tag values.
504
505 access-control-tag-data: <IP netblock> <tag> <"resource record string">
506 Set redirect data for particular tag for given access control
507 element.
508
509 access-control-view: <IP netblock> <view name>
510 Set view for given access control element.
511
512 chroot: <directory>
513 If chroot is enabled, you should pass the configfile (from the
514 commandline) as a full path from the original root. After the
515 chroot has been performed the now defunct portion of the config
516 file path is removed to be able to reread the config after a
517 reload.
518
519 All other file paths (working dir, logfile, roothints, and key
520 files) can be specified in several ways: as an absolute path
521 relative to the new root, as a relative path to the working
522 directory, or as an absolute path relative to the original root.
523 In the last case the path is adjusted to remove the unused por‐
524 tion.
525
526 The pidfile can be either a relative path to the working direc‐
527 tory, or an absolute path relative to the original root. It is
528 written just prior to chroot and dropping permissions. This
529 allows the pidfile to be /var/run/unbound.pid and the chroot to
530 be /var/unbound, for example.
531
532 Additionally, unbound may need to access /dev/random (for
533 entropy) from inside the chroot.
534
535 If given a chroot is done to the given directory. The default is
536 "/etc/unbound". If you give "" no chroot is performed.
537
538 username: <name>
539 If given, after binding the port the user privileges are
540 dropped. Default is "unbound". If you give username: "" no user
541 change is performed.
542
543 If this user is not capable of binding the port, reloads (by
544 signal HUP) will still retain the opened ports. If you change
545 the port number in the config file, and that new port number
546 requires privileges, then a reload will fail; a restart is
547 needed.
548
549 directory: <directory>
550 Sets the working directory for the program. Default is
551 "/etc/unbound". On Windows the string "%EXECUTABLE%" tries to
552 change to the directory that unbound.exe resides in. If you
553 give a server: directory: dir before include: file statements
554 then those includes can be relative to the working directory.
555
556 logfile: <filename>
557 If "" is given, logging goes to stderr, or nowhere once daemo‐
558 nized. The logfile is appended to, in the following format:
559 [seconds since 1970] unbound[pid:tid]: type: message.
560 If this option is given, the use-syslog is option is set to
561 "no". The logfile is reopened (for append) when the config file
562 is reread, on SIGHUP.
563
564 use-syslog: <yes or no>
565 Sets unbound to send log messages to the syslogd, using sys‐
566 log(3). The log facility LOG_DAEMON is used, with identity
567 "unbound". The logfile setting is overridden when use-syslog is
568 turned on. The default is to log to syslog.
569
570 log-identity: <string>
571 If "" is given (default), then the name of the executable, usu‐
572 ally "unbound" is used to report to the log. Enter a string to
573 override it with that, which is useful on systems that run more
574 than one instance of unbound, with different configurations, so
575 that the logs can be easily distinguished against.
576
577 log-time-ascii: <yes or no>
578 Sets logfile lines to use a timestamp in UTC ascii. Default is
579 no, which prints the seconds since 1970 in brackets. No effect
580 if using syslog, in that case syslog formats the timestamp
581 printed into the log files.
582
583 log-queries: <yes or no>
584 Prints one line per query to the log, with the log timestamp and
585 IP address, name, type and class. Default is no. Note that it
586 takes time to print these lines which makes the server (signifi‐
587 cantly) slower. Odd (nonprintable) characters in names are
588 printed as '?'.
589
590 log-replies: <yes or no>
591 Prints one line per reply to the log, with the log timestamp and
592 IP address, name, type, class, return code, time to resolve,
593 from cache and response size. Default is no. Note that it
594 takes time to print these lines which makes the server (signifi‐
595 cantly) slower. Odd (nonprintable) characters in names are
596 printed as '?'.
597
598 pidfile: <filename>
599 The process id is written to the file. Default is
600 "/var/run/unbound/unbound.pid". So,
601 kill -HUP `cat /var/run/unbound/unbound.pid`
602 triggers a reload,
603 kill -TERM `cat /var/run/unbound/unbound.pid`
604 gracefully terminates.
605
606 root-hints: <filename>
607 Read the root hints from this file. Default is nothing, using
608 builtin hints for the IN class. The file has the format of zone
609 files, with root nameserver names and addresses only. The
610 default may become outdated, when servers change, therefore it
611 is good practice to use a root-hints file.
612
613 hide-identity: <yes or no>
614 If enabled id.server and hostname.bind queries are refused.
615
616 identity: <string>
617 Set the identity to report. If set to "", the default, then the
618 hostname of the server is returned.
619
620 hide-version: <yes or no>
621 If enabled version.server and version.bind queries are refused.
622
623 version: <string>
624 Set the version to report. If set to "", the default, then the
625 package version is returned.
626
627 hide-trustanchor: <yes or no>
628 If enabled trustanchor.unbound queries are refused.
629
630 target-fetch-policy: <"list of numbers">
631 Set the target fetch policy used by unbound to determine if it
632 should fetch nameserver target addresses opportunistically. The
633 policy is described per dependency depth.
634
635 The number of values determines the maximum dependency depth
636 that unbound will pursue in answering a query. A value of -1
637 means to fetch all targets opportunistically for that dependency
638 depth. A value of 0 means to fetch on demand only. A positive
639 value fetches that many targets opportunistically.
640
641 Enclose the list between quotes ("") and put spaces between num‐
642 bers. The default is "3 2 1 0 0". Setting all zeroes, "0 0 0 0
643 0" gives behaviour closer to that of BIND 9, while setting "-1
644 -1 -1 -1 -1" gives behaviour rumoured to be closer to that of
645 BIND 8.
646
647 harden-short-bufsize: <yes or no>
648 Very small EDNS buffer sizes from queries are ignored. Default
649 is off, since it is legal protocol wise to send these, and
650 unbound tries to give very small answers to these queries, where
651 possible.
652
653 harden-large-queries: <yes or no>
654 Very large queries are ignored. Default is off, since it is
655 legal protocol wise to send these, and could be necessary for
656 operation if TSIG or EDNS payload is very large.
657
658 harden-glue: <yes or no>
659 Will trust glue only if it is within the servers authority.
660 Default is on.
661
662 harden-dnssec-stripped: <yes or no>
663 Require DNSSEC data for trust-anchored zones, if such data is
664 absent, the zone becomes bogus. If turned off, and no DNSSEC
665 data is received (or the DNSKEY data fails to validate), then
666 the zone is made insecure, this behaves like there is no trust
667 anchor. You could turn this off if you are sometimes behind an
668 intrusive firewall (of some sort) that removes DNSSEC data from
669 packets, or a zone changes from signed to unsigned to badly
670 signed often. If turned off you run the risk of a downgrade
671 attack that disables security for a zone. Default is on.
672
673 harden-below-nxdomain: <yes or no>
674 From RFC 8020 (with title "NXDOMAIN: There Really Is Nothing
675 Underneath"), returns nxdomain to queries for a name below
676 another name that is already known to be nxdomain. DNSSEC man‐
677 dates noerror for empty nonterminals, hence this is possible.
678 Very old software might return nxdomain for empty nonterminals
679 (that usually happen for reverse IP address lookups), and thus
680 may be incompatible with this. To try to avoid this only
681 DNSSEC-secure nxdomains are used, because the old software does
682 not have DNSSEC. Default is off. The nxdomain must be secure,
683 this means nsec3 with optout is insufficient.
684
685 harden-referral-path: <yes or no>
686 Harden the referral path by performing additional queries for
687 infrastructure data. Validates the replies if trust anchors are
688 configured and the zones are signed. This enforces DNSSEC vali‐
689 dation on nameserver NS sets and the nameserver addresses that
690 are encountered on the referral path to the answer. Default
691 off, because it burdens the authority servers, and it is not RFC
692 standard, and could lead to performance problems because of the
693 extra query load that is generated. Experimental option. If
694 you enable it consider adding more numbers after the tar‐
695 get-fetch-policy to increase the max depth that is checked to.
696
697 harden-algo-downgrade: <yes or no>
698 Harden against algorithm downgrade when multiple algorithms are
699 advertised in the DS record. If no, allows the weakest algo‐
700 rithm to validate the zone. Default is no. Zone signers must
701 produce zones that allow this feature to work, but sometimes
702 they do not, and turning this option off avoids that validation
703 failure.
704
705 use-caps-for-id: <yes or no>
706 Use 0x20-encoded random bits in the query to foil spoof
707 attempts. This perturbs the lowercase and uppercase of query
708 names sent to authority servers and checks if the reply still
709 has the correct casing. Disabled by default. This feature is
710 an experimental implementation of draft dns-0x20.
711
712 caps-whitelist: <domain>
713 Whitelist the domain so that it does not receive caps-for-id
714 perturbed queries. For domains that do not support 0x20 and
715 also fail with fallback because they keep sending different
716 answers, like some load balancers. Can be given multiple times,
717 for different domains.
718
719 qname-minimisation: <yes or no>
720 Send minimum amount of information to upstream servers to
721 enhance privacy. Only sent minimum required labels of the QNAME
722 and set QTYPE to NS when possible. Best effort approach; full
723 QNAME and original QTYPE will be sent when upstream replies with
724 a RCODE other than NOERROR, except when receiving NXDOMAIN from
725 a DNSSEC signed zone. Default is off.
726
727 qname-minimisation-strict: <yes or no>
728 QNAME minimisation in strict mode. Do not fall-back to sending
729 full QNAME to potentially broken nameservers. A lot of domains
730 will not be resolvable when this option in enabled. Only use if
731 you know what you are doing. This option only has effect when
732 qname-minimisation is enabled. Default is off.
733
734 private-address: <IP address or subnet>
735 Give IPv4 of IPv6 addresses or classless subnets. These are
736 addresses on your private network, and are not allowed to be
737 returned for public internet names. Any occurrence of such
738 addresses are removed from DNS answers. Additionally, the DNSSEC
739 validator may mark the answers bogus. This protects against
740 so-called DNS Rebinding, where a user browser is turned into a
741 network proxy, allowing remote access through the browser to
742 other parts of your private network. Some names can be allowed
743 to contain your private addresses, by default all the local-data
744 that you configured is allowed to, and you can specify addi‐
745 tional names using private-domain. No private addresses are
746 enabled by default. We consider to enable this for the RFC1918
747 private IP address space by default in later releases. That
748 would enable private addresses for 10.0.0.0/8 172.16.0.0/12
749 192.168.0.0/16 169.254.0.0/16 fd00::/8 and fe80::/10, since the
750 RFC standards say these addresses should not be visible on the
751 public internet. Turning on 127.0.0.0/8 would hinder many spam‐
752 blocklists as they use that. Adding ::ffff:0:0/96 stops
753 IPv4-mapped IPv6 addresses from bypassing the filter.
754
755 private-domain: <domain name>
756 Allow this domain, and all its subdomains to contain private
757 addresses. Give multiple times to allow multiple domain names
758 to contain private addresses. Default is none.
759
760 unwanted-reply-threshold: <number>
761 If set, a total number of unwanted replies is kept track of in
762 every thread. When it reaches the threshold, a defensive action
763 is taken and a warning is printed to the log. The defensive
764 action is to clear the rrset and message caches, hopefully
765 flushing away any poison. A value of 10 million is suggested.
766 Default is 0 (turned off).
767
768 do-not-query-address: <IP address>
769 Do not query the given IP address. Can be IP4 or IP6. Append
770 /num to indicate a classless delegation netblock, for example
771 like 10.2.3.4/24 or 2001::11/64.
772
773 do-not-query-localhost: <yes or no>
774 If yes, localhost is added to the do-not-query-address entries,
775 both IP6 ::1 and IP4 127.0.0.1/8. If no, then localhost can be
776 used to send queries to. Default is yes.
777
778 prefetch: <yes or no>
779 If yes, message cache elements are prefetched before they expire
780 to keep the cache up to date. Default is no. Turning it on
781 gives about 10 percent more traffic and load on the machine, but
782 popular items do not expire from the cache.
783
784 prefetch-key: <yes or no>
785 If yes, fetch the DNSKEYs earlier in the validation process,
786 when a DS record is encountered. This lowers the latency of
787 requests. It does use a little more CPU. Also if the cache is
788 set to 0, it is no use. Default is no.
789
790 rrset-roundrobin: <yes or no>
791 If yes, Unbound rotates RRSet order in response (the random num‐
792 ber is taken from the query ID, for speed and thread safety).
793 Default is no.
794
795 minimal-responses: <yes or no>
796 If yes, Unbound doesn't insert authority/additional sections
797 into response messages when those sections are not required.
798 This reduces response size significantly, and may avoid TCP
799 fallback for some responses. This may cause a slight speedup.
800 The default is no, because the DNS protocol RFCs mandate these
801 sections, and the additional content could be of use and save
802 roundtrips for clients.
803
804 disable-dnssec-lame-check: <yes or no>
805 If true, disables the DNSSEC lameness check in the iterator.
806 This check sees if RRSIGs are present in the answer, when dnssec
807 is expected, and retries another authority if RRSIGs are unex‐
808 pectedly missing. The validator will insist in RRSIGs for
809 DNSSEC signed domains regardless of this setting, if a trust
810 anchor is loaded.
811
812 module-config: <"module names">
813 Module configuration, a list of module names separated by spa‐
814 ces, surround the string with quotes (""). The modules can be
815 validator, iterator. Setting this to "iterator" will result in
816 a non-validating server. Setting this to "validator iterator"
817 will turn on DNSSEC validation. The ordering of the modules is
818 important. You must also set trust-anchors for validation to be
819 useful.
820
821 trust-anchor-file: <filename>
822 File with trusted keys for validation. Both DS and DNSKEY
823 entries can appear in the file. The format of the file is the
824 standard DNS Zone file format. Default is "", or no trust
825 anchor file.
826
827 auto-trust-anchor-file: <filename>
828 File with trust anchor for one zone, which is tracked with
829 RFC5011 probes. The probes are several times per month, thus
830 the machine must be online frequently. The initial file can be
831 one with contents as described in trust-anchor-file. The file
832 is written to when the anchor is updated, so the unbound user
833 must have write permission. Write permission to the file, but
834 also to the directory it is in (to create a temporary file,
835 which is necessary to deal with filesystem full events), it must
836 also be inside the chroot (if that is used).
837
838 trust-anchor: <"Resource Record">
839 A DS or DNSKEY RR for a key to use for validation. Multiple
840 entries can be given to specify multiple trusted keys, in addi‐
841 tion to the trust-anchor-files. The resource record is entered
842 in the same format as 'dig' or 'drill' prints them, the same
843 format as in the zone file. Has to be on a single line, with ""
844 around it. A TTL can be specified for ease of cut and paste, but
845 is ignored. A class can be specified, but class IN is default.
846
847 trusted-keys-file: <filename>
848 File with trusted keys for validation. Specify more than one
849 file with several entries, one file per entry. Like
850 trust-anchor-file but has a different file format. Format is
851 BIND-9 style format, the trusted-keys { name flag proto algo
852 "key"; }; clauses are read. It is possible to use wildcards
853 with this statement, the wildcard is expanded on start and on
854 reload.
855
856 trust-anchor-signaling: <yes or no>
857 Send RFC8145 key tag query after trust anchor priming. Default
858 is off.
859
860 dlv-anchor-file: <filename>
861 This option was used during early days DNSSEC deployment when no
862 parent-side DS record registrations were easily available.
863 Nowadays, it is best to have DS records registered with the par‐
864 ent zone (many top level zones are signed). File with trusted
865 keys for DLV (DNSSEC Lookaside Validation). Both DS and DNSKEY
866 entries can be used in the file, in the same format as for
867 trust-anchor-file: statements. Only one DLV can be configured,
868 more would be slow. The DLV configured is used as a root trusted
869 DLV, this means that it is a lookaside for the root. Default is
870 "", or no dlv anchor file. DLV is going to be decommissioned.
871 Please do not use it any more.
872
873 dlv-anchor: <"Resource Record">
874 Much like trust-anchor, this is a DLV anchor with the DS or
875 DNSKEY inline. DLV is going to be decommissioned. Please do
876 not use it any more.
877
878 domain-insecure: <domain name>
879 Sets domain name to be insecure, DNSSEC chain of trust is
880 ignored towards the domain name. So a trust anchor above the
881 domain name can not make the domain secure with a DS record,
882 such a DS record is then ignored. Also keys from DLV are
883 ignored for the domain. Can be given multiple times to specify
884 multiple domains that are treated as if unsigned. If you set
885 trust anchors for the domain they override this setting (and the
886 domain is secured).
887
888 This can be useful if you want to make sure a trust anchor for
889 external lookups does not affect an (unsigned) internal domain.
890 A DS record externally can create validation failures for that
891 internal domain.
892
893 val-override-date: <rrsig-style date spec>
894 Default is "" or "0", which disables this debugging feature. If
895 enabled by giving a RRSIG style date, that date is used for ver‐
896 ifying RRSIG inception and expiration dates, instead of the cur‐
897 rent date. Do not set this unless you are debugging signature
898 inception and expiration. The value -1 ignores the date alto‐
899 gether, useful for some special applications.
900
901 val-sig-skew-min: <seconds>
902 Minimum number of seconds of clock skew to apply to validated
903 signatures. A value of 10% of the signature lifetime (expira‐
904 tion - inception) is used, capped by this setting. Default is
905 3600 (1 hour) which allows for daylight savings differences.
906 Lower this value for more strict checking of short lived signa‐
907 tures.
908
909 val-sig-skew-max: <seconds>
910 Maximum number of seconds of clock skew to apply to validated
911 signatures. A value of 10% of the signature lifetime (expira‐
912 tion - inception) is used, capped by this setting. Default is
913 86400 (24 hours) which allows for timezone setting problems in
914 stable domains. Setting both min and max very low disables the
915 clock skew allowances. Setting both min and max very high makes
916 the validator check the signature timestamps less strictly.
917
918 val-bogus-ttl: <number>
919 The time to live for bogus data. This is data that has failed
920 validation; due to invalid signatures or other checks. The TTL
921 from that data cannot be trusted, and this value is used
922 instead. The value is in seconds, default 60. The time interval
923 prevents repeated revalidation of bogus data.
924
925 val-clean-additional: <yes or no>
926 Instruct the validator to remove data from the additional sec‐
927 tion of secure messages that are not signed properly. Messages
928 that are insecure, bogus, indeterminate or unchecked are not
929 affected. Default is yes. Use this setting to protect the users
930 that rely on this validator for authentication from potentially
931 bad data in the additional section.
932
933 val-log-level: <number>
934 Have the validator print validation failures to the log.
935 Regardless of the verbosity setting. Default is 0, off. At 1,
936 for every user query that fails a line is printed to the logs.
937 This way you can monitor what happens with validation. Use a
938 diagnosis tool, such as dig or drill, to find out why validation
939 is failing for these queries. At 2, not only the query that
940 failed is printed but also the reason why unbound thought it was
941 wrong and which server sent the faulty data.
942
943 val-permissive-mode: <yes or no>
944 Instruct the validator to mark bogus messages as indeterminate.
945 The security checks are performed, but if the result is bogus
946 (failed security), the reply is not withheld from the client
947 with SERVFAIL as usual. The client receives the bogus data. For
948 messages that are found to be secure the AD bit is set in
949 replies. Also logging is performed as for full validation. The
950 default value is "no".
951
952 ignore-cd-flag: <yes or no>
953 Instruct unbound to ignore the CD flag from clients and refuse
954 to return bogus answers to them. Thus, the CD (Checking Dis‐
955 abled) flag does not disable checking any more. This is useful
956 if legacy (w2008) servers that set the CD flag but cannot vali‐
957 date DNSSEC themselves are the clients, and then unbound pro‐
958 vides them with DNSSEC protection. The default value is "no".
959
960 serve-expired: <yes or no>
961 If enabled, unbound attempts to serve old responses from cache
962 with a TTL of 0 in the response without waiting for the actual
963 resolution to finish. The actual resolution answer ends up in
964 the cache later on. Default is "no".
965
966 val-nsec3-keysize-iterations: <"list of values">
967 List of keysize and iteration count values, separated by spaces,
968 surrounded by quotes. Default is "1024 150 2048 500 4096 2500".
969 This determines the maximum allowed NSEC3 iteration count before
970 a message is simply marked insecure instead of performing the
971 many hashing iterations. The list must be in ascending order and
972 have at least one entry. If you set it to "1024 65535" there is
973 no restriction to NSEC3 iteration values. This table must be
974 kept short; a very long list could cause slower operation.
975
976 add-holddown: <seconds>
977 Instruct the auto-trust-anchor-file probe mechanism for RFC5011
978 autotrust updates to add new trust anchors only after they have
979 been visible for this time. Default is 30 days as per the RFC.
980
981 del-holddown: <seconds>
982 Instruct the auto-trust-anchor-file probe mechanism for RFC5011
983 autotrust updates to remove revoked trust anchors after they
984 have been kept in the revoked list for this long. Default is 30
985 days as per the RFC.
986
987 keep-missing: <seconds>
988 Instruct the auto-trust-anchor-file probe mechanism for RFC5011
989 autotrust updates to remove missing trust anchors after they
990 have been unseen for this long. This cleans up the state file
991 if the target zone does not perform trust anchor revocation, so
992 this makes the auto probe mechanism work with zones that perform
993 regular (non-5011) rollovers. The default is 366 days. The
994 value 0 does not remove missing anchors, as per the RFC.
995
996 permit-small-holddown: <yes or no>
997 Debug option that allows the autotrust 5011 rollover timers to
998 assume very small values. Default is no.
999
1000 key-cache-size: <number>
1001 Number of bytes size of the key cache. Default is 4 megabytes.
1002 A plain number is in bytes, append 'k', 'm' or 'g' for kilo‐
1003 bytes, megabytes or gigabytes (1024*1024 bytes in a megabyte).
1004
1005 key-cache-slabs: <number>
1006 Number of slabs in the key cache. Slabs reduce lock contention
1007 by threads. Must be set to a power of 2. Setting (close) to the
1008 number of cpus is a reasonable guess.
1009
1010 neg-cache-size: <number>
1011 Number of bytes size of the aggressive negative cache. Default
1012 is 1 megabyte. A plain number is in bytes, append 'k', 'm' or
1013 'g' for kilobytes, megabytes or gigabytes (1024*1024 bytes in a
1014 megabyte).
1015
1016 unblock-lan-zones: <yesno>
1017 Default is disabled. If enabled, then for private address
1018 space, the reverse lookups are no longer filtered. This allows
1019 unbound when running as dns service on a host where it provides
1020 service for that host, to put out all of the queries for the
1021 'lan' upstream. When enabled, only localhost, 127.0.0.1 reverse
1022 and ::1 reverse zones are configured with default local zones.
1023 Disable the option when unbound is running as a (DHCP-) DNS net‐
1024 work resolver for a group of machines, where such lookups should
1025 be filtered (RFC compliance), this also stops potential data
1026 leakage about the local network to the upstream DNS servers.
1027
1028 insecure-lan-zones: <yesno>
1029 Default is disabled. If enabled, then reverse lookups in pri‐
1030 vate address space are not validated. This is usually required
1031 whenever unblock-lan-zones is used.
1032
1033 local-zone: <zone> <type>
1034 Configure a local zone. The type determines the answer to give
1035 if there is no match from local-data. The types are deny,
1036 refuse, static, transparent, redirect, nodefault, typetranspar‐
1037 ent, inform, inform_deny, always_transparent, always_refuse,
1038 always_nxdomain, and are explained below. After that the default
1039 settings are listed. Use local-data: to enter data into the
1040 local zone. Answers for local zones are authoritative DNS
1041 answers. By default the zones are class IN.
1042
1043 If you need more complicated authoritative data, with referrals,
1044 wildcards, CNAME/DNAME support, or DNSSEC authoritative service,
1045 setup a stub-zone for it as detailed in the stub zone section
1046 below.
1047
1048 deny Do not send an answer, drop the query. If there is a match
1049 from local data, the query is answered.
1050
1051 refuse
1052 Send an error message reply, with rcode REFUSED. If there is
1053 a match from local data, the query is answered.
1054
1055 static
1056 If there is a match from local data, the query is answered.
1057 Otherwise, the query is answered with nodata or nxdomain.
1058 For a negative answer a SOA is included in the answer if
1059 present as local-data for the zone apex domain.
1060
1061 transparent
1062 If there is a match from local data, the query is answered.
1063 Otherwise if the query has a different name, the query is
1064 resolved normally. If the query is for a name given in
1065 localdata but no such type of data is given in localdata,
1066 then a noerror nodata answer is returned. If no local-zone
1067 is given local-data causes a transparent zone to be created
1068 by default.
1069
1070 typetransparent
1071 If there is a match from local data, the query is answered.
1072 If the query is for a different name, or for the same name
1073 but for a different type, the query is resolved normally.
1074 So, similar to transparent but types that are not listed in
1075 local data are resolved normally, so if an A record is in the
1076 local data that does not cause a nodata reply for AAAA
1077 queries.
1078
1079 redirect
1080 The query is answered from the local data for the zone name.
1081 There may be no local data beneath the zone name. This
1082 answers queries for the zone, and all subdomains of the zone
1083 with the local data for the zone. It can be used to redirect
1084 a domain to return a different address record to the end
1085 user, with local-zone: "example.com." redirect and
1086 local-data: "example.com. A 127.0.0.1" queries for www.exam‐
1087 ple.com and www.foo.example.com are redirected, so that users
1088 with web browsers cannot access sites with suffix exam‐
1089 ple.com.
1090
1091 inform
1092 The query is answered normally, same as transparent. The
1093 client IP address (@portnumber) is printed to the logfile.
1094 The log message is: timestamp, unbound-pid, info: zonename
1095 inform IP@port queryname type class. This option can be used
1096 for normal resolution, but machines looking up infected names
1097 are logged, eg. to run antivirus on them.
1098
1099 inform_deny
1100 The query is dropped, like 'deny', and logged, like 'inform'.
1101 Ie. find infected machines without answering the queries.
1102
1103 always_transparent
1104 Like transparent, but ignores local data and resolves nor‐
1105 mally.
1106
1107 always_refuse
1108 Like refuse, but ignores local data and refuses the query.
1109
1110 always_nxdomain
1111 Like static, but ignores local data and returns nxdomain for
1112 the query.
1113
1114 nodefault
1115 Used to turn off default contents for AS112 zones. The other
1116 types also turn off default contents for the zone. The 'node‐
1117 fault' option has no other effect than turning off default
1118 contents for the given zone. Use nodefault if you use
1119 exactly that zone, if you want to use a subzone, use trans‐
1120 parent.
1121
1122 The default zones are localhost, reverse 127.0.0.1 and ::1, the onion,
1123 test, invalid and the AS112 zones. The AS112 zones are reverse DNS
1124 zones for private use and reserved IP addresses for which the servers
1125 on the internet cannot provide correct answers. They are configured by
1126 default to give nxdomain (no reverse information) answers. The defaults
1127 can be turned off by specifying your own local-zone of that name, or
1128 using the 'nodefault' type. Below is a list of the default zone con‐
1129 tents.
1130
1131 localhost
1132 The IP4 and IP6 localhost information is given. NS and SOA
1133 records are provided for completeness and to satisfy some DNS
1134 update tools. Default content:
1135 local-zone: "localhost." redirect
1136 local-data: "localhost. 10800 IN NS localhost."
1137 local-data: "localhost. 10800 IN
1138 SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1139 local-data: "localhost. 10800 IN A 127.0.0.1"
1140 local-data: "localhost. 10800 IN AAAA ::1"
1141
1142 reverse IPv4 loopback
1143 Default content:
1144 local-zone: "127.in-addr.arpa." static
1145 local-data: "127.in-addr.arpa. 10800 IN NS localhost."
1146 local-data: "127.in-addr.arpa. 10800 IN
1147 SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1148 local-data: "1.0.0.127.in-addr.arpa. 10800 IN
1149 PTR localhost."
1150
1151 reverse IPv6 loopback
1152 Default content:
1153 local-zone: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
1154 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." static
1155 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
1156 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
1157 NS localhost."
1158 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
1159 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
1160 SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1161 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
1162 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
1163 PTR localhost."
1164
1165 onion (RFC 7686)
1166 Default content:
1167 local-zone: "onion." static
1168 local-data: "onion. 10800 IN NS localhost."
1169 local-data: "onion. 10800 IN
1170 SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1171
1172 test (RFC 7686)
1173 Default content:
1174 local-zone: "test." static
1175 local-data: "test. 10800 IN NS localhost."
1176 local-data: "test. 10800 IN
1177 SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1178
1179 invalid (RFC 7686)
1180 Default content:
1181 local-zone: "invalid." static
1182 local-data: "invalid. 10800 IN NS localhost."
1183 local-data: "invalid. 10800 IN
1184 SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
1185
1186 reverse RFC1918 local use zones
1187 Reverse data for zones 10.in-addr.arpa, 16.172.in-addr.arpa
1188 to 31.172.in-addr.arpa, 168.192.in-addr.arpa. The
1189 local-zone: is set static and as local-data: SOA and NS
1190 records are provided.
1191
1192 reverse RFC3330 IP4 this, link-local, testnet and broadcast
1193 Reverse data for zones 0.in-addr.arpa, 254.169.in-addr.arpa,
1194 2.0.192.in-addr.arpa (TEST NET 1), 100.51.198.in-addr.arpa
1195 (TEST NET 2), 113.0.203.in-addr.arpa (TEST NET 3),
1196 255.255.255.255.in-addr.arpa. And from 64.100.in-addr.arpa
1197 to 127.100.in-addr.arpa (Shared Address Space).
1198
1199 reverse RFC4291 IP6 unspecified
1200 Reverse data for zone
1201 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
1202 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa.
1203
1204 reverse RFC4193 IPv6 Locally Assigned Local Addresses
1205 Reverse data for zone D.F.ip6.arpa.
1206
1207 reverse RFC4291 IPv6 Link Local Addresses
1208 Reverse data for zones 8.E.F.ip6.arpa to B.E.F.ip6.arpa.
1209
1210 reverse IPv6 Example Prefix
1211 Reverse data for zone 8.B.D.0.1.0.0.2.ip6.arpa. This zone is
1212 used for tutorials and examples. You can remove the block on
1213 this zone with:
1214 local-zone: 8.B.D.0.1.0.0.2.ip6.arpa. nodefault
1215 You can also selectively unblock a part of the zone by making
1216 that part transparent with a local-zone statement. This also
1217 works with the other default zones.
1218
1219 local-data: "<resource record string>"
1220 Configure local data, which is served in reply to queries for it.
1221 The query has to match exactly unless you configure the local-zone
1222 as redirect. If not matched exactly, the local-zone type deter‐
1223 mines further processing. If local-data is configured that is not
1224 a subdomain of a local-zone, a transparent local-zone is config‐
1225 ured. For record types such as TXT, use single quotes, as in
1226 local-data: 'example. TXT "text"'.
1227
1228 If you need more complicated authoritative data, with referrals,
1229 wildcards, CNAME/DNAME support, or DNSSEC authoritative service,
1230 setup a stub-zone for it as detailed in the stub zone section
1231 below.
1232
1233 local-data-ptr: "IPaddr name"
1234 Configure local data shorthand for a PTR record with the reversed
1235 IPv4 or IPv6 address and the host name. For example "192.0.2.4
1236 www.example.com". TTL can be inserted like this: "2001:DB8::4
1237 7200 www.example.com"
1238
1239 local-zone-tag: <zone> <"list of tags">
1240 Assign tags to localzones. Tagged localzones will only be applied
1241 when the used access-control element has a matching tag. Tags must
1242 be defined in define-tags. Enclose list of tags in quotes ("")
1243 and put spaces between tags.
1244
1245 local-zone-override: <zone> <IP netblock> <type>
1246 Override the localzone type for queries from addresses matching
1247 netblock. Use this localzone type, regardless the type configured
1248 for the local-zone (both tagged and untagged) and regardless the
1249 type configured using access-control-tag-action.
1250
1251 ratelimit: <number or 0>
1252 Enable ratelimiting of queries sent to nameserver for performing
1253 recursion. If 0, the default, it is disabled. This option is
1254 experimental at this time. The ratelimit is in queries per second
1255 that are allowed. More queries are turned away with an error
1256 (servfail). This stops recursive floods, eg. random query names,
1257 but not spoofed reflection floods. Cached responses are not rate‐
1258 limited by this setting. The zone of the query is determined by
1259 examining the nameservers for it, the zone name is used to keep
1260 track of the rate. For example, 1000 may be a suitable value to
1261 stop the server from being overloaded with random names, and keeps
1262 unbound from sending traffic to the nameservers for those zones.
1263
1264 ratelimit-size: <memory size>
1265 Give the size of the data structure in which the current ongoing
1266 rates are kept track in. Default 4m. In bytes or use m(mega),
1267 k(kilo), g(giga). The ratelimit structure is small, so this data
1268 structure likely does not need to be large.
1269
1270 ratelimit-slabs: <number>
1271 Give power of 2 number of slabs, this is used to reduce lock con‐
1272 tention in the ratelimit tracking data structure. Close to the
1273 number of cpus is a fairly good setting.
1274
1275 ratelimit-factor: <number>
1276 Set the amount of queries to rate limit when the limit is
1277 exceeded. If set to 0, all queries are dropped for domains where
1278 the limit is exceeded. If set to another value, 1 in that number
1279 is allowed through to complete. Default is 10, allowing 1/10
1280 traffic to flow normally. This can make ordinary queries complete
1281 (if repeatedly queried for), and enter the cache, whilst also mit‐
1282 igating the traffic flow by the factor given.
1283
1284 ratelimit-for-domain: <domain> <number qps or 0>
1285 Override the global ratelimit for an exact match domain name with
1286 the listed number. You can give this for any number of names.
1287 For example, for a top-level-domain you may want to have a higher
1288 limit than other names. A value of 0 will disable ratelimiting
1289 for that domain.
1290
1291 ratelimit-below-domain: <domain> <number qps or 0>
1292 Override the global ratelimit for a domain name that ends in this
1293 name. You can give this multiple times, it then describes differ‐
1294 ent settings in different parts of the namespace. The closest
1295 matching suffix is used to determine the qps limit. The rate for
1296 the exact matching domain name is not changed, use rate‐
1297 limit-for-domain to set that, you might want to use different set‐
1298 tings for a top-level-domain and subdomains. A value of 0 will
1299 disable ratelimiting for domain names that end in this name.
1300
1301 ip-ratelimit: <number or 0>
1302 Enable global ratelimiting of queries accepted per ip address. If
1303 0, the default, it is disabled. This option is experimental at
1304 this time. The ratelimit is in queries per second that are
1305 allowed. More queries are completely dropped and will not receive
1306 a reply, SERVFAIL or otherwise. IP ratelimiting happens before
1307 looking in the cache. This may be useful for mitigating amplifica‐
1308 tion attacks.
1309
1310 ip-ratelimit-size: <memory size>
1311 Give the size of the data structure in which the current ongoing
1312 rates are kept track in. Default 4m. In bytes or use m(mega),
1313 k(kilo), g(giga). The ip ratelimit structure is small, so this
1314 data structure likely does not need to be large.
1315
1316 ip-ratelimit-slabs: <number>
1317 Give power of 2 number of slabs, this is used to reduce lock con‐
1318 tention in the ip ratelimit tracking data structure. Close to the
1319 number of cpus is a fairly good setting.
1320
1321 ip-ratelimit-factor: <number>
1322 Set the amount of queries to rate limit when the limit is
1323 exceeded. If set to 0, all queries are dropped for addresses
1324 where the limit is exceeded. If set to another value, 1 in that
1325 number is allowed through to complete. Default is 10, allowing
1326 1/10 traffic to flow normally. This can make ordinary queries
1327 complete (if repeatedly queried for), and enter the cache, whilst
1328 also mitigating the traffic flow by the factor given.
1329
1330 Remote Control Options
1331 In the remote-control: clause are the declarations for the remote con‐
1332 trol facility. If this is enabled, the unbound-control(8) utility can
1333 be used to send commands to the running unbound server. The server
1334 uses these clauses to setup SSLv3 / TLSv1 security for the connection.
1335 The unbound-control(8) utility also reads the remote-control section
1336 for options. To setup the correct self-signed certificates use the
1337 unbound-control-setup(8) utility.
1338
1339 control-enable: <yes or no>
1340 The option is used to enable remote control, default is "no". If
1341 turned off, the server does not listen for control commands.
1342
1343 control-interface: <ip address or path>
1344 Give IPv4 or IPv6 addresses or local socket path to listen on for
1345 control commands. By default localhost (127.0.0.1 and ::1) is
1346 listened to. Use 0.0.0.0 and ::0 to listen to all interfaces. If
1347 you change this and permissions have been dropped, you must
1348 restart the server for the change to take effect.
1349
1350 control-port: <port number>
1351 The port number to listen on for IPv4 or IPv6 control interfaces,
1352 default is 8953. If you change this and permissions have been
1353 dropped, you must restart the server for the change to take
1354 effect.
1355
1356 control-use-cert: <yes or no>
1357 Whether to require certificate authentication of control connec‐
1358 tions. The default is "yes". This should not be changed unless
1359 there are other mechanisms in place to prevent untrusted users
1360 from accessing the remote control interface.
1361
1362 server-key-file: <private key file>
1363 Path to the server private key, by default unbound_server.key.
1364 This file is generated by the unbound-control-setup utility. This
1365 file is used by the unbound server, but not by unbound-control.
1366
1367 server-cert-file: <certificate file.pem>
1368 Path to the server self signed certificate, by default
1369 unbound_server.pem. This file is generated by the unbound-con‐
1370 trol-setup utility. This file is used by the unbound server, and
1371 also by unbound-control.
1372
1373 control-key-file: <private key file>
1374 Path to the control client private key, by default unbound_con‐
1375 trol.key. This file is generated by the unbound-control-setup
1376 utility. This file is used by unbound-control.
1377
1378 control-cert-file: <certificate file.pem>
1379 Path to the control client certificate, by default unbound_con‐
1380 trol.pem. This certificate has to be signed with the server cer‐
1381 tificate. This file is generated by the unbound-control-setup
1382 utility. This file is used by unbound-control.
1383
1384 Stub Zone Options
1385 There may be multiple stub-zone: clauses. Each with a name: and zero or
1386 more hostnames or IP addresses. For the stub zone this list of name‐
1387 servers is used. Class IN is assumed. The servers should be authority
1388 servers, not recursors; unbound performs the recursive processing
1389 itself for stub zones.
1390
1391 The stub zone can be used to configure authoritative data to be used by
1392 the resolver that cannot be accessed using the public internet servers.
1393 This is useful for company-local data or private zones. Setup an
1394 authoritative server on a different host (or different port). Enter a
1395 config entry for unbound with stub-addr: <ip address of host[@port]>.
1396 The unbound resolver can then access the data, without referring to the
1397 public internet for it.
1398
1399 This setup allows DNSSEC signed zones to be served by that authorita‐
1400 tive server, in which case a trusted key entry with the public key can
1401 be put in config, so that unbound can validate the data and set the AD
1402 bit on replies for the private zone (authoritative servers do not set
1403 the AD bit). This setup makes unbound capable of answering queries for
1404 the private zone, and can even set the AD bit ('authentic'), but the AA
1405 ('authoritative') bit is not set on these replies.
1406
1407 Consider adding server: statements for domain-insecure: and for
1408 local-zone: name nodefault for the zone if it is a locally served zone.
1409 The insecure clause stops DNSSEC from invalidating the zone. The local
1410 zone nodefault (or transparent) clause makes the (reverse-) zone bypass
1411 unbound's filtering of RFC1918 zones.
1412
1413 name: <domain name>
1414 Name of the stub zone.
1415
1416 stub-host: <domain name>
1417 Name of stub zone nameserver. Is itself resolved before it is
1418 used.
1419
1420 stub-addr: <IP address>
1421 IP address of stub zone nameserver. Can be IP 4 or IP 6. To use
1422 a nondefault port for DNS communication append '@' with the port
1423 number.
1424
1425 stub-prime: <yes or no>
1426 This option is by default off. If enabled it performs NS set
1427 priming, which is similar to root hints, where it starts using
1428 the list of nameservers currently published by the zone. Thus,
1429 if the hint list is slightly outdated, the resolver picks up a
1430 correct list online.
1431
1432 stub-first: <yes or no>
1433 If enabled, a query is attempted without the stub clause if it
1434 fails. The data could not be retrieved and would have caused
1435 SERVFAIL because the servers are unreachable, instead it is
1436 tried without this clause. The default is no.
1437
1438 stub-ssl-upstream: <yes or no>
1439 Enabled or disable whether the queries to this stub use SSL for
1440 transport. Default is no.
1441
1442 Forward Zone Options
1443 There may be multiple forward-zone: clauses. Each with a name: and zero
1444 or more hostnames or IP addresses. For the forward zone this list of
1445 nameservers is used to forward the queries to. The servers listed as
1446 forward-host: and forward-addr: have to handle further recursion for
1447 the query. Thus, those servers are not authority servers, but are
1448 (just like unbound is) recursive servers too; unbound does not perform
1449 recursion itself for the forward zone, it lets the remote server do it.
1450 Class IN is assumed. A forward-zone entry with name "." and a for‐
1451 ward-addr target will forward all queries to that other server (unless
1452 it can answer from the cache).
1453
1454 name: <domain name>
1455 Name of the forward zone.
1456
1457 forward-host: <domain name>
1458 Name of server to forward to. Is itself resolved before it is
1459 used.
1460
1461 forward-addr: <IP address>
1462 IP address of server to forward to. Can be IP 4 or IP 6. To use
1463 a nondefault port for DNS communication append '@' with the port
1464 number.
1465
1466 forward-first: <yes or no>
1467 If enabled, a query is attempted without the forward clause if
1468 it fails. The data could not be retrieved and would have caused
1469 SERVFAIL because the servers are unreachable, instead it is
1470 tried without this clause. The default is no.
1471
1472 forward-ssl-upstream: <yes or no>
1473 Enabled or disable whether the queries to this forwarder use SSL
1474 for transport. Default is no.
1475
1476 View Options
1477 There may be multiple view: clauses. Each with a name: and zero or more
1478 local-zone and local-data elements. View can be mapped to requests by
1479 specifying the view name in an access-control-view element. Options
1480 from matching views will override global options. Global options will
1481 be used if no matching view is found, or when the matching view does
1482 not have the option specified.
1483
1484 name: <view name>
1485 Name of the view. Must be unique. This name is used in
1486 access-control-view elements.
1487
1488 local-zone: <zone> <type>
1489 View specific local-zone elements. Has the same types and behav‐
1490 iour as the global local-zone elements. When there is at least
1491 one local-zone specified and view-first is no, the default
1492 local-zones will be added to this view. Defaults can be dis‐
1493 abled using the nodefault type. When view-first is yes or when a
1494 view does not have a local-zone, the global local-zone will be
1495 used including it's default zones.
1496
1497 local-data: "<resource record string>"
1498 View specific local-data elements. Has the same behaviour as the
1499 global local-data elements.
1500
1501 local-data-ptr: "IPaddr name"
1502 View specific local-data-ptr elements. Has the same behaviour as
1503 the global local-data-ptr elements.
1504
1505 view-first: <yes or no>
1506 If enabled, it attempts to use the global local-zone and
1507 local-data if there is no match in the view specific options.
1508 The default is no.
1509
1510 Python Module Options
1511 The python: clause gives the settings for the python(1) script module.
1512 This module acts like the iterator and validator modules do, on queries
1513 and answers. To enable the script module it has to be compiled into
1514 the daemon, and the word "python" has to be put in the module-config:
1515 option (usually first, or between the validator and iterator).
1516
1517 If the chroot: option is enabled, you should make sure Python's library
1518 directory structure is bind mounted in the new root environment, see
1519 mount(8). Also the python-script: path should be specified as an abso‐
1520 lute path relative to the new root, or as a relative path to the work‐
1521 ing directory.
1522
1523 python-script: <python file>
1524 The script file to load.
1525
1526 DNS64 Module Options
1527 The dns64 module must be configured in the module-config: "dns64 val‐
1528 idator iterator" directive and be compiled into the daemon to be
1529 enabled. These settings go in the server: section.
1530
1531 dns64-prefix: <IPv6 prefix>
1532 This sets the DNS64 prefix to use to synthesize AAAA records
1533 with. It must be /96 or shorter. The default prefix is
1534 64:ff9b::/96.
1535
1536 dns64-synthall: <yes or no>
1537 Debug option, default no. If enabled, synthesize all AAAA
1538 records despite the presence of actual AAAA records.
1539
1540 DNSCrypt Options
1541 The dnscrypt: clause gives the settings of the dnscrypt channel. While
1542 those options are available, they are only meaningful if unbound was
1543 compiled with --enable-dnscrypt. Currently certificate and secret/pub‐
1544 lic keys cannot be generated by unbound. You can use dnscrypt-wrapper
1545 to generate those: https://github.com/cofyc/dnscrypt-wrapper/blob/mas‐
1546 ter/README.md#usage
1547
1548 dnscrypt-enable: <yes or no>
1549 Whether or not the dnscrypt config should be enabled. You may
1550 define configuration but not activate it. The default is no.
1551
1552 dnscrypt-port: <port number>
1553 On which port should dnscrypt should be activated. Note that you
1554 should have a matching interface option defined in the server
1555 section for this port.
1556
1557 dnscrypt-provider: <provider name>
1558 The provider name to use to distribute certificates. This is of
1559 the form: 2.dnscrypt-cert.example.com.. The name MUST end with a
1560 dot.
1561
1562 dnscrypt-secret-key: <path to secret key file>
1563 Path to the time limited secret key file. This option may be
1564 specified multiple times.
1565
1566 dnscrypt-provider-cert: <path to cert file>
1567 Path to the certificate related to the dnscrypt-secret-keys.
1568 This option may be specified multiple times.
1569
1570 dnscrypt-shared-secret-cache-size: <memory size>
1571 Give the size of the data structure in which the shared secret
1572 keys are kept in. Default 4m. In bytes or use m(mega),
1573 k(kilo), g(giga). The shared secret cache is used when a same
1574 client is making multiple queries using the same public key. It
1575 saves a substantial amount of CPU.
1576
1577 dnscrypt-shared-secret-cache-slabs: <number>
1578 Give power of 2 number of slabs, this is used to reduce lock
1579 contention in the dnscrypt shared secrets cache. Close to the
1580 number of cpus is a fairly good setting.
1581
1582 EDNS Client Subnet Module Options
1583 The ECS module must be configured in the module-config: "subnetcache
1584 validator iterator" directive and be compiled into the daemon to be
1585 enabled. These settings go in the server: section.
1586
1587 If the destination address is whitelisted with Unbound will add the
1588 EDNS0 option to the query containing the relevant part of the client's
1589 address. When an answer contains the ECS option the response and the
1590 option are placed in a specialized cache. If the authority indicated no
1591 support, the response is stored in the regular cache.
1592
1593 Additionally, when a client includes the option in its queries, Unbound
1594 will forward the option to the authority if prensent in the whitelist,
1595 or client-subnet-always-forward is set to yes. In this case the lookup
1596 in the regular cache is skipped.
1597
1598 The maximum size of the ECS cache is controlled by 'msg-cache-size' in
1599 the configuration file. On top of that, for each query only 100 differ‐
1600 ent subnets are allowed to be stored for each address family. Exceeding
1601 that number, older entries will be purged from cache.
1602
1603 send-client-subnet: <IP address>
1604 Send client source address to this authority. Append /num to
1605 indicate a classless delegation netblock, for example like
1606 10.2.3.4/24 or 2001::11/64. Can be given multiple times. Author‐
1607 ities not listed will not receive edns-subnet information,
1608 unless domain in query is specified in client-subnet-zone.
1609
1610 client-subnet-zone: <domain>
1611 Send client source address in queries for this domain and its
1612 subdomains. Can be given multiple times. Zones not listed will
1613 not receive edns-subnet information, unless hosted by authority
1614 specified in send-client-subnet.
1615
1616 client-subnet-always-forward: <yes or no>
1617 Specify whether the ECS whitelist check (configured using
1618 send-client-subnet) is applied for all queries, even if the
1619 triggering query contains an ECS record, or only for queries for
1620 which the ECS record is generated using the querier address (and
1621 therefore did not contain ECS data in the client query). If
1622 enabled, the whitelist check is skipped when the client query
1623 contains an ECS record. Default is no.
1624
1625 max-client-subnet-ipv6: <number>
1626 Specifies the maximum prefix length of the client source address
1627 we are willing to expose to third parties for IPv6. Defaults to
1628 56.
1629
1630 max-client-subnet-ipv4: <number>
1631 Specifies the maximum prefix length of the client source address
1632 we are willing to expose to third parties for IPv4. Defaults to
1633 24.
1634
1635 Opportunistic IPsec Support Module Options
1636 The IPsec module must be configured in the module-config: "ipsecmod
1637 validator iterator" directive and be compiled into the daemon to be
1638 enabled. These settings go in the server: section.
1639
1640 When unbound receives an A/AAAA query that is not in the cache and
1641 finds a valid answer, it will withhold returning the answer and instead
1642 will generate an IPSECKEY subquery for the same domain name. If an
1643 answer was found, unbound will call an external hook passing the fol‐
1644 lowing arguments:
1645
1646 QNAME
1647 Domain name of the A/AAAA and IPSECKEY query. In string for‐
1648 mat.
1649
1650 IPSECKEY TTL
1651 TTL of the IPSECKEY RRset.
1652
1653 A/AAAA
1654 String of space separated IP addresses present in the A/AAAA
1655 RRset. The IP addresses are in string format.
1656
1657 IPSECKEY
1658 String of space separated IPSECKEY RDATA present in the
1659 IPSECKEY RRset. The IPSECKEY RDATA are in DNS presentation
1660 format.
1661
1662 The A/AAAA answer is then cached and returned to the client. If the
1663 external hook was called the TTL changes to ensure it doesn't surpass
1664 ipsecmod-max-ttl.
1665
1666 The same procedure is also followed when prefetch: is used, but the
1667 A/AAAA answer is given to the client before the hook is called. ipsec‐
1668 mod-max-ttl ensures that the A/AAAA answer given from cache is still
1669 relevant for opportunistic IPsec.
1670
1671 ipsecmod-enabled: <yes or no>
1672 Specifies whether the IPsec module is enabled or not. The IPsec
1673 module still needs to be defined in the module-config: direc‐
1674 tive. This option facilitates turning on/off the module without
1675 restarting/reloading unbound. Defaults to yes.
1676
1677 ipsecmod-hook: <filename>
1678 Specifies the external hook that unbound will call with sys‐
1679 tem(3). The file can be specified as an absolute/relative path.
1680 The file needs the proper permissions to be able to be executed
1681 by the same user that runs unbound. It must be present when the
1682 IPsec module is defined in the module-config: directive.
1683
1684 ipsecmod-strict: <yes or no>
1685 If enabled unbound requires the external hook to return a suc‐
1686 cess value of 0. Failing to do so unbound will reply with SERV‐
1687 FAIL. The A/AAAA answer will also not be cached. Defaults to
1688 no.
1689
1690 ipsecmod-max-ttl: <seconds>
1691 Time to live maximum for A/AAAA cached records after calling the
1692 external hook. Defaults to 3600.
1693
1694 ipsecmod-ignore-bogus: <yes or no>
1695 Specifies the behaviour of unbound when the IPSECKEY answer is
1696 bogus. If set to yes, the hook will be called and the A/AAAA
1697 answer will be returned to the client. If set to no, the hook
1698 will not be called and the answer to the A/AAAA query will be
1699 SERVFAIL. Mainly used for testing. Defaults to no.
1700
1701 ipsecmod-whitelist: <domain>
1702 Whitelist the domain so that the module logic will be executed.
1703 Can be given multiple times, for different domains. If the
1704 option is not specified, all domains are treated as being
1705 whitelisted (default).
1706
1707 Cache DB Module Options
1708 The Cache DB module must be configured in the module-config: "validator
1709 cachedb iterator" directive and be compiled into the daemon with
1710 --enable-cachedb. If this module is enabled and configured, the speci‐
1711 fied backend database works as a second level cache: When Unbound can‐
1712 not find an answer to a query in its built-in in-memory cache, it con‐
1713 sults the specified backend. If it finds a valid answer in the back‐
1714 end, Unbound uses it to respond to the query without performing itera‐
1715 tive DNS resolution. If Unbound cannot even find an answer in the
1716 backend, it resolves the query as usual, and stores the answer in the
1717 backend. The cachedb: clause gives custom settings of the cache DB
1718 module.
1719
1720 backend: <backend name>
1721 Specify the backend database name. Currently, only the in-mem‐
1722 ory "testframe" backend is supported. As the name suggests this
1723 backend is not of any practical use. This option defaults to
1724 "testframe".
1725
1726 secret-seed: <"secret string">
1727 Specify a seed to calculate a hash value from query information.
1728 This value will be used as the key of the corresponding answer
1729 for the backend database and can be customized if the hash
1730 should not be predictable operationally. If the backend data‐
1731 base is shared by multiple Unbound instances, all instances must
1732 use the same secret seed. This option defaults to "default".
1733
1735 In the example config settings below memory usage is reduced. Some ser‐
1736 vice levels are lower, notable very large data and a high TCP load are
1737 no longer supported. Very large data and high TCP loads are exceptional
1738 for the DNS. DNSSEC validation is enabled, just add trust anchors. If
1739 you do not have to worry about programs using more than 3 Mb of memory,
1740 the below example is not for you. Use the defaults to receive full ser‐
1741 vice, which on BSD-32bit tops out at 30-40 Mb after heavy usage.
1742
1743 # example settings that reduce memory usage
1744 server:
1745 num-threads: 1
1746 outgoing-num-tcp: 1 # this limits TCP service, uses less buffers.
1747 incoming-num-tcp: 1
1748 outgoing-range: 60 # uses less memory, but less performance.
1749 msg-buffer-size: 8192 # note this limits service, 'no huge stuff'.
1750 msg-cache-size: 100k
1751 msg-cache-slabs: 1
1752 rrset-cache-size: 100k
1753 rrset-cache-slabs: 1
1754 infra-cache-numhosts: 200
1755 infra-cache-slabs: 1
1756 key-cache-size: 100k
1757 key-cache-slabs: 1
1758 neg-cache-size: 10k
1759 num-queries-per-thread: 30
1760 target-fetch-policy: "2 1 0 0 0 0"
1761 harden-large-queries: "yes"
1762 harden-short-bufsize: "yes"
1763
1765 /etc/unbound
1766 default unbound working directory.
1767
1768 /etc/unbound
1769 default chroot(2) location.
1770
1771 /etc/unbound/unbound.conf
1772 unbound configuration file.
1773
1774 /var/run/unbound/unbound.pid
1775 default unbound pidfile with process ID of the running daemon.
1776
1777 unbound.log
1778 unbound log file. default is to log to syslog(3).
1779
1781 unbound(8), unbound-checkconf(8).
1782
1784 Unbound was written by NLnet Labs. Please see CREDITS file in the dis‐
1785 tribution for further details.
1786
1787
1788
1789NLnet Labs Sep 18, 2017 unbound.conf(5)