forked from NLnetLabs/unbound
-
Notifications
You must be signed in to change notification settings - Fork 0
/
unbound.conf.5.in
2852 lines (2851 loc) · 134 KB
/
unbound.conf.5.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.TH "unbound.conf" "5" "@date@" "NLnet Labs" "unbound @version@"
.\"
.\" unbound.conf.5 -- unbound.conf manual
.\"
.\" Copyright (c) 2007, NLnet Labs. All rights reserved.
.\"
.\" See LICENSE for the license.
.\"
.\"
.SH "NAME"
.B unbound.conf
\- Unbound configuration file.
.SH "SYNOPSIS"
.B unbound.conf
.SH "DESCRIPTION"
.B unbound.conf
is used to configure
\fIunbound\fR(8).
The file format has attributes and values. Some attributes have attributes
inside them.
The notation is: attribute: value.
.P
Comments start with # and last to the end of line. Empty lines are
ignored as is whitespace at the beginning of a line.
.P
The utility
\fIunbound\-checkconf\fR(8)
can be used to check unbound.conf prior to usage.
.SH "EXAMPLE"
An example config file is shown below. Copy this to /etc/unbound/unbound.conf
and start the server with:
.P
.nf
$ unbound \-c /etc/unbound/unbound.conf
.fi
.P
Most settings are the defaults. Stop the server with:
.P
.nf
$ kill `cat /etc/unbound/unbound.pid`
.fi
.P
Below is a minimal config file. The source distribution contains an extensive
example.conf file with all the options.
.P
.nf
# unbound.conf(5) config file for unbound(8).
server:
directory: "/etc/unbound"
username: unbound
# make sure unbound can access entropy from inside the chroot.
# e.g. on linux the use these commands (on BSD, devfs(8) is used):
# mount \-\-bind \-n /dev/urandom /etc/unbound/dev/urandom
# and mount \-\-bind \-n /dev/log /etc/unbound/dev/log
chroot: "/etc/unbound"
# logfile: "/etc/unbound/unbound.log" #uncomment to use logfile.
pidfile: "/etc/unbound/unbound.pid"
# verbosity: 1 # uncomment and increase to get more logging.
# listen on all interfaces, answer queries from the local subnet.
interface: 0.0.0.0
interface: ::0
access\-control: 10.0.0.0/8 allow
access\-control: 2001:DB8::/64 allow
.fi
.SH "FILE FORMAT"
There must be whitespace between keywords. Attribute keywords end with a
colon ':'. An attribute is followed by a value, or its containing attributes
in which case it is referred to as a clause. Clauses can be repeated throughout
the file (or included files) to group attributes under the same clause.
.P
Files can be included using the
.B include:
directive. It can appear anywhere, it accepts a single file name as argument.
Processing continues as if the text from the included file was copied into
the config file at that point. If also using chroot, using full path names
for the included files works, relative pathnames for the included names work
if the directory where the daemon is started equals its chroot/working
directory or is specified before the include statement with directory: dir.
Wildcards can be used to include multiple files, see \fIglob\fR(7).
.P
For a more structural include option, the
.B include\-toplevel:
directive can be used. This closes whatever clause is currently active (if any)
and forces the use of clauses in the included files and right after this
directive.
.SS "Server Options"
These options are part of the
.B server:
clause.
.TP
.B verbosity: \fI<number>
The verbosity number, level 0 means no verbosity, only errors. Level 1
gives operational information. Level 2 gives detailed operational
information including short information per query. Level 3 gives query level
information, output per query. Level 4 gives algorithm level information.
Level 5 logs client identification for cache misses. Default is level 1.
The verbosity can also be increased from the commandline, see \fIunbound\fR(8).
.TP
.B statistics\-interval: \fI<seconds>
The number of seconds between printing statistics to the log for every thread.
Disable with value 0 or "". Default is disabled. The histogram statistics
are only printed if replies were sent during the statistics interval,
requestlist statistics are printed for every interval (but can be 0).
This is because the median calculation requires data to be present.
.TP
.B statistics\-cumulative: \fI<yes or no>
If enabled, statistics are cumulative since starting Unbound, without clearing
the statistics counters after logging the statistics. Default is no.
.TP
.B extended\-statistics: \fI<yes or no>
If enabled, extended statistics are printed from \fIunbound\-control\fR(8).
Default is off, because keeping track of more statistics takes time. The
counters are listed in \fIunbound\-control\fR(8).
.TP
.B num\-threads: \fI<number>
The number of threads to create to serve clients. Use 1 for no threading.
.TP
.B port: \fI<port number>
The port number, default 53, on which the server responds to queries.
.TP
.B interface: \fI<ip address or interface name [@port]>
Interface to use to connect to the network. This interface is listened to
for queries from clients, and answers to clients are given from it.
Can be given multiple times to work on several interfaces. If none are
given the default is to listen to localhost. If an interface name is used
instead of an ip address, the list of ip addresses on that interface are used.
The interfaces are not changed on a reload (kill \-HUP) but only on restart.
A port number can be specified with @port (without spaces between
interface and port number), if not specified the default port (from
\fBport\fR) is used.
.TP
.B ip\-address: \fI<ip address or interface name [@port]>
Same as interface: (for ease of compatibility with nsd.conf).
.TP
.B interface\-automatic: \fI<yes or no>
Listen on all addresses on all (current and future) interfaces, detect the
source interface on UDP queries and copy them to replies. This is a lot like
ip\-transparent, but this option services all interfaces whilst with
ip\-transparent you can select which (future) interfaces Unbound provides
service on. This feature is experimental, and needs support in your OS for
particular socket options. Default value is no.
.TP
.B interface\-automatic\-ports: \fI<string>
List the port numbers that interface-automatic listens on. If empty, the
default port is listened on. The port numbers are separated by spaces in the
string. Default is "".
.IP
This can be used to have interface automatic to deal with the interface,
and listen on the normal port number, by including it in the list, and
also https or dns over tls port numbers by putting them in the list as well.
.TP
.B outgoing\-interface: \fI<ip address or ip6 netblock>
Interface to use to connect to the network. This interface is used to send
queries to authoritative servers and receive their replies. Can be given
multiple times to work on several interfaces. If none are given the
default (all) is used. You can specify the same interfaces in
.B interface:
and
.B outgoing\-interface:
lines, the interfaces are then used for both purposes. Outgoing queries are
sent via a random outgoing interface to counter spoofing.
.IP
If an IPv6 netblock is specified instead of an individual IPv6 address,
outgoing UDP queries will use a randomised source address taken from the
netblock to counter spoofing. Requires the IPv6 netblock to be routed to the
host running Unbound, and requires OS support for unprivileged non-local binds
(currently only supported on Linux). Several netblocks may be specified with
multiple
.B outgoing\-interface:
options, but do not specify both an individual IPv6 address and an IPv6
netblock, or the randomisation will be compromised. Consider combining with
.B prefer\-ip6: yes
to increase the likelihood of IPv6 nameservers being selected for queries.
On Linux you need these two commands to be able to use the freebind socket
option to receive traffic for the ip6 netblock:
ip \-6 addr add mynetblock/64 dev lo &&
ip \-6 route add local mynetblock/64 dev lo
.TP
.B outgoing\-range: \fI<number>
Number of ports to open. This number of file descriptors can be opened per
thread. Must be at least 1. Default depends on compile options. Larger
numbers need extra resources from the operating system. For performance a
very large value is best, use libevent to make this possible.
.TP
.B outgoing\-port\-permit: \fI<port number or range>
Permit Unbound to open this port or range of ports for use to send queries.
A larger number of permitted outgoing ports increases resilience against
spoofing attempts. Make sure these ports are not needed by other daemons.
By default only ports above 1024 that have not been assigned by IANA are used.
Give a port number or a range of the form "low\-high", without spaces.
.IP
The \fBoutgoing\-port\-permit\fR and \fBoutgoing\-port\-avoid\fR statements
are processed in the line order of the config file, adding the permitted ports
and subtracting the avoided ports from the set of allowed ports. The
processing starts with the non IANA allocated ports above 1024 in the set
of allowed ports.
.TP
.B outgoing\-port\-avoid: \fI<port number or range>
Do not permit Unbound to open this port or range of ports for use to send
queries. Use this to make sure Unbound does not grab a port that another
daemon needs. The port is avoided on all outgoing interfaces, both IP4 and IP6.
By default only ports above 1024 that have not been assigned by IANA are used.
Give a port number or a range of the form "low\-high", without spaces.
.TP
.B outgoing\-num\-tcp: \fI<number>
Number of outgoing TCP buffers to allocate per thread. Default is 10. If
set to 0, or if do\-tcp is "no", no TCP queries to authoritative servers
are done. For larger installations increasing this value is a good idea.
.TP
.B incoming\-num\-tcp: \fI<number>
Number of incoming TCP buffers to allocate per thread. Default is
10. If set to 0, or if do\-tcp is "no", no TCP queries from clients are
accepted. For larger installations increasing this value is a good idea.
.TP
.B edns\-buffer\-size: \fI<number>
Number of bytes size to advertise as the EDNS reassembly buffer size.
This is the value put into datagrams over UDP towards peers. The actual
buffer size is determined by msg\-buffer\-size (both for TCP and UDP). Do
not set higher than that value. Default is 1232 which is the DNS Flag Day 2020
recommendation. Setting to 512 bypasses even the most stringent path MTU
problems, but is seen as extreme, since the amount of TCP fallback generated is
excessive (probably also for this resolver, consider tuning the outgoing tcp
number).
.TP
.B max\-udp\-size: \fI<number>
Maximum UDP response size (not applied to TCP response). 65536 disables the
udp response size maximum, and uses the choice from the client, always.
Suggested values are 512 to 4096. Default is 4096.
.TP
.B stream\-wait\-size: \fI<number>
Number of bytes size maximum to use for waiting stream buffers. Default is
4 megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes,
megabytes or gigabytes (1024*1024 bytes in a megabyte). As TCP and TLS streams
queue up multiple results, the amount of memory used for these buffers does
not exceed this number, otherwise the responses are dropped. This manages
the total memory usage of the server (under heavy use), the number of requests
that can be queued up per connection is also limited, with further requests
waiting in TCP buffers.
.TP
.B msg\-buffer\-size: \fI<number>
Number of bytes size of the message buffers. Default is 65552 bytes, enough
for 64 Kb packets, the maximum DNS message size. No message larger than this
can be sent or received. Can be reduced to use less memory, but some requests
for DNS data, such as for huge resource records, will result in a SERVFAIL
reply to the client.
.TP
.B msg\-cache\-size: \fI<number>
Number of bytes size of the message cache. Default is 4 megabytes.
A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
or gigabytes (1024*1024 bytes in a megabyte).
.TP
.B msg\-cache\-slabs: \fI<number>
Number of slabs in the message cache. Slabs reduce lock contention by threads.
Must be set to a power of 2. Setting (close) to the number of cpus is a
reasonable guess.
.TP
.B num\-queries\-per\-thread: \fI<number>
The number of queries that every thread will service simultaneously.
If more queries arrive that need servicing, and no queries can be jostled out
(see \fIjostle\-timeout\fR), then the queries are dropped. This forces
the client to resend after a timeout; allowing the server time to work on
the existing queries. Default depends on compile options, 512 or 1024.
.TP
.B jostle\-timeout: \fI<msec>
Timeout used when the server is very busy. Set to a value that usually
results in one roundtrip to the authority servers. If too many queries
arrive, then 50% of the queries are allowed to run to completion, and
the other 50% are replaced with the new incoming query if they have already
spent more than their allowed time. This protects against denial of
service by slow queries or high query rates. Default 200 milliseconds.
The effect is that the qps for long-lasting queries is about
(numqueriesperthread / 2) / (average time for such long queries) qps.
The qps for short queries can be about (numqueriesperthread / 2)
/ (jostletimeout in whole seconds) qps per thread, about (1024/2)*5 = 2560
qps by default.
.TP
.B delay\-close: \fI<msec>
Extra delay for timeouted UDP ports before they are closed, in msec.
Default is 0, and that disables it. This prevents very delayed answer
packets from the upstream (recursive) servers from bouncing against
closed ports and setting off all sort of close-port counters, with
eg. 1500 msec. When timeouts happen you need extra sockets, it checks
the ID and remote IP of packets, and unwanted packets are added to the
unwanted packet counter.
.TP
.B udp\-connect: \fI<yes or no>
Perform connect for UDP sockets that mitigates ICMP side channel leakage.
Default is yes.
.TP
.B unknown\-server\-time\-limit: \fI<msec>
The wait time in msec for waiting for an unknown server to reply.
Increase this if you are behind a slow satellite link, to eg. 1128.
That would then avoid re\-querying every initial query because it times out.
Default is 376 msec.
.TP
.B so\-rcvbuf: \fI<number>
If not 0, then set the SO_RCVBUF socket option to get more buffer
space on UDP port 53 incoming queries. So that short spikes on busy
servers do not drop packets (see counter in netstat \-su). Default is
0 (use system value). Otherwise, the number of bytes to ask for, try
"4m" on a busy server. The OS caps it at a maximum, on linux Unbound
needs root permission to bypass the limit, or the admin can use sysctl
net.core.rmem_max. On BSD change kern.ipc.maxsockbuf in /etc/sysctl.conf.
On OpenBSD change header and recompile kernel. On Solaris ndd \-set
/dev/udp udp_max_buf 8388608.
.TP
.B so\-sndbuf: \fI<number>
If not 0, then set the SO_SNDBUF socket option to get more buffer space on
UDP port 53 outgoing queries. This for very busy servers handles spikes
in answer traffic, otherwise 'send: resource temporarily unavailable'
can get logged, the buffer overrun is also visible by netstat \-su.
Default is 0 (use system value). Specify the number of bytes to ask
for, try "4m" on a very busy server. The OS caps it at a maximum, on
linux Unbound needs root permission to bypass the limit, or the admin
can use sysctl net.core.wmem_max. On BSD, Solaris changes are similar
to so\-rcvbuf.
.TP
.B so\-reuseport: \fI<yes or no>
If yes, then open dedicated listening sockets for incoming queries for each
thread and try to set the SO_REUSEPORT socket option on each socket. May
distribute incoming queries to threads more evenly. Default is yes.
On Linux it is supported in kernels >= 3.9. On other systems, FreeBSD, OSX
it may also work. You can enable it (on any platform and kernel),
it then attempts to open the port and passes the option if it was available
at compile time, if that works it is used, if it fails, it continues
silently (unless verbosity 3) without the option.
At extreme load it could be better to turn it off to distribute the queries
evenly, reported for Linux systems (4.4.x).
.TP
.B ip\-transparent: \fI<yes or no>
If yes, then use IP_TRANSPARENT socket option on sockets where Unbound
is listening for incoming traffic. Default no. Allows you to bind to
non\-local interfaces. For example for non\-existent IP addresses that
are going to exist later on, with host failover configuration. This is
a lot like interface\-automatic, but that one services all interfaces
and with this option you can select which (future) interfaces Unbound
provides service on. This option needs Unbound to be started with root
permissions on some systems. The option uses IP_BINDANY on FreeBSD systems
and SO_BINDANY on OpenBSD systems.
.TP
.B ip\-freebind: \fI<yes or no>
If yes, then use IP_FREEBIND socket option on sockets where Unbound
is listening to incoming traffic. Default no. Allows you to bind to
IP addresses that are nonlocal or do not exist, like when the network
interface or IP address is down. Exists only on Linux, where the similar
ip\-transparent option is also available.
.TP
.B ip-dscp: \fI<number>
The value of the Differentiated Services Codepoint (DSCP) in the
differentiated services field (DS) of the outgoing IP packet headers.
The field replaces the outdated IPv4 Type-Of-Service field and the
IPv6 traffic class field.
.TP
.B rrset\-cache\-size: \fI<number>
Number of bytes size of the RRset cache. Default is 4 megabytes.
A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes, megabytes
or gigabytes (1024*1024 bytes in a megabyte).
.TP
.B rrset\-cache\-slabs: \fI<number>
Number of slabs in the RRset cache. Slabs reduce lock contention by threads.
Must be set to a power of 2.
.TP
.B cache\-max\-ttl: \fI<seconds>
Time to live maximum for RRsets and messages in the cache. Default is
86400 seconds (1 day). When the TTL expires, the cache item has expired.
Can be set lower to force the resolver to query for data often, and not
trust (very large) TTL values. Downstream clients also see the lower TTL.
.TP
.B cache\-min\-ttl: \fI<seconds>
Time to live minimum for RRsets and messages in the cache. Default is 0.
If the minimum kicks in, the data is cached for longer than the domain
owner intended, and thus less queries are made to look up the data.
Zero makes sure the data in the cache is as the domain owner intended,
higher values, especially more than an hour or so, can lead to trouble as
the data in the cache does not match up with the actual data any more.
.TP
.B cache\-max\-negative\-ttl: \fI<seconds>
Time to live maximum for negative responses, these have a SOA in the
authority section that is limited in time. Default is 3600.
This applies to nxdomain and nodata answers.
.TP
.B infra\-host\-ttl: \fI<seconds>
Time to live for entries in the host cache. The host cache contains
roundtrip timing, lameness and EDNS support information. Default is 900.
.TP
.B infra\-cache\-slabs: \fI<number>
Number of slabs in the infrastructure cache. Slabs reduce lock contention
by threads. Must be set to a power of 2.
.TP
.B infra\-cache\-numhosts: \fI<number>
Number of hosts for which information is cached. Default is 10000.
.TP
.B infra\-cache\-min\-rtt: \fI<msec>
Lower limit for dynamic retransmit timeout calculation in infrastructure
cache. Default is 50 milliseconds. Increase this value if using forwarders
needing more time to do recursive name resolution.
.TP
.B infra\-cache\-max\-rtt: \fI<msec>
Upper limit for dynamic retransmit timeout calculation in infrastructure
cache. Default is 2 minutes.
.TP
.B infra\-keep\-probing: \fI<yes or no>
If enabled the server keeps probing hosts that are down, in the one probe
at a time regime. Default is no. Hosts that are down, eg. they did
not respond during the one probe at a time period, are marked as down and
it may take \fBinfra\-host\-ttl\fR time to get probed again.
.TP
.B define\-tag: \fI<"list of tags">
Define the tags that can be used with local\-zone and access\-control.
Enclose the list between quotes ("") and put spaces between tags.
.TP
.B do\-ip4: \fI<yes or no>
Enable or disable whether ip4 queries are answered or issued. Default is yes.
.TP
.B do\-ip6: \fI<yes or no>
Enable or disable whether ip6 queries are answered or issued. Default is yes.
If disabled, queries are not answered on IPv6, and queries are not sent on
IPv6 to the internet nameservers. With this option you can disable the
IPv6 transport for sending DNS traffic, it does not impact the contents of
the DNS traffic, which may have ip4 and ip6 addresses in it.
.TP
.B prefer\-ip4: \fI<yes or no>
If enabled, prefer IPv4 transport for sending DNS queries to internet
nameservers. Default is no. Useful if the IPv6 netblock the server has,
the entire /64 of that is not owned by one operator and the reputation of
the netblock /64 is an issue, using IPv4 then uses the IPv4 filters that
the upstream servers have.
.TP
.B prefer\-ip6: \fI<yes or no>
If enabled, prefer IPv6 transport for sending DNS queries to internet
nameservers. Default is no.
.TP
.B do\-udp: \fI<yes or no>
Enable or disable whether UDP queries are answered or issued. Default is yes.
.TP
.B do\-tcp: \fI<yes or no>
Enable or disable whether TCP queries are answered or issued. Default is yes.
.TP
.B tcp\-mss: \fI<number>
Maximum segment size (MSS) of TCP socket on which the server responds
to queries. Value lower than common MSS on Ethernet
(1220 for example) will address path MTU problem.
Note that not all platform supports socket option to set MSS (TCP_MAXSEG).
Default is system default MSS determined by interface MTU and
negotiation between server and client.
.TP
.B outgoing\-tcp\-mss: \fI<number>
Maximum segment size (MSS) of TCP socket for outgoing queries
(from Unbound to other servers). Value lower than
common MSS on Ethernet (1220 for example) will address path MTU problem.
Note that not all platform supports socket option to set MSS (TCP_MAXSEG).
Default is system default MSS determined by interface MTU and
negotiation between Unbound and other servers.
.TP
.B tcp-idle-timeout: \fI<msec>\fR
The period Unbound will wait for a query on a TCP connection.
If this timeout expires Unbound closes the connection.
This option defaults to 30000 milliseconds.
When the number of free incoming TCP buffers falls below 50% of the
total number configured, the option value used is progressively
reduced, first to 1% of the configured value, then to 0.2% of the
configured value if the number of free buffers falls below 35% of the
total number configured, and finally to 0 if the number of free buffers
falls below 20% of the total number configured. A minimum timeout of
200 milliseconds is observed regardless of the option value used.
.TP
.B tcp-reuse-timeout: \fI<msec>\fR
The period Unbound will keep TCP persistent connections open to
authority servers. This option defaults to 60000 milliseconds.
.TP
.B max-reuse-tcp-queries: \fI<number>\fR
The maximum number of queries that can be sent on a persistent TCP
connection.
This option defaults to 200 queries.
.TP
.B tcp-auth-query-timeout: \fI<number>\fR
Timeout in milliseconds for TCP queries to auth servers.
This option defaults to 3000 milliseconds.
.TP
.B edns-tcp-keepalive: \fI<yes or no>\fR
Enable or disable EDNS TCP Keepalive. Default is no.
.TP
.B edns-tcp-keepalive-timeout: \fI<msec>\fR
The period Unbound will wait for a query on a TCP connection when
EDNS TCP Keepalive is active. If this timeout expires Unbound closes
the connection. If the client supports the EDNS TCP Keepalive option,
Unbound sends the timeout value to the client to encourage it to
close the connection before the server times out.
This option defaults to 120000 milliseconds.
When the number of free incoming TCP buffers falls below 50% of
the total number configured, the advertised timeout is progressively
reduced to 1% of the configured value, then to 0.2% of the configured
value if the number of free buffers falls below 35% of the total number
configured, and finally to 0 if the number of free buffers falls below
20% of the total number configured.
A minimum actual timeout of 200 milliseconds is observed regardless of the
advertised timeout.
.TP
.B tcp\-upstream: \fI<yes or no>
Enable or disable whether the upstream queries use TCP only for transport.
Default is no. Useful in tunneling scenarios. If set to no you can specify
TCP transport only for selected forward or stub zones using forward-tcp-upstream
or stub-tcp-upstream respectively.
.TP
.B udp\-upstream\-without\-downstream: \fI<yes or no>
Enable udp upstream even if do-udp is no. Default is no, and this does not
change anything. Useful for TLS service providers, that want no udp downstream
but use udp to fetch data upstream.
.TP
.B tls\-upstream: \fI<yes or no>
Enabled or disable whether the upstream queries use TLS only for transport.
Default is no. Useful in tunneling scenarios. The TLS contains plain DNS in
TCP wireformat. The other server must support this (see
\fBtls\-service\-key\fR).
If you enable this, also configure a tls\-cert\-bundle or use tls\-win\-cert or
tls\-system\-cert to load CA certs, otherwise the connections cannot be
authenticated. This option enables TLS for all of them, but if you do not set
this you can configure TLS specifically for some forward zones with
forward\-tls\-upstream. And also with stub\-tls\-upstream.
.TP
.B ssl\-upstream: \fI<yes or no>
Alternate syntax for \fBtls\-upstream\fR. If both are present in the config
file the last is used.
.TP
.B tls\-service\-key: \fI<file>
If enabled, the server provides DNS-over-TLS or DNS-over-HTTPS service on the
TCP ports marked implicitly or explicitly for these services with tls\-port or
https\-port. The file must contain the private key for the TLS session, the
public certificate is in the tls\-service\-pem file and it must also be
specified if tls\-service\-key is specified. The default is "", turned off.
Enabling or disabling this service requires a restart (a reload is not enough),
because the key is read while root permissions are held and before chroot (if any).
The ports enabled implicitly or explicitly via \fBtls\-port:\fR and
\fBhttps\-port:\fR do not provide normal DNS TCP service. Unbound needs to be
compiled with libnghttp2 in order to provide DNS-over-HTTPS.
.TP
.B ssl\-service\-key: \fI<file>
Alternate syntax for \fBtls\-service\-key\fR.
.TP
.B tls\-service\-pem: \fI<file>
The public key certificate pem file for the tls service. Default is "",
turned off.
.TP
.B ssl\-service\-pem: \fI<file>
Alternate syntax for \fBtls\-service\-pem\fR.
.TP
.B tls\-port: \fI<number>
The port number on which to provide TCP TLS service, default 853, only
interfaces configured with that port number as @number get the TLS service.
.TP
.B ssl\-port: \fI<number>
Alternate syntax for \fBtls\-port\fR.
.TP
.B tls\-cert\-bundle: \fI<file>
If null or "", no file is used. Set it to the certificate bundle file,
for example "/etc/pki/tls/certs/ca\-bundle.crt". These certificates are used
for authenticating connections made to outside peers. For example auth\-zone
urls, and also DNS over TLS connections. It is read at start up before
permission drop and chroot.
.TP
.B ssl\-cert\-bundle: \fI<file>
Alternate syntax for \fBtls\-cert\-bundle\fR.
.TP
.B tls\-win\-cert: \fI<yes or no>
Add the system certificates to the cert bundle certificates for authentication.
If no cert bundle, it uses only these certificates. Default is no.
On windows this option uses the certificates from the cert store. Use
the tls\-cert\-bundle option on other systems. On other systems, this option
enables the system certificates.
.TP
.B tls\-system\-cert: \fI<yes or no>
This the same setting as the tls\-win\-cert setting, under a different name.
Because it is not windows specific.
.TP
.B tls\-additional\-port: \fI<portnr>
List portnumbers as tls\-additional\-port, and when interfaces are defined,
eg. with the @port suffix, as this port number, they provide dns over TLS
service. Can list multiple, each on a new statement.
.TP
.B tls-session-ticket-keys: \fI<file>
If not "", lists files with 80 bytes of random contents that are used to
perform TLS session resumption for clients using the Unbound server.
These files contain the secret key for the TLS session tickets.
First key use to encrypt and decrypt TLS session tickets.
Other keys use to decrypt only. With this you can roll over to new keys,
by generating a new first file and allowing decrypt of the old file by
listing it after the first file for some time, after the wait clients are not
using the old key any more and the old key can be removed.
One way to create the file is dd if=/dev/random bs=1 count=80 of=ticket.dat
The first 16 bytes should be different from the old one if you create a second key, that is the name used to identify the key. Then there is 32 bytes random
data for an AES key and then 32 bytes random data for the HMAC key.
.TP
.B tls\-ciphers: \fI<string with cipher list>
Set the list of ciphers to allow when serving TLS. Use "" for defaults,
and that is the default.
.TP
.B tls\-ciphersuites: \fI<string with ciphersuites list>
Set the list of ciphersuites to allow when serving TLS. This is for newer
TLS 1.3 connections. Use "" for defaults, and that is the default.
.TP
.B pad\-responses: \fI<yes or no>
If enabled, TLS serviced queries that contained an EDNS Padding option will
cause responses padded to the closest multiple of the size specified in
\fBpad\-responses\-block\-size\fR.
Default is yes.
.TP
.B pad\-responses\-block\-size: \fI<number>
The block size with which to pad responses serviced over TLS. Only responses
to padded queries will be padded.
Default is 468.
.TP
.B pad\-queries: \fI<yes or no>
If enabled, all queries sent over TLS upstreams will be padded to the closest
multiple of the size specified in \fBpad\-queries\-block\-size\fR.
Default is yes.
.TP
.B pad\-queries\-block\-size: \fI<number>
The block size with which to pad queries sent over TLS upstreams.
Default is 128.
.TP
.B tls\-use\-sni: \fI<yes or no>
Enable or disable sending the SNI extension on TLS connections.
Default is yes.
Changing the value requires a reload.
.TP
.B https\-port: \fI<number>
The port number on which to provide DNS-over-HTTPS service, default 443, only
interfaces configured with that port number as @number get the HTTPS service.
.TP
.B http\-endpoint: \fI<endpoint string>
The HTTP endpoint to provide DNS-over-HTTPS service on. Default "/dns-query".
.TP
.B http\-max\-streams: \fI<number of streams>
Number used in the SETTINGS_MAX_CONCURRENT_STREAMS parameter in the HTTP/2
SETTINGS frame for DNS-over-HTTPS connections. Default 100.
.TP
.B http\-query\-buffer\-size: \fI<size in bytes>
Maximum number of bytes used for all HTTP/2 query buffers combined. These
buffers contain (partial) DNS queries waiting for request stream completion.
An RST_STREAM frame will be send to streams exceeding this limit. Default is 4
megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes,
megabytes or gigabytes (1024*1024 bytes in a megabyte).
.TP
.B http\-response\-buffer\-size: \fI<size in bytes>
Maximum number of bytes used for all HTTP/2 response buffers combined. These
buffers contain DNS responses waiting to be written back to the clients.
An RST_STREAM frame will be send to streams exceeding this limit. Default is 4
megabytes. A plain number is in bytes, append 'k', 'm' or 'g' for kilobytes,
megabytes or gigabytes (1024*1024 bytes in a megabyte).
.TP
.B http\-nodelay: \fI<yes or no>
Set TCP_NODELAY socket option on sockets used to provide DNS-over-HTTPS service.
Ignored if the option is not available. Default is yes.
.TP
.B http\-notls\-downstream: \fI<yes or no>
Disable use of TLS for the downstream DNS-over-HTTP connections. Useful for
local back end servers. Default is no.
.TP
.B proxy\-protocol\-port: \fI<portnr>
List port numbers as proxy\-protocol\-port, and when interfaces are defined,
eg. with the @port suffix, as this port number, they support and expect PROXYv2.
In this case the proxy address will only be used for the network communication
and initial ACL (check if the proxy itself is denied/refused by configuration).
The proxied address (if any) will then be used as the true client address and
will be used where applicable for logging, ACL, DNSTAP, RPZ and IP ratelimiting.
PROXYv2 is supported for UDP and TCP/TLS listening interfaces.
There is no support for PROXYv2 on a DoH or DNSCrypt listening interface.
Can list multiple, each on a new statement.
.TP
.B use\-systemd: \fI<yes or no>
Enable or disable systemd socket activation.
Default is no.
.TP
.B do\-daemonize: \fI<yes or no>
Enable or disable whether the Unbound server forks into the background as
a daemon. Set the value to \fIno\fR when Unbound runs as systemd service.
Default is yes.
.TP
.B tcp\-connection\-limit: \fI<IP netblock> <limit>
Allow up to \fIlimit\fR simultaneous TCP connections from the given netblock.
When at the limit, further connections are accepted but closed immediately.
This option is experimental at this time.
.TP
.B access\-control: \fI<IP netblock> <action>
The netblock is given as an IP4 or IP6 address with /size appended for a
classless network block. The action can be \fIdeny\fR, \fIrefuse\fR,
\fIallow\fR, \fIallow_setrd\fR, \fIallow_snoop\fR, \fIdeny_non_local\fR or
\fIrefuse_non_local\fR.
The most specific netblock match is used, if none match \fIrefuse\fR is used.
The order of the access\-control statements therefore does not matter.
.IP
The action \fIdeny\fR stops queries from hosts from that netblock.
.IP
The action \fIrefuse\fR stops queries too, but sends a DNS rcode REFUSED
error message back.
.IP
The action \fIallow\fR gives access to clients from that netblock.
It gives only access for recursion clients (which is
what almost all clients need). Nonrecursive queries are refused.
.IP
The \fIallow\fR action does allow nonrecursive queries to access the
local\-data that is configured. The reason is that this does not involve
the Unbound server recursive lookup algorithm, and static data is served
in the reply. This supports normal operations where nonrecursive queries
are made for the authoritative data. For nonrecursive queries any replies
from the dynamic cache are refused.
.IP
The \fIallow_setrd\fR action ignores the recursion desired (RD) bit and
treats all requests as if the recursion desired bit is set. Note that this
behavior violates RFC 1034 which states that a name server should never perform
recursive service unless asked via the RD bit since this interferes with
trouble shooting of name servers and their databases. This prohibited behavior
may be useful if another DNS server must forward requests for specific
zones to a resolver DNS server, but only supports stub domains and
sends queries to the resolver DNS server with the RD bit cleared.
.IP
The action \fIallow_snoop\fR gives nonrecursive access too. This give
both recursive and non recursive access. The name \fIallow_snoop\fR refers
to cache snooping, a technique to use nonrecursive queries to examine
the cache contents (for malicious acts). However, nonrecursive queries can
also be a valuable debugging tool (when you want to examine the cache
contents). In that case use \fIallow_snoop\fR for your administration host.
.IP
By default only localhost is \fIallow\fRed, the rest is \fIrefuse\fRd.
The default is \fIrefuse\fRd, because that is protocol\-friendly. The DNS
protocol is not designed to handle dropped packets due to policy, and
dropping may result in (possibly excessive) retried queries.
.IP
The deny_non_local and refuse_non_local settings are for hosts that are
only allowed to query for the authoritative local\-data, they are not
allowed full recursion but only the static data. With deny_non_local,
messages that are disallowed are dropped, with refuse_non_local they
receive error code REFUSED.
.TP
.B access\-control\-tag: \fI<IP netblock> <"list of tags">
Assign tags to access-control elements. Clients using this access control
element use localzones that are tagged with one of these tags. Tags must be
defined in \fIdefine\-tags\fR. Enclose list of tags in quotes ("") and put
spaces between tags. If access\-control\-tag is configured for a netblock that
does not have an access\-control, an access\-control element with action
\fIallow\fR is configured for this netblock.
.TP
.B access\-control\-tag\-action: \fI<IP netblock> <tag> <action>
Set action for particular tag for given access control element. If you have
multiple tag values, the tag used to lookup the action is the first tag match
between access\-control\-tag and local\-zone\-tag where "first" comes from the
order of the define-tag values.
.TP
.B access\-control\-tag\-data: \fI<IP netblock> <tag> <"resource record string">
Set redirect data for particular tag for given access control element.
.TP
.B access\-control\-view: \fI<IP netblock> <view name>
Set view for given access control element.
.TP
.B interface\-action: \fI<ip address or interface name [@port]> <action>
Similar to \fBaccess\-control:\fR but for interfaces.
.IP
The action is the same as the ones defined under \fBaccess\-control:\fR.
Interfaces are \fIrefuse\fRd by default.
By default only localhost (the IP netblock, not the loopback interface) is
\fIallow\fRed through the default \fBaccess\-control:\fR behavior.
.IP
Note that the interface needs to be already specified with \fBinterface:\fR
and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR
settings for targeted clients.
.TP
.B interface\-tag: \fI<ip address or interface name [@port]> <"list of tags">
Similar to \fBaccess\-control-tag:\fR but for interfaces.
.IP
Note that the interface needs to be already specified with \fBinterface:\fR
and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR
settings for targeted clients.
.TP
.B interface\-tag\-action: \fI<ip address or interface name [@port]> <tag> <action>
Similar to \fBaccess\-control-tag-action:\fR but for interfaces.
.IP
Note that the interface needs to be already specified with \fBinterface:\fR
and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR
settings for targeted clients.
.TP
.B interface\-tag\-data: \fI<ip address or interface name [@port]> <tag> <"resource record string">
Similar to \fBaccess\-control-tag-data:\fR but for interfaces.
.IP
Note that the interface needs to be already specified with \fBinterface:\fR
and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR
settings for targeted clients.
.TP
.B interface\-view: \fI<ip address or interface name [@port]> <view name>
Similar to \fBaccess\-control-view:\fR but for interfaces.
.IP
Note that the interface needs to be already specified with \fBinterface:\fR
and that any \fBaccess-control*:\fR setting overrides all \fBinterface-*:\fR
settings for targeted clients.
.TP
.B chroot: \fI<directory>
If chroot is enabled, you should pass the configfile (from the
commandline) as a full path from the original root. After the
chroot has been performed the now defunct portion of the config
file path is removed to be able to reread the config after a reload.
.IP
All other file paths (working dir, logfile, roothints, and
key files) can be specified in several ways:
as an absolute path relative to the new root,
as a relative path to the working directory, or
as an absolute path relative to the original root.
In the last case the path is adjusted to remove the unused portion.
.IP
The pidfile can be either a relative path to the working directory, or
an absolute path relative to the original root. It is written just prior
to chroot and dropping permissions. This allows the pidfile to be
/var/run/unbound.pid and the chroot to be /var/unbound, for example. Note that
Unbound is not able to remove the pidfile after termination when it is located
outside of the chroot directory.
.IP
Additionally, Unbound may need to access /dev/urandom (for entropy)
from inside the chroot.
.IP
If given a chroot is done to the given directory. By default chroot is
enabled and the default is "@UNBOUND_CHROOT_DIR@". If you give "" no
chroot is performed.
.TP
.B username: \fI<name>
If given, after binding the port the user privileges are dropped. Default is
"@UNBOUND_USERNAME@". If you give username: "" no user change is performed.
.IP
If this user is not capable of binding the
port, reloads (by signal HUP) will still retain the opened ports.
If you change the port number in the config file, and that new port number
requires privileges, then a reload will fail; a restart is needed.
.TP
.B directory: \fI<directory>
Sets the working directory for the program. Default is "@UNBOUND_RUN_DIR@".
On Windows the string "%EXECUTABLE%" tries to change to the directory
that unbound.exe resides in.
If you give a server: directory: dir before include: file statements
then those includes can be relative to the working directory.
.TP
.B logfile: \fI<filename>
If "" is given, logging goes to stderr, or nowhere once daemonized.
The logfile is appended to, in the following format:
.nf
[seconds since 1970] unbound[pid:tid]: type: message.
.fi
If this option is given, the use\-syslog is option is set to "no".
The logfile is reopened (for append) when the config file is reread, on
SIGHUP.
.TP
.B use\-syslog: \fI<yes or no>
Sets Unbound to send log messages to the syslogd, using
\fIsyslog\fR(3).
The log facility LOG_DAEMON is used, with identity "unbound".
The logfile setting is overridden when use\-syslog is turned on.
The default is to log to syslog.
.TP
.B log\-identity: \fI<string>
If "" is given (default), then the name of the executable, usually "unbound"
is used to report to the log. Enter a string to override it
with that, which is useful on systems that run more than one instance of
Unbound, with different configurations, so that the logs can be easily
distinguished against.
.TP
.B log\-time\-ascii: \fI<yes or no>
Sets logfile lines to use a timestamp in UTC ascii. Default is no, which
prints the seconds since 1970 in brackets. No effect if using syslog, in
that case syslog formats the timestamp printed into the log files.
.TP
.B log\-queries: \fI<yes or no>
Prints one line per query to the log, with the log timestamp and IP address,
name, type and class. Default is no. Note that it takes time to print these
lines which makes the server (significantly) slower. Odd (nonprintable)
characters in names are printed as '?'.
.TP
.B log\-replies: \fI<yes or no>
Prints one line per reply to the log, with the log timestamp and IP address,
name, type, class, return code, time to resolve, from cache and response size.
Default is no. Note that it takes time to print these
lines which makes the server (significantly) slower. Odd (nonprintable)
characters in names are printed as '?'.
.TP
.B log\-tag\-queryreply: \fI<yes or no>
Prints the word 'query' and 'reply' with log\-queries and log\-replies.
This makes filtering logs easier. The default is off (for backwards
compatibility).
.TP
.B log\-local\-actions: \fI<yes or no>
Print log lines to inform about local zone actions. These lines are like the
local\-zone type inform prints out, but they are also printed for the other
types of local zones.
.TP
.B log\-servfail: \fI<yes or no>
Print log lines that say why queries return SERVFAIL to clients.
This is separate from the verbosity debug logs, much smaller, and printed
at the error level, not the info level of debug info from verbosity.
.TP
.B pidfile: \fI<filename>
The process id is written to the file. Default is "@UNBOUND_PIDFILE@".
So,
.nf
kill \-HUP `cat @UNBOUND_PIDFILE@`
.fi
triggers a reload,
.nf
kill \-TERM `cat @UNBOUND_PIDFILE@`
.fi
gracefully terminates.
.TP
.B root\-hints: \fI<filename>
Read the root hints from this file. Default is nothing, using builtin hints
for the IN class. The file has the format of zone files, with root
nameserver names and addresses only. The default may become outdated,
when servers change, therefore it is good practice to use a root\-hints file.
.TP
.B hide\-identity: \fI<yes or no>
If enabled id.server and hostname.bind queries are refused.
.TP
.B identity: \fI<string>
Set the identity to report. If set to "", the default, then the hostname
of the server is returned.
.TP
.B hide\-version: \fI<yes or no>
If enabled version.server and version.bind queries are refused.
.TP
.B version: \fI<string>
Set the version to report. If set to "", the default, then the package
version is returned.
.TP
.B hide\-http\-user\-agent: \fI<yes or no>
If enabled the HTTP header User-Agent is not set. Use with caution as some
webserver configurations may reject HTTP requests lacking this header.
If needed, it is better to explicitly set the
.B http\-user\-agent
below.
.TP
.B http\-user\-agent: \fI<string>
Set the HTTP User-Agent header for outgoing HTTP requests. If set to "",
the default, then the package name and version are used.
.TP
.B nsid:\fR <string>
Add the specified nsid to the EDNS section of the answer when queried
with an NSID EDNS enabled packet. As a sequence of hex characters or
with ascii_ prefix and then an ascii string.
.TP
.B hide\-trustanchor: \fI<yes or no>
If enabled trustanchor.unbound queries are refused.
.TP
.B target\-fetch\-policy: \fI<"list of numbers">
Set the target fetch policy used by Unbound to determine if it should fetch
nameserver target addresses opportunistically. The policy is described per
dependency depth.
.IP
The number of values determines the maximum dependency depth
that Unbound will pursue in answering a query.
A value of \-1 means to fetch all targets opportunistically for that dependency
depth. A value of 0 means to fetch on demand only. A positive value fetches
that many targets opportunistically.
.IP
Enclose the list between quotes ("") and put spaces between numbers.
The default is "3 2 1 0 0". Setting all zeroes, "0 0 0 0 0" gives behaviour
closer to that of BIND 9, while setting "\-1 \-1 \-1 \-1 \-1" gives behaviour
rumoured to be closer to that of BIND 8.
.TP
.B harden\-short\-bufsize: \fI<yes or no>
Very small EDNS buffer sizes from queries are ignored. Default is on, as
described in the standard.
.TP
.B harden\-large\-queries: \fI<yes or no>
Very large queries are ignored. Default is off, since it is legal protocol
wise to send these, and could be necessary for operation if TSIG or EDNS
payload is very large.
.TP
.B harden\-glue: \fI<yes or no>
Will trust glue only if it is within the servers authority. Default is yes.
.TP
.B harden\-dnssec\-stripped: \fI<yes or no>
Require DNSSEC data for trust\-anchored zones, if such data is absent,
the zone becomes bogus. If turned off, and no DNSSEC data is received
(or the DNSKEY data fails to validate), then the zone is made insecure,
this behaves like there is no trust anchor. You could turn this off if
you are sometimes behind an intrusive firewall (of some sort) that
removes DNSSEC data from packets, or a zone changes from signed to
unsigned to badly signed often. If turned off you run the risk of a
downgrade attack that disables security for a zone. Default is yes.
.TP
.B harden\-below\-nxdomain: \fI<yes or no>
From RFC 8020 (with title "NXDOMAIN: There Really Is Nothing Underneath"),
returns nxdomain to queries for a name
below another name that is already known to be nxdomain. DNSSEC mandates
noerror for empty nonterminals, hence this is possible. Very old software
might return nxdomain for empty nonterminals (that usually happen for reverse
IP address lookups), and thus may be incompatible with this. To try to avoid
this only DNSSEC-secure nxdomains are used, because the old software does not
have DNSSEC. Default is yes.
The nxdomain must be secure, this means nsec3 with optout is insufficient.
.TP
.B harden\-referral\-path: \fI<yes or no>
Harden the referral path by performing additional queries for
infrastructure data. Validates the replies if trust anchors are configured
and the zones are signed. This enforces DNSSEC validation on nameserver
NS sets and the nameserver addresses that are encountered on the referral
path to the answer.