1unbound.conf(5) unbound 1.4.13 unbound.conf(5)
2
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 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 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 $ unbound -c /etc/unbound/unbound.conf
27 Most settings are the defaults. Stop the server with:
29 $ kill `cat /etc/unbound/unbound.pid`
31 Below is a minimal config file. The source distribution contains an
33 extensive example.conf file with all the options.
34 # 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 Files can be included using the include: directive. It can appear any‐
59 where, and takes a single filename as an argument. Processing contin‐
60 ues as if the text from the included file was copied into the config
61 file at that point. If also using chroot, using full path names for
62 the included files works, relative pathnames for the included names
63 work if the directory where the daemon is started equals its
64 chroot/working directory.
65 Server Options
67 These options are part of the server: clause.
68 verbosity: <number>
70 The verbosity number, level 0 means no verbosity, only errors.
71 Level 1 gives operational information. Level 2 gives detailed
72 operational information. Level 3 gives query level information,
73 output per query. Level 4 gives algorithm level information.
74 Level 5 logs client identification for cache misses. Default is
75 level 1. The verbosity can also be increased from the command‐
76 line, see unbound(8).
77 statistics-interval: <seconds>
79 The number of seconds between printing statistics to the log for
80 every thread. Disable with value 0 or "". Default is disabled.
81 The histogram statistics are only printed if replies were sent
82 during the statistics interval, requestlist statistics are
83 printed for every interval (but can be 0). This is because the
84 median calculation requires data to be present.
85 statistics-cumulative: <yes or no>
87 If enabled, statistics are cumulative since starting unbound,
88 without clearing the statistics counters after logging the sta‐
89 tistics. Default is no.
90 extended-statistics: <yes or no>
92 If enabled, extended statistics are printed from unbound-con‐
93 trol(8). Default is off, because keeping track of more statis‐
94 tics takes time. The counters are listed in unbound-control(8).
95 num-threads: <number>
97 The number of threads to create to serve clients. Use 1 for no
98 threading.
99 port: <port number>
101 The port number, default 53, on which the server responds to
102 queries.
103 interface: <ip address[@port]>
105 Interface to use to connect to the network. This interface is
106 listened to for queries from clients, and answers to clients are
107 given from it. Can be given multiple times to work on several
108 interfaces. If none are given the default is to listen to local‐
109 host. The interfaces are not changed on a reload (kill -HUP)
110 but only on restart. A port number can be specified with @port
111 (without spaces between interface and port number), if not spec‐
112 ified the default port (from port) is used.
113 interface-automatic: <yes or no>
115 Detect source interface on UDP queries and copy them to replies.
116 This feature is experimental, and needs support in your OS for
117 particular socket options. Default value is no.
118 outgoing-interface: <ip address>
120 Interface to use to connect to the network. This interface is
121 used to send queries to authoritative servers and receive their
122 replies. Can be given multiple times to work on several inter‐
123 faces. If none are given the default (all) is used. You can
124 specify the same interfaces in interface: and outgoing-inter‐
125 face: lines, the interfaces are then used for both purposes.
126 Outgoing queries are sent via a random outgoing interface to
127 counter spoofing.
128 outgoing-range: <number>
130 Number of ports to open. This number of file descriptors can be
131 opened per thread. Must be at least 1. Default depends on com‐
132 pile options. Larger numbers need extra resources from the oper‐
133 ating system. For performance a a very large value is best, use
134 libevent to make this possible.
135 outgoing-port-permit: <port number or range>
137 Permit unbound to open this port or range of ports for use to
138 send queries. A larger number of permitted outgoing ports
139 increases resilience against spoofing attempts. Make sure these
140 ports are not needed by other daemons. By default only ports
141 above 1024 that have not been assigned by IANA are used. Give a
142 port number or a range of the form "low-high", without spaces.
143 The outgoing-port-permit and outgoing-port-avoid statements are
145 processed in the line order of the config file, adding the per‐
146 mitted ports and subtracting the avoided ports from the set of
147 allowed ports. The processing starts with the non IANA allo‐
148 cated ports above 1024 in the set of allowed ports.
149 outgoing-port-avoid: <port number or range>
151 Do not permit unbound to open this port or range of ports for
152 use to send queries. Use this to make sure unbound does not grab
153 a port that another daemon needs. The port is avoided on all
154 outgoing interfaces, both IP4 and IP6. By default only ports
155 above 1024 that have not been assigned by IANA are used. Give a
156 port number or a range of the form "low-high", without spaces.
157 outgoing-num-tcp: <number>
159 Number of outgoing TCP buffers to allocate per thread. Default
160 is 10. If set to 0, or if do_tcp is "no", no TCP queries to
161 authoritative servers are done.
162 incoming-num-tcp: <number>
164 Number of incoming TCP buffers to allocate per thread. Default
165 is 10. If set to 0, or if do_tcp is "no", no TCP queries from
166 clients are accepted.
167 edns-buffer-size: <number>
169 Number of bytes size to advertise as the EDNS reassembly buffer
170 size. This is the value put into datagrams over UDP towards
171 peers. The actual buffer size is determined by msg-buffer-size
172 (both for TCP and UDP). Do not set lower than that value.
173 Default is 4096 which is RFC recommended. If you have fragmen‐
174 tation reassembly problems, usually seen as timeouts, then a
175 value of 1480 can fix it. Setting to 512 bypasses even the most
176 stringent path MTU problems, but is seen as extreme, since the
177 amount of TCP fallback generated is excessive (probably also for
178 this resolver, consider tuning the outgoing tcp number).
179 msg-buffer-size: <number>
181 Number of bytes size of the message buffers. Default is 65552
182 bytes, enough for 64 Kb packets, the maximum DNS message size.
183 No message larger than this can be sent or received. Can be
184 reduced to use less memory, but some requests for DNS data, such
185 as for huge resource records, will result in a SERVFAIL reply to
186 the client.
187 msg-cache-size: <number>
189 Number of bytes size of the message cache. Default is 4
190 megabytes. A plain number is in bytes, append 'k', 'm' or 'g'
191 for kilobytes, megabytes or gigabytes (1024*1024 bytes in a
192 megabyte).
193 msg-cache-slabs: <number>
195 Number of slabs in the message cache. Slabs reduce lock con‐
196 tention by threads. Must be set to a power of 2. Setting
197 (close) to the number of cpus is a reasonable guess.
198 num-queries-per-thread: <number>
200 The number of queries that every thread will service simultane‐
201 ously. If more queries arrive that need servicing, and no
202 queries can be jostled out (see jostle-timeout), then the
203 queries are dropped. This forces the client to resend after a
204 timeout; allowing the server time to work on the existing
205 queries. Default depends on compile options, 512 or 1024.
206 jostle-timeout: <msec>
208 Timeout used when the server is very busy. Set to a value that
209 usually results in one roundtrip to the authority servers. If
210 too many queries arrive, then 50% of the queries are allowed to
211 run to completion, and the other 50% are replaced with the new
212 incoming query if they have already spent more than their
213 allowed time. This protects against denial of service by slow
214 queries or high query rates. Default 200 milliseconds. The
215 effect is that the qps for long-lasting queries is about (num‐
216 queriesperthread / 2) / (average time for such long queries)
217 qps. The qps for short queries can be about (numqueries‐
218 perthread / 2) / (jostletimeout in whole seconds) qps per
219 thread, about (1024/2)*5 = 2560 qps by default.
220 so-rcvbuf: <number>
222 If not 0, then set the SO_RCVBUF socket option to get more buf‐
223 fer space on UDP port 53 incoming queries. So that short spikes
224 on busy servers do not drop packets (see counter in netstat
225 -su). Default is 0 (use system value). Otherwise, the number
226 of bytes to ask for, try "4m" on a busy server. The OS caps it
227 at a maximum, on linux unbound needs root permission to bypass
228 the limit, or the admin can use sysctl net.core.rmem_max. On
229 BSD change kern.ipc.maxsockbuf in /etc/sysctl.conf. On OpenBSD
230 change header and recompile kernel. On Solaris ndd -set /dev/udp
231 udp_max_buf 8388608.
232 so-sndbuf: <number>
234 If not 0, then set the SO_SNDBUF socket option to get more buf‐
235 fer space on UDP port 53 outgoing queries. This for very busy
236 servers handles spikes in answer traffic, otherwise 'send:
237 resource temporarily unavailable' can get logged, the buffer
238 overrun is also visible by netstat -su. Default is 0 (use sys‐
239 tem value). Specify the number of bytes to ask for, try "4m" on
240 a very busy server. The OS caps it at a maximum, on linux
241 unbound needs root permission to bypass the limit, or the admin
242 can use sysctl net.core.wmem_max. On BSD, Solaris changes are
243 similar to so-rcvbuf.
244 rrset-cache-size: <number>
246 Number of bytes size of the RRset cache. Default is 4 megabytes.
247 A plain number is in bytes, append 'k', 'm' or 'g' for kilo‐
248 bytes, megabytes or gigabytes (1024*1024 bytes in a megabyte).
249 rrset-cache-slabs: <number>
251 Number of slabs in the RRset cache. Slabs reduce lock contention
252 by threads. Must be set to a power of 2.
253 cache-max-ttl: <seconds>
255 Time to live maximum for RRsets and messages in the cache.
256 Default is 86400 seconds (1 day). If the maximum kicks in,
257 responses to clients still get decrementing TTLs based on the
258 original (larger) values. When the internal TTL expires, the
259 cache item has expired. Can be set lower to force the resolver
260 to query for data often, and not trust (very large) TTL values.
261 cache-min-ttl: <seconds>
263 Time to live minimum for RRsets and messages in the cache.
264 Default is 0. If the the minimum kicks in, the data is cached
265 for longer than the domain owner intended, and thus less queries
266 are made to look up the data. Zero makes sure the data in the
267 cache is as the domain owner intended, higher values, especially
268 more than an hour or so, can lead to trouble as the data in the
269 cache does not match up with the actual data any more.
270 infra-host-ttl: <seconds>
272 Time to live for entries in the host cache. The host cache con‐
273 tains roundtrip timing and EDNS support information. Default is
274 900.
275 infra-lame-ttl: <seconds>
277 The time to live when a delegation is discovered to be lame.
278 Default is 900.
279 infra-cache-slabs: <number>
281 Number of slabs in the infrastructure cache. Slabs reduce lock
282 contention by threads. Must be set to a power of 2.
283 infra-cache-numhosts: <number>
285 Number of hosts for which information is cached. Default is
286 10000.
287 infra-cache-lame-size: <number>
289 Number of bytes that the lameness cache per host is allowed to
290 use. Default is 10 kb, which gives maximum storage for a couple
291 score zones, depending on the lame zone name lengths.
292 do-ip4: <yes or no>
294 Enable or disable whether ip4 queries are answered or issued.
295 Default is yes.
296 do-ip6: <yes or no>
298 Enable or disable whether ip6 queries are answered or issued.
299 Default is yes. If disabled, queries are not answered on IPv6,
300 and queries are not sent on IPv6 to the internet nameservers.
301 do-udp: <yes or no>
303 Enable or disable whether UDP queries are answered or issued.
304 Default is yes.
305 do-tcp: <yes or no>
307 Enable or disable whether TCP queries are answered or issued.
308 Default is yes.
309 tcp-upstream: <yes or no>
311 Enable or disable whether the upstream queries use TCP only for
312 transport. Default is no. Useful in tunneling scenarios.
313 do-daemonize: <yes or no>
315 Enable or disable whether the unbound server forks into the
316 background as a daemon. Default is yes.
317 access-control: <IP netblock> <action>
319 The netblock is given as an IP4 or IP6 address with /size
320 appended for a classless network block. The action can be deny,
321 refuse, allow or allow_snoop.
322 The action deny stops queries from hosts from that netblock.
324 The action refuse stops queries too, but sends a DNS rcode
326 REFUSED error message back.
327 The action allow gives access to clients from that netblock. It
329 gives only access for recursion clients (which is what almost
330 all clients need). Nonrecursive queries are refused.
331 The allow action does allow nonrecursive queries to access the
333 local-data that is configured. The reason is that this does not
334 involve the unbound server recursive lookup algorithm, and
335 static data is served in the reply. This supports normal opera‐
336 tions where nonrecursive queries are made for the authoritative
337 data. For nonrecursive queries any replies from the dynamic
338 cache are refused.
339 The action allow_snoop gives nonrecursive access too. This give
341 both recursive and non recursive access. The name allow_snoop
342 refers to cache snooping, a technique to use nonrecursive
343 queries to examine the cache contents (for malicious acts).
344 However, nonrecursive queries can also be a valuable debugging
345 tool (when you want to examine the cache contents). In that case
346 use allow_snoop for your administration host.
347 By default only localhost is allowed, the rest is refused. The
349 default is refused, because that is protocol-friendly. The DNS
350 protocol is not designed to handle dropped packets due to pol‐
351 icy, and dropping may result in (possibly excessive) retried
352 queries.
353 chroot: <directory>
355 If chroot is enabled, you should pass the configfile (from the
356 commandline) as a full path from the original root. After the
357 chroot has been performed the now defunct portion of the config
358 file path is removed to be able to reread the config after a
359 reload.
360 All other file paths (working dir, logfile, roothints, and key
362 files) can be specified in several ways: as an absolute path
363 relative to the new root, as a relative path to the working
364 directory, or as an absolute path relative to the original root.
365 In the last case the path is adjusted to remove the unused por‐
366 tion.
367 The pidfile can be either a relative path to the working direc‐
369 tory, or an absolute path relative to the original root. It is
370 written just prior to chroot and dropping permissions. This
371 allows the pidfile to be /var/run/unbound.pid and the chroot to
372 be /var/unbound, for example.
373 Additionally, unbound may need to access /dev/random (for
375 entropy) from inside the chroot.
376 If given a chroot is done to the given directory. The default is
378 "/etc/unbound". If you give "" no chroot is performed.
379 username: <name>
381 If given, after binding the port the user privileges are
382 dropped. Default is "unbound". If you give username: "" no user
383 change is performed.
384 If this user is not capable of binding the port, reloads (by
386 signal HUP) will still retain the opened ports. If you change
387 the port number in the config file, and that new port number
388 requires privileges, then a reload will fail; a restart is
389 needed.
390 directory: <directory>
392 Sets the working directory for the program. Default is
393 "/etc/unbound".
394 logfile: <filename>
396 If "" is given, logging goes to stderr, or nowhere once daemo‐
397 nized. The logfile is appended to, in the following format:
398 [seconds since 1970] unbound[pid:tid]: type: message.
399 If this option is given, the use-syslog is option is set to
400 "no". The logfile is reopened (for append) when the config file
401 is reread, on SIGHUP.
402 use-syslog: <yes or no>
404 Sets unbound to send log messages to the syslogd, using sys‐
405 log(3). The log facility LOG_DAEMON is used, with identity
406 "unbound". The logfile setting is overridden when use-syslog is
407 turned on. The default is to log to syslog.
408 log-time-ascii: <yes or no>
410 Sets logfile lines to use a timestamp in UTC ascii. Default is
411 no, which prints the seconds since 1970 in brackets. No effect
412 if using syslog, in that case syslog formats the timestamp
413 printed into the log files.
414 log-queries: <yes or no>
416 Prints one line per query to the log, with the log timestamp and
417 IP address, name, type and class. Default is no. Note that it
418 takes time to print these lines which makes the server (signifi‐
419 cantly) slower. Odd (nonprintable) characters in names are
420 printed as '?'.
421 pidfile: <filename>
423 The process id is written to the file. Default is
424 "/var/run/unbound/unbound.pid". So,
425 kill -HUP `cat /var/run/unbound/unbound.pid`
426 triggers a reload,
427 kill -QUIT `cat /var/run/unbound/unbound.pid`
428 gracefully terminates.
429 root-hints: <filename>
431 Read the root hints from this file. Default is nothing, using
432 builtin hints for the IN class. The file has the format of zone
433 files, with root nameserver names and addresses only. The
434 default may become outdated, when servers change, therefore it
435 is good practice to use a root-hints file.
436 hide-identity: <yes or no>
438 If enabled id.server and hostname.bind queries are refused.
439 identity: <string>
441 Set the identity to report. If set to "", the default, then the
442 hostname of the server is returned.
443 hide-version: <yes or no>
445 If enabled version.server and version.bind queries are refused.
446 version: <string>
448 Set the version to report. If set to "", the default, then the
449 package version is returned.
450 target-fetch-policy: <"list of numbers">
452 Set the target fetch policy used by unbound to determine if it
453 should fetch nameserver target addresses opportunistically. The
454 policy is described per dependency depth.
455 The number of values determines the maximum dependency depth
457 that unbound will pursue in answering a query. A value of -1
458 means to fetch all targets opportunistically for that dependency
459 depth. A value of 0 means to fetch on demand only. A positive
460 value fetches that many targets opportunistically.
461 Enclose the list between quotes ("") and put spaces between num‐
463 bers. The default is "3 2 1 0 0". Setting all zeroes, "0 0 0 0
464 0" gives behaviour closer to that of BIND 9, while setting "-1
465 -1 -1 -1 -1" gives behaviour rumoured to be closer to that of
466 BIND 8.
467 harden-short-bufsize: <yes or no>
469 Very small EDNS buffer sizes from queries are ignored. Default
470 is off, since it is legal protocol wise to send these, and
471 unbound tries to give very small answers to these queries, where
472 possible.
473 harden-large-queries: <yes or no>
475 Very large queries are ignored. Default is off, since it is
476 legal protocol wise to send these, and could be necessary for
477 operation if TSIG or EDNS payload is very large.
478 harden-glue: <yes or no>
480 Will trust glue only if it is within the servers authority.
481 Default is on.
482 harden-dnssec-stripped: <yes or no>
484 Require DNSSEC data for trust-anchored zones, if such data is
485 absent, the zone becomes bogus. If turned off, and no DNSSEC
486 data is received (or the DNSKEY data fails to validate), then
487 the zone is made insecure, this behaves like there is no trust
488 anchor. You could turn this off if you are sometimes behind an
489 intrusive firewall (of some sort) that removes DNSSEC data from
490 packets, or a zone changes from signed to unsigned to badly
491 signed often. If turned off you run the risk of a downgrade
492 attack that disables security for a zone. Default is on.
493 harden-below-nxdomain: <yes or no>
495 From draft-vixie-dnsext-resimprove, returns nxdomain to queries
496 for a name below another name that is already known to be nxdo‐
497 main. DNSSEC mandates noerror for empty nonterminals, hence
498 this is possible. Very old software might return nxdomain for
499 empty nonterminals (that usually happen for reverse IP address
500 lookups), and thus may be incompatible with this. To try to
501 avoid this only DNSSEC-secure nxdomains are used, because the
502 old software does not have DNSSEC. Default is off.
503 harden-referral-path: <yes or no>
505 Harden the referral path by performing additional queries for
506 infrastructure data. Validates the replies if trust anchors are
507 configured and the zones are signed. This enforces DNSSEC vali‐
508 dation on nameserver NS sets and the nameserver addresses that
509 are encountered on the referral path to the answer. Default
510 off, because it burdens the authority servers, and it is not RFC
511 standard, and could lead to performance problems because of the
512 extra query load that is generated. Experimental option. If
513 you enable it consider adding more numbers after the tar‐
514 get-fetch-policy to increase the max depth that is checked to.
515 use-caps-for-id: <yes or no>
517 Use 0x20-encoded random bits in the query to foil spoof
518 attempts. This perturbs the lowercase and uppercase of query
519 names sent to authority servers and checks if the reply still
520 has the correct casing. Disabled by default. This feature is
521 an experimental implementation of draft dns-0x20.
522 private-address: <IP address or subnet>
524 Give IPv4 of IPv6 addresses or classless subnets. These are
525 addresses on your private network, and are not allowed to be
526 returned for public internet names. Any occurence of such
527 addresses are removed from DNS answers. Additionally, the DNSSEC
528 validator may mark the answers bogus. This protects against
529 so-called DNS Rebinding, where a user browser is turned into a
530 network proxy, allowing remote access through the browser to
531 other parts of your private network. Some names can be allowed
532 to contain your private addresses, by default all the local-data
533 that you configured is allowed to, and you can specify addi‐
534 tional names using private-domain. No private addresses are
535 enabled by default. We consider to enable this for the RFC1918
536 private IP address space by default in later releases. That
537 would enable private addresses for 10.0.0.0/8 172.16.0.0/12
538 192.168.0.0/16 169.254.0.0/16 fd00::/8 and fe80::/10, since the
539 RFC standards say these addresses should not be visible on the
540 public internet. Turning on 127.0.0.0/8 would hinder many spam‐
541 blocklists as they use that.
542 private-domain: <domain name>
544 Allow this domain, and all its subdomains to contain private
545 addresses. Give multiple times to allow multiple domain names
546 to contain private addresses. Default is none.
547 unwanted-reply-threshold: <number>
549 If set, a total number of unwanted replies is kept track of in
550 every thread. When it reaches the threshold, a defensive action
551 is taken and a warning is printed to the log. The defensive
552 action is to clear the rrset and message caches, hopefully
553 flushing away any poison. A value of 10 million is suggested.
554 Default is 0 (turned off).
555 do-not-query-address: <IP address>
557 Do not query the given IP address. Can be IP4 or IP6. Append
558 /num to indicate a classless delegation netblock, for example
559 like 10.2.3.4/24 or 2001::11/64.
560 do-not-query-localhost: <yes or no>
562 If yes, localhost is added to the do-not-query-address entries,
563 both IP6 ::1 and IP4 127.0.0.1/8. If no, then localhost can be
564 used to send queries to. Default is yes.
565 prefetch: <yes or no>
567 If yes, message cache elements are prefetched before they expire
568 to keep the cache up to date. Default is no. Turning it on
569 gives about 10 percent more traffic and load on the machine, but
570 popular items do not expire from the cache.
571 prefetch-key: <yes or no>
573 If yes, fetch the DNSKEYs earlier in the validation process,
574 when a DS record is encountered. This lowers the latency of
575 requests. It does use a little more CPU. Also if the cache is
576 set to 0, it is no use. Default is no.
577 module-config: <"module names">
579 Module configuration, a list of module names separated by spa‐
580 ces, surround the string with quotes (""). The modules can be
581 validator, iterator. Setting this to "iterator" will result in
582 a non-validating server. Setting this to "validator iterator"
583 will turn on DNSSEC validation. The ordering of the modules is
584 important. You must also set trust-anchors for validation to be
585 useful.
586 trust-anchor-file: <filename>
588 File with trusted keys for validation. Both DS and DNSKEY
589 entries can appear in the file. The format of the file is the
590 standard DNS Zone file format. Default is "", or no trust
591 anchor file.
592 auto-trust-anchor-file: <filename>
594 File with trust anchor for one zone, which is tracked with
595 RFC5011 probes. The probes are several times per month, thus
596 the machine must be online frequently. The initial file can be
597 one with contents as described in trust-anchor-file. The file
598 is written to when the anchor is updated, so the unbound user
599 must have write permission.
600 trust-anchor: <"Resource Record">
602 A DS or DNSKEY RR for a key to use for validation. Multiple
603 entries can be given to specify multiple trusted keys, in addi‐
604 tion to the trust-anchor-files. The resource record is entered
605 in the same format as 'dig' or 'drill' prints them, the same
606 format as in the zone file. Has to be on a single line, with ""
607 around it. A TTL can be specified for ease of cut and paste, but
608 is ignored. A class can be specified, but class IN is default.
609 trusted-keys-file: <filename>
611 File with trusted keys for validation. Specify more than one
612 file with several entries, one file per entry. Like
613 trust-anchor-file but has a different file format. Format is
614 BIND-9 style format, the trusted-keys { name flag proto algo
615 "key"; }; clauses are read. It is possible to use wildcards
616 with this statement, the wildcard is expanded on start and on
617 reload.
618 dlv-anchor-file: <filename>
620 File with trusted keys for DLV (DNSSEC Lookaside Validation).
621 Both DS and DNSKEY entries can be used in the file, in the same
622 format as for trust-anchor-file: statements. Only one DLV can be
623 configured, more would be slow. The DLV configured is used as a
624 root trusted DLV, this means that it is a lookaside for the
625 root. Default is "", or no dlv anchor file.
626 dlv-anchor: <"Resource Record">
628 Much like trust-anchor, this is a DLV anchor with the DS or
629 DNSKEY inline.
630 domain-insecure: <domain name>
632 Sets domain name to be insecure, DNSSEC chain of trust is
633 ignored towards the domain name. So a trust anchor above the
634 domain name can not make the domain secure with a DS record,
635 such a DS record is then ignored. Also keys from DLV are
636 ignored for the domain. Can be given multiple times to specify
637 multiple domains that are treated as if unsigned. If you set
638 trust anchors for the domain they override this setting (and the
639 domain is secured).
640 This can be useful if you want to make sure a trust anchor for
642 external lookups does not affect an (unsigned) internal domain.
643 A DS record externally can create validation failures for that
644 internal domain.
645 val-override-date: <rrsig-style date spec>
647 Default is "" or "0", which disables this debugging feature. If
648 enabled by giving a RRSIG style date, that date is used for ver‐
649 ifying RRSIG inception and expiration dates, instead of the cur‐
650 rent date. Do not set this unless you are debugging signature
651 inception and expiration. The value -1 ignores the date alto‐
652 gether, useful for some special applications.
653 val-sig-skew-min: <seconds>
655 Minimum number of seconds of clock skew to apply to validated
656 signatures. A value of 10% of the signature lifetime (expira‐
657 tion - inception) is used, capped by this setting. Default is
658 3600 (1 hour) which allows for daylight savings differences.
659 Lower this value for more strict checking of short lived signa‐
660 tures.
661 val-sig-skew-max: <seconds>
663 Maximum number of seconds of clock skew to apply to validated
664 signatures. A value of 10% of the signature lifetime (expira‐
665 tion - inception) is used, capped by this setting. Default is
666 86400 (24 hours) which allows for timezone setting problems in
667 stable domains. Setting both min and max very low disables the
668 clock skew allowances. Setting both min and max very high makes
669 the validator check the signature timestamps less strictly.
670 val-bogus-ttl: <number>
672 The time to live for bogus data. This is data that has failed
673 validation; due to invalid signatures or other checks. The TTL
674 from that data cannot be trusted, and this value is used
675 instead. The value is in seconds, default 60. The time interval
676 prevents repeated revalidation of bogus data.
677 val-clean-additional: <yes or no>
679 Instruct the validator to remove data from the additional sec‐
680 tion of secure messages that are not signed properly. Messages
681 that are insecure, bogus, indeterminate or unchecked are not
682 affected. Default is yes. Use this setting to protect the users
683 that rely on this validator for authentication from protentially
684 bad data in the additional section.
685 val-log-level: <number>
687 Have the validator print validation failures to the log.
688 Regardless of the verbosity setting. Default is 0, off. At 1,
689 for every user query that fails a line is printed to the logs.
690 This way you can monitor what happens with validation. Use a
691 diagnosis tool, such as dig or drill, to find out why validation
692 is failing for these queries. At 2, not only the query that
693 failed is printed but also the reason why unbound thought it was
694 wrong and which server sent the faulty data.
695 val-permissive-mode: <yes or no>
697 Instruct the validator to mark bogus messages as indeterminate.
698 The security checks are performed, but if the result is bogus
699 (failed security), the reply is not withheld from the client
700 with SERVFAIL as usual. The client receives the bogus data. For
701 messages that are found to be secure the AD bit is set in
702 replies. Also logging is performed as for full validation. The
703 default value is "no".
704 ignore-cd-flag: <yes or no>
706 Instruct unbound to ignore the CD flag from clients and refuse
707 to return bogus answers to them. Thus, the CD (Checking Dis‐
708 abled) flag does not disable checking any more. This is useful
709 if legacy (w2008) servers that set the CD flag but cannot vali‐
710 date DNSSEC themselves are the clients, and then unbound pro‐
711 vides them with DNSSEC protection. The default value is "no".
712 val-nsec3-keysize-iterations: <"list of values">
714 List of keysize and iteration count values, separated by spaces,
715 surrounded by quotes. Default is "1024 150 2048 500 4096 2500".
716 This determines the maximum allowed NSEC3 iteration count before
717 a message is simply marked insecure instead of performing the
718 many hashing iterations. The list must be in ascending order and
719 have at least one entry. If you set it to "1024 65535" there is
720 no restriction to NSEC3 iteration values. This table must be
721 kept short; a very long list could cause slower operation.
722 add-holddown: <seconds>
724 Instruct the auto-trust-anchor-file probe mechanism for RFC5011
725 autotrust updates to add new trust anchors only after they have
726 been visible for this time. Default is 30 days as per the RFC.
727 del-holddown: <seconds>
729 Instruct the auto-trust-anchor-file probe mechanism for RFC5011
730 autotrust updates to remove revoked trust anchors after they
731 have been kept in the revoked list for this long. Default is 30
732 days as per the RFC.
733 keep-missing: <seconds>
735 Instruct the auto-trust-anchor-file probe mechanism for RFC5011
736 autotrust updates to remove missing trust anchors after they
737 have been unseen for this long. This cleans up the state file
738 if the target zone does not perform trust anchor revocation, so
739 this makes the auto probe mechanism work with zones that perform
740 regular (non-5011) rollovers. The default is 366 days. The
741 value 0 does not remove missing anchors, as per the RFC.
742 key-cache-size: <number>
744 Number of bytes size of the key cache. Default is 4 megabytes.
745 A plain number is in bytes, append 'k', 'm' or 'g' for kilo‐
746 bytes, megabytes or gigabytes (1024*1024 bytes in a megabyte).
747 key-cache-slabs: <number>
749 Number of slabs in the key cache. Slabs reduce lock contention
750 by threads. Must be set to a power of 2. Setting (close) to the
751 number of cpus is a reasonable guess.
752 neg-cache-size: <number>
754 Number of bytes size of the aggressive negative cache. Default
755 is 1 megabyte. A plain number is in bytes, append 'k', 'm' or
756 'g' for kilobytes, megabytes or gigabytes (1024*1024 bytes in a
757 megabyte).
758 local-zone: <zone> <type>
760 Configure a local zone. The type determines the answer to give
761 if there is no match from local-data. The types are deny,
762 refuse, static, transparent, redirect, nodefault, typetranspar‐
763 ent, and are explained below. After that the default settings
764 are listed. Use local-data: to enter data into the local zone.
765 Answers for local zones are authoritative DNS answers. By
766 default the zones are class IN.
767 If you need more complicated authoritative data, with referrals,
769 wildcards, CNAME/DNAME support, or DNSSEC authoritative service,
770 setup a stub-zone for it as detailed in the stub zone section
771 below.
772 deny Do not send an answer, drop the query. If there is a match
774 from local data, the query is answered.
775 refuse
777 Send an error message reply, with rcode REFUSED. If there is
778 a match from local data, the query is answered.
779 static
781 If there is a match from local data, the query is answered.
782 Otherwise, the query is answered with nodata or nxdomain.
783 For a negative answer a SOA is included in the answer if
784 present as local-data for the zone apex domain.
785 transparent
787 If there is a match from local data, the query is answered.
788 Otherwise if the query has a different name, the query is
789 resolved normally. If the query is for a name given in
790 localdata but no such type of data is given in localdata,
791 then a noerror nodata answer is returned. If no local-zone
792 is given local-data causes a transparent zone to be created
793 by default.
794 typetransparent
796 If there is a match from local data, the query is answered.
797 If the query is for a different name, or for the same name
798 but for a different type, the query is resolved normally.
799 So, similar to transparent but types that are not listed in
800 local data are resolved normally, so if an A record is in the
801 local data that does not cause a nodata reply for AAAA
802 queries.
803 redirect
805 The query is answered from the local data for the zone name.
806 There may be no local data beneath the zone name. This
807 answers queries for the zone, and all subdomains of the zone
808 with the local data for the zone. It can be used to redirect
809 a domain to return a different address record to the end
810 user, with local-zone: "example.com." redirect and
811 local-data: "example.com. A 127.0.0.1" queries for www.exam‐
812 ple.com and www.foo.example.com are redirected, so that users
813 with web browsers cannot access sites with suffix exam‐
814 ple.com.
815 nodefault
817 Used to turn off default contents for AS112 zones. The other
818 types also turn off default contents for the zone. The 'node‐
819 fault' option has no other effect than turning off default
820 contents for the given zone.
821 The default zones are localhost, reverse 127.0.0.1 and ::1, and the
823 AS112 zones. The AS112 zones are reverse DNS zones for private use and
824 reserved IP addresses for which the servers on the internet cannot pro‐
825 vide correct answers. They are configured by default to give nxdomain
826 (no reverse information) answers. The defaults can be turned off by
827 specifying your own local-zone of that name, or using the 'nodefault'
828 type. Below is a list of the default zone contents.
829 localhost
831 The IP4 and IP6 localhost information is given. NS and SOA
832 records are provided for completeness and to satisfy some DNS
833 update tools. Default content:
834 local-zone: "localhost." static
835 local-data: "localhost. 10800 IN NS localhost."
836 local-data: "localhost. 10800 IN
837 SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
838 local-data: "localhost. 10800 IN A 127.0.0.1"
839 local-data: "localhost. 10800 IN AAAA ::1"
840 reverse IPv4 loopback
842 Default content:
843 local-zone: "127.in-addr.arpa." static
844 local-data: "127.in-addr.arpa. 10800 IN NS localhost."
845 local-data: "127.in-addr.arpa. 10800 IN
846 SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
847 local-data: "1.0.0.127.in-addr.arpa. 10800 IN
848 PTR localhost."
849 reverse IPv6 loopback
851 Default content:
852 local-zone: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
853 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." static
854 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
855 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
856 NS localhost."
857 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
858 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
859 SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
860 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
861 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
862 PTR localhost."
863 reverse RFC1918 local use zones
865 Reverse data for zones 10.in-addr.arpa, 16.172.in-addr.arpa
866 to 31.172.in-addr.arpa, 168.192.in-addr.arpa. The
867 local-zone: is set static and as local-data: SOA and NS
868 records are provided.
869 reverse RFC3330 IP4 this, link-local, testnet and broadcast
871 Reverse data for zones 0.in-addr.arpa, 254.169.in-addr.arpa,
872 2.0.192.in-addr.arpa (TEST NET 1), 100.51.198.in-addr.arpa
873 (TEST NET 2), 113.0.203.in-addr.arpa (TEST NET 3),
874 255.255.255.255.in-addr.arpa.
875 reverse RFC4291 IP6 unspecified
877 Reverse data for zone
878 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
879 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa.
880 reverse RFC4193 IPv6 Locally Assigned Local Addresses
882 Reverse data for zone D.F.ip6.arpa.
883 reverse RFC4291 IPv6 Link Local Addresses
885 Reverse data for zones 8.E.F.ip6.arpa to B.E.F.ip6.arpa.
886 reverse IPv6 Example Prefix
888 Reverse data for zone 8.B.D.0.1.0.0.2.ip6.arpa. This zone is
889 used for tutorials and examples. You can remove the block on
890 this zone with:
891 local-zone: 8.B.D.0.1.0.0.2.ip6.arpa. nodefault
892 You can also selectively unblock a part of the zone by making
893 that part transparent with a local-zone statement. This also
894 works with the other default zones.
895 local-data: "<resource record string>"
897 Configure local data, which is served in reply to queries for it.
898 The query has to match exactly unless you configure the local-zone
899 as redirect. If not matched exactly, the local-zone type deter‐
900 mines further processing. If local-data is configured that is not
901 a subdomain of a local-zone, a transparent local-zone is config‐
902 ured. For record types such as TXT, use single quotes, as in
903 local-data: 'example. TXT "text"'.
904 If you need more complicated authoritative data, with referrals,
906 wildcards, CNAME/DNAME support, or DNSSEC authoritative service,
907 setup a stub-zone for it as detailed in the stub zone section
908 below.
909 local-data-ptr: "IPaddr name"
911 Configure local data shorthand for a PTR record with the reversed
912 IPv4 or IPv6 address and the host name. For example "192.0.2.4
913 www.example.com". TTL can be inserted like this: "2001:DB8::4
914 7200 www.example.com"
915 Remote Control Options
917 In the remote-control: clause are the declarations for the remote con‐
918 trol facility. If this is enabled, the unbound-control(8) utility can
919 be used to send commands to the running unbound server. The server
920 uses these clauses to setup SSLv3 / TLSv1 security for the connection.
921 The unbound-control(8) utility also reads the remote-control section
922 for options. To setup the correct self-signed certificates use the
923 unbound-control-setup(8) utility.
924 control-enable: <yes or no>
926 The option is used to enable remote control, default is "no". If
927 turned off, the server does not listen for control commands.
928 control-interface: <ip address>
930 Give IPv4 or IPv6 addresses to listen on for control commands. By
931 default localhost (127.0.0.1 and ::1) is listened to. Use 0.0.0.0
932 and ::0 to listen to all interfaces.
933 control-port: <port number>
935 The port number to listen on for control commands, default is
936 8953. If you change this port number, and permissions have been
937 dropped, a reload is not sufficient to open the port again, you
938 must then restart.
939 server-key-file: <private key file>
941 Path to the server private key, by default unbound_server.key.
942 This file is generated by the unbound-control-setup utility. This
943 file is used by the unbound server, but not by unbound-control.
944 server-cert-file: <certificate file.pem>
946 Path to the server self signed certificate, by default
947 unbound_server.pem. This file is generated by the unbound-con‐
948 trol-setup utility. This file is used by the unbound server, and
949 also by unbound-control.
950 control-key-file: <private key file>
952 Path to the control client private key, by default unbound_con‐
953 trol.key. This file is generated by the unbound-control-setup
954 utility. This file is used by unbound-control.
955 control-cert-file: <certificate file.pem>
957 Path to the control client certificate, by default unbound_con‐
958 trol.pem. This certificate has to be signed with the server cer‐
959 tificate. This file is generated by the unbound-control-setup
960 utility. This file is used by unbound-control.
961 Stub Zone Options
963 There may be multiple stub-zone: clauses. Each with a name: and zero or
964 more hostnames or IP addresses. For the stub zone this list of name‐
965 servers is used. Class IN is assumed. The servers should be authority
966 servers, not recursors; unbound performs the recursive processing
967 itself for stub zones.
968 The stub zone can be used to configure authoritative data to be used by
970 the resolver that cannot be accessed using the public internet servers.
971 This is useful for company-local data or private zones. Setup an
972 authoritative server on a different host (or different port). Enter a
973 config entry for unbound with stub-addr: <ip address of host[@port]>.
974 The unbound resolver can then access the data, without referring to the
975 public internet for it.
976 This setup allows DNSSEC signed zones to be served by that authorita‐
978 tive server, in which case a trusted key entry with the public key can
979 be put in config, so that unbound can validate the data and set the AD
980 bit on replies for the private zone (authoritative servers do not set
981 the AD bit). This setup makes unbound capable of answering queries for
982 the private zone, and can even set the AD bit ('authentic'), but the AA
983 ('authoritative') bit is not set on these replies.
984 name: <domain name>
986 Name of the stub zone.
987 stub-host: <domain name>
989 Name of stub zone nameserver. Is itself resolved before it is
990 used.
991 stub-addr: <IP address>
993 IP address of stub zone nameserver. Can be IP 4 or IP 6. To use
994 a nondefault port for DNS communication append '@' with the port
995 number.
996 stub-prime: <yes or no>
998 This option is by default off. If enabled it performs NS set
999 priming, which is similar to root hints, where it starts using
1000 the list of nameservers currently published by the zone. Thus,
1001 if the hint list is slightly outdated, the resolver picks up a
1002 correct list online.
1003 Forward Zone Options
1005 There may be multiple forward-zone: clauses. Each with a name: and zero
1006 or more hostnames or IP addresses. For the forward zone this list of
1007 nameservers is used to forward the queries to. The servers listed as
1008 forward-host: and forward-addr: have to handle further recursion for
1009 the query. Thus, those servers are not authority servers, but are
1010 (just like unbound is) recursive servers too; unbound does not perform
1011 recursion itself for the forward zone, it lets the remote server do it.
1012 Class IN is assumed. A forward-zone entry with name "." and a for‐
1013 ward-addr target will forward all queries to that other server (unless
1014 it can answer from the cache).
1015 name: <domain name>
1017 Name of the forward zone.
1018 forward-host: <domain name>
1020 Name of server to forward to. Is itself resolved before it is
1021 used.
1022 forward-addr: <IP address>
1024 IP address of server to forward to. Can be IP 4 or IP 6. To use
1025 a nondefault port for DNS communication append '@' with the port
1026 number.
1027 Python Module Options
1029 The python: clause gives the settings for the python(1) script module.
1030 This module acts like the iterator and validator modules do, on queries
1031 and answers. To enable the script module it has to be compiled into
1032 the daemon, and the word "python" has to be put in the module-config:
1033 option (usually first, or between the validator and iterator).
1034 python-script: <python file>
1036 The script file to load.
1037
1039 In the example config settings below memory usage is reduced. Some ser‐
1040 vice levels are lower, notable very large data and a high TCP load are
1041 no longer supported. Very large data and high TCP loads are exceptional
1042 for the DNS. DNSSEC validation is enabled, just add trust anchors. If
1043 you do not have to worry about programs using more than 3 Mb of memory,
1044 the below example is not for you. Use the defaults to receive full ser‐
1045 vice, which on BSD-32bit tops out at 30-40 Mb after heavy usage.
1046 # example settings that reduce memory usage
1048 server:
1049 num-threads: 1
1050 outgoing-num-tcp: 1 # this limits TCP service, uses less buffers.
1051 incoming-num-tcp: 1
1052 outgoing-range: 60 # uses less memory, but less performance.
1053 msg-buffer-size: 8192 # note this limits service, 'no huge stuff'.
1054 msg-cache-size: 100k
1055 msg-cache-slabs: 1
1056 rrset-cache-size: 100k
1057 rrset-cache-slabs: 1
1058 infra-cache-numhosts: 200
1059 infra-cache-slabs: 1
1060 infra-cache-lame-size: 1k
1061 key-cache-size: 100k
1062 key-cache-slabs: 1
1063 neg-cache-size: 10k
1064 num-queries-per-thread: 30
1065 target-fetch-policy: "2 1 0 0 0 0"
1066 harden-large-queries: "yes"
1067 harden-short-bufsize: "yes"
1068
1070 /etc/unbound
1071 default unbound working directory.
1072 /etc/unbound
1074 default chroot(2) location.
1075 /etc/unbound/unbound.conf
1077 unbound configuration file.
1078 /var/run/unbound/unbound.pid
1080 default unbound pidfile with process ID of the running daemon.
1081 unbound.log
1083 unbound log file. default is to log to syslog(3).
1084
1086 unbound(8), unbound-checkconf(8).
1087
1089 Unbound was written by NLnet Labs. Please see CREDITS file in the dis‐
1090 tribution for further details.
1091NLnet Labs Sep 15, 2011 unbound.conf(5)