Provided by: unbound_1.4.16-1_amd64 bug

NAME

       unbound.conf - Unbound configuration file.

SYNOPSIS

       unbound.conf

DESCRIPTION

       unbound.conf  is used to configure unbound(8).  The file format has attributes and values.
       Some attributes have attributes inside them.  The notation is: attribute: value.

       Comments start with # and last to  the  end  of  line.  Empty  lines  are  ignored  as  is
       whitespace at the beginning of a line.

       The utility unbound-checkconf(8) can be used to check unbound.conf prior to usage.

EXAMPLE

       An  example  config  file is shown below. Copy this to /etc/unbound/unbound.conf and start
       the server with:

            $ unbound -c /etc/unbound/unbound.conf

       Most settings are the defaults. Stop the server with:

            $ kill `cat /etc/unbound/unbound.pid`

       Below is a minimal config file. The source distribution contains an extensive example.conf
       file with all the options.

       # 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/random /etc/unbound/dev/random
            # 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

FILE FORMAT

       There  must  be  whitespace  between keywords. Attribute keywords end with a colon ':'. An
       attribute is followed by its containing attributes, or a value.

       Files can be included using the include: directive. It can appear anywhere,  and  takes  a
       single  filename  as  an  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.

   Server Options
       These options are part of the server: clause.

       verbosity: <number>
              The verbosity number, level 0 means  no  verbosity,  only  errors.  Level  1  gives
              operational  information.  Level  2 gives detailed operational information. 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 unbound(8).

       statistics-interval: <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.

       statistics-cumulative: <yes or no>
              If enabled, statistics are cumulative since starting unbound, without clearing  the
              statistics counters after logging the statistics. Default is no.

       extended-statistics: <yes or no>
              If  enabled,  extended  statistics are printed from unbound-control(8).  Default is
              off, because keeping track of more statistics takes time.  The counters are  listed
              in unbound-control(8).

       num-threads: <number>
              The number of threads to create to serve clients. Use 1 for no threading.

       port: <port number>
              The port number, default 53, on which the server responds to queries.

       interface: <ip address[@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.  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 port) is used.

       interface-automatic: <yes or no>
              Detect source interface on UDP queries and copy them to replies.  This  feature  is
              experimental,  and needs support in your OS for particular socket options.  Default
              value is no.

       outgoing-interface: <ip address>
              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  interface:  and  outgoing-interface: lines, the
              interfaces are then used for both purposes. Outgoing queries are sent via a  random
              outgoing interface to counter spoofing.

       outgoing-range: <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 a very large value is best,
              use libevent to make this possible.

       outgoing-port-permit: <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.

              The outgoing-port-permit and outgoing-port-avoid 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.

       outgoing-port-avoid: <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.

       outgoing-num-tcp: <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.

       incoming-num-tcp: <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.

       edns-buffer-size: <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 lower than that
              value.  Default is 4096 which  is  RFC  recommended.   If  you  have  fragmentation
              reassembly  problems,  usually  seen  as timeouts, then a value of 1480 can fix it.
              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).

       msg-buffer-size: <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.

       msg-cache-size: <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).

       msg-cache-slabs: <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.

       num-queries-per-thread: <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
              jostle-timeout),  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.

       jostle-timeout: <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.

       so-rcvbuf: <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.

       so-sndbuf: <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.

       rrset-cache-size: <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).

       rrset-cache-slabs: <number>
              Number  of slabs in the RRset cache. Slabs reduce lock contention by threads.  Must
              be set to a power of 2.

       cache-max-ttl: <seconds>
              Time to live maximum for RRsets and messages in the cache. Default is 86400 seconds
              (1  day). If the maximum kicks in, responses to clients still get decrementing TTLs
              based on the original (larger) values.  When the internal 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.

       cache-min-ttl: <seconds>
              Time to live minimum for RRsets and messages in the cache. Default is  0.   If  the
              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.

       infra-host-ttl: <seconds>
              Time  to  live  for  entries  in  the host cache. The host cache contains roundtrip
              timing, lameness and EDNS support information. Default is 900.

       infra-cache-slabs: <number>
              Number of slabs in the  infrastructure  cache.  Slabs  reduce  lock  contention  by
              threads. Must be set to a power of 2.

       infra-cache-numhosts: <number>
              Number of hosts for which information is cached. Default is 10000.

       do-ip4: <yes or no>
              Enable or disable whether ip4 queries are answered or issued. Default is yes.

       do-ip6: <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.

       do-udp: <yes or no>
              Enable or disable whether UDP queries are answered or issued. Default is yes.

       do-tcp: <yes or no>
              Enable or disable whether TCP queries are answered or issued. Default is yes.

       tcp-upstream: <yes or no>
              Enable or disable whether the upstream queries use TCP only for transport.  Default
              is no.  Useful in tunneling scenarios.

       ssl-upstream: <yes or no>
              Enabled or disable whether  the  upstream  queries  use  SSL  only  for  transport.
              Default  is  no.  Useful in tunneling scenarios.  The SSL contains plain DNS in TCP
              wireformat.  The other server must support this (see ssl-service-key).

       ssl-service-key: <file>
              If enabled, the server provider SSL service on its TCP sockets.  The  clients  have
              to  use  ssl-upstream:  yes.  The file is the private key for the TLS session.  The
              public certificate is in the ssl-service-pem file.   Default  is  "",  turned  off.
              Requires  a restart (a reload is not enough) if changed, because the private key is
              read while root permissions are held and before chroot (if any).   Normal  DNS  TCP
              service is not provided and gives errors, this service is best run with a different
              port: config or @port suffixes in the interface config.

       ssl-service-pem: <file>
              The public key certificate pem file for the ssl service.   Default  is  "",  turned
              off.

       ssl-port: <number>
              The  port  number on which to provide TCP SSL service, default 443, only interfaces
              configured with that port number as @number get the SSL service.

       do-daemonize: <yes or no>
              Enable or disable whether the unbound server forks into the background as a daemon.
              Default is yes.

       access-control: <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 deny, refuse, allow or allow_snoop.

              The action deny stops queries from hosts from that netblock.

              The action refuse stops queries too, but sends a DNS rcode  REFUSED  error  message
              back.

              The  action allow 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.

              The  allow  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.

              The action allow_snoop gives nonrecursive access too.  This give both recursive and
              non recursive access.  The name allow_snoop 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  allow_snoop  for  your
              administration host.

              By default only localhost is allowed, the rest is refused.  The default is refused,
              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.

       chroot: <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.

              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.

              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.

              Additionally, unbound may need to access /dev/random (for entropy) from inside  the
              chroot.

              If given a chroot is done to the given directory. The default is "/etc/unbound". If
              you give "" no chroot is performed.

       username: <name>
              If given, after binding the port  the  user  privileges  are  dropped.  Default  is
              "unbound". If you give username: "" no user change is performed.

              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.

       directory: <directory>
              Sets the working directory for the program. Default is "/etc/unbound".

       logfile: <filename>
              If "" is given, logging goes to stderr, or nowhere once daemonized.  The logfile is
              appended to, in the following format:
              [seconds since 1970] unbound[pid:tid]: type: message.
              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.

       use-syslog: <yes or no>
              Sets unbound to send log  messages  to  the  syslogd,  using  syslog(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.

       log-time-ascii: <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.

       log-queries: <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 '?'.

       pidfile: <filename>
              The process id is written to the file. Default is "/etc/unbound/unbound.pid".  So,
              kill -HUP `cat /etc/unbound/unbound.pid`
              triggers a reload,
              kill -QUIT `cat /etc/unbound/unbound.pid`
              gracefully terminates.

       root-hints: <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.

       hide-identity: <yes or no>
              If enabled id.server and hostname.bind queries are refused.

       identity: <string>
              Set the identity to report. If set to "", the default, then  the  hostname  of  the
              server is returned.

       hide-version: <yes or no>
              If enabled version.server and version.bind queries are refused.

       version: <string>
              Set  the  version to report. If set to "", the default, then the package version is
              returned.

       target-fetch-policy: <"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.

              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.

              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.

       harden-short-bufsize: <yes or no>
              Very small EDNS buffer sizes from queries are ignored. Default is off, since it  is
              legal  protocol wise to send these, and unbound tries to give very small answers to
              these queries, where possible.

       harden-large-queries: <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.

       harden-glue: <yes or no>
              Will trust glue only if it is within the servers authority. Default is on.

       harden-dnssec-stripped: <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 on.

       harden-below-nxdomain: <yes or no>
              From draft-vixie-dnsext-resimprove, 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 off.

       harden-referral-path: <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.  Default off, because it
              burdens the authority servers, and it is  not  RFC  standard,  and  could  lead  to
              performance   problems   because  of  the  extra  query  load  that  is  generated.
              Experimental option.  If you enable it  consider  adding  more  numbers  after  the
              target-fetch-policy to increase the max depth that is checked to.

       use-caps-for-id: <yes or no>
              Use  0x20-encoded  random  bits in the query to foil spoof attempts.  This perturbs
              the lowercase and uppercase of query names sent to authority servers and checks  if
              the  reply  still has the correct casing.  Disabled by default.  This feature is an
              experimental implementation of draft dns-0x20.

       private-address: <IP address or subnet>
              Give IPv4 of IPv6 addresses or classless  subnets.  These  are  addresses  on  your
              private network, and are not allowed to be returned for public internet names.  Any
              occurence of such addresses are removed from DNS answers. Additionally, the  DNSSEC
              validator  may  mark  the  answers  bogus.  This  protects  against  so-called  DNS
              Rebinding, where a user browser is turned into a  network  proxy,  allowing  remote
              access  through the browser to other parts of your private network.  Some names can
              be allowed to contain your private addresses, by default all  the  local-data  that
              you  configured  is  allowed  to,  and  you  can  specify  additional  names  using
              private-domain.  No private addresses are  enabled  by  default.   We  consider  to
              enable  this for the RFC1918 private IP address space by default in later releases.
              That would enable private addresses  for  10.0.0.0/8  172.16.0.0/12  192.168.0.0/16
              169.254.0.0/16  fd00::/8 and fe80::/10, since the RFC standards say these addresses
              should not be visible on the public internet.  Turning on 127.0.0.0/8 would  hinder
              many spamblocklists as they use that.

       private-domain: <domain name>
              Allow  this  domain,  and  all  its  subdomains to contain private addresses.  Give
              multiple times to allow multiple domain names to contain private addresses. Default
              is none.

       unwanted-reply-threshold: <number>
              If  set, a total number of unwanted replies is kept track of in every thread.  When
              it reaches the threshold, a defensive action is taken and a warning is  printed  to
              the  log.  The defensive action is to clear the rrset and message caches, hopefully
              flushing away any poison.  A value of  10  million  is  suggested.   Default  is  0
              (turned off).

       do-not-query-address: <IP address>
              Do  not  query  the  given IP address. Can be IP4 or IP6. Append /num to indicate a
              classless delegation netblock, for example like 10.2.3.4/24 or 2001::11/64.

       do-not-query-localhost: <yes or no>
              If yes, localhost is added to the do-not-query-address entries, both  IP6  ::1  and
              IP4  127.0.0.1/8.  If no, then localhost can be used to send queries to. Default is
              yes.

       prefetch: <yes or no>
              If yes, message cache elements are prefetched before they expire to keep the  cache
              up  to date.  Default is no.  Turning it on gives about 10 percent more traffic and
              load on the machine, but popular items do not expire from the cache.

       prefetch-key: <yes or no>
              If yes, fetch the DNSKEYs earlier in the validation process, when a  DS  record  is
              encountered.   This lowers the latency of requests.  It does use a little more CPU.
              Also if the cache is set to 0, it is no use. Default is no.

       module-config: <"module names">
              Module configuration, a list of module names  separated  by  spaces,  surround  the
              string  with  quotes (""). The modules can be validator, iterator.  Setting this to
              "iterator" will result in a non-validating  server.   Setting  this  to  "validator
              iterator"  will  turn  on  DNSSEC  validation.   The  ordering  of  the  modules is
              important.  You must also set trust-anchors for validation to be useful.

       trust-anchor-file: <filename>
              File with trusted keys for validation. Both DS and DNSKEY entries can appear in the
              file.  The format of the file is the standard DNS Zone file format.  Default is "",
              or no trust anchor file.

       auto-trust-anchor-file: <filename>
              File with trust anchor for one zone, which is tracked  with  RFC5011  probes.   The
              probes  are  several  times  per month, thus the machine must be online frequently.
              The initial file can be one with contents as described in  trust-anchor-file.   The
              file  is written to when the anchor is updated, so the unbound user must have write
              permission.

       trust-anchor: <"Resource Record">
              A DS or DNSKEY RR for a key to use for validation. Multiple entries can be given to
              specify multiple trusted keys, in addition to the trust-anchor-files.  The resource
              record is entered in the same format as 'dig' or  'drill'  prints  them,  the  same
              format  as  in  the zone file. Has to be on a single line, with "" around it. A TTL
              can be specified for ease of cut and  paste,  but  is  ignored.   A  class  can  be
              specified, but class IN is default.

       trusted-keys-file: <filename>
              File  with  trusted  keys  for  validation. Specify more than one file with several
              entries, one file per entry.  Like  trust-anchor-file  but  has  a  different  file
              format.  Format  is  BIND-9  style  format, the trusted-keys { name flag proto algo
              "key"; }; clauses are read.  It is possible to use wildcards with  this  statement,
              the wildcard is expanded on start and on reload.

       dlv-anchor-file: <filename>
              File  with  trusted  keys for DLV (DNSSEC Lookaside Validation). Both DS and DNSKEY
              entries can be used in the file, in  the  same  format  as  for  trust-anchor-file:
              statements.  Only one DLV can be configured, more would be slow. The DLV configured
              is used as a root trusted DLV, this means that it is  a  lookaside  for  the  root.
              Default is "", or no dlv anchor file.

       dlv-anchor: <"Resource Record">
              Much like trust-anchor, this is a DLV anchor with the DS or DNSKEY inline.

       domain-insecure: <domain name>
              Sets  domain  name  to  be  insecure,  DNSSEC chain of trust is ignored towards the
              domain name.  So a trust anchor above the domain  name  can  not  make  the  domain
              secure  with a DS record, such a DS record is then ignored.  Also keys from DLV are
              ignored for the domain.  Can be given multiple times to  specify  multiple  domains
              that  are  treated  as  if  unsigned.  If you set trust anchors for the domain they
              override this setting (and the domain is secured).

              This can be useful if you want to make sure a trust  anchor  for  external  lookups
              does  not  affect an (unsigned) internal domain.  A DS record externally can create
              validation failures for that internal domain.

       val-override-date: <rrsig-style date spec>
              Default is "" or "0", which disables this debugging feature. If enabled by giving a
              RRSIG  style  date,  that date is used for verifying RRSIG inception and expiration
              dates, instead of the current date. Do  not  set  this  unless  you  are  debugging
              signature  inception  and  expiration.  The  value  -1 ignores the date altogether,
              useful for some special applications.

       val-sig-skew-min: <seconds>
              Minimum number of seconds of clock skew to apply to validated signatures.  A  value
              of  10%  of the signature lifetime (expiration - inception) is used, capped by this
              setting.  Default is 3600 (1 hour) which allows for daylight  savings  differences.
              Lower this value for more strict checking of short lived signatures.

       val-sig-skew-max: <seconds>
              Maximum  number of seconds of clock skew to apply to validated signatures.  A value
              of 10% of the signature lifetime (expiration - inception) is used, capped  by  this
              setting.  Default is 86400 (24 hours) which allows for timezone setting problems in
              stable domains.  Setting both  min  and  max  very  low  disables  the  clock  skew
              allowances.   Setting  both  min  and  max  very high makes the validator check the
              signature timestamps less strictly.

       val-bogus-ttl: <number>
              The time to live for bogus data. This is data that has failed  validation;  due  to
              invalid  signatures  or other checks. The TTL from that data cannot be trusted, and
              this value is used instead. The value is in seconds, default 60.  The time interval
              prevents repeated revalidation of bogus data.

       val-clean-additional: <yes or no>
              Instruct  the  validator  to  remove  data  from  the  additional section of secure
              messages  that  are  not  signed  properly.  Messages  that  are  insecure,  bogus,
              indeterminate  or  unchecked  are not affected. Default is yes. Use this setting to
              protect the users that rely on this validator for authentication from  protentially
              bad data in the additional section.

       val-log-level: <number>
              Have  the  validator  print  validation  failures  to  the  log.  Regardless of the
              verbosity setting.  Default is 0, off.  At 1, for every user  query  that  fails  a
              line  is  printed  to  the  logs.   This  way  you  can  monitor  what happens with
              validation.  Use a diagnosis tool, such as dig or drill, to find out why validation
              is  failing for these queries.  At 2, not only the query that failed is printed but
              also the reason why unbound thought it was wrong and which server sent  the  faulty
              data.

       val-permissive-mode: <yes or no>
              Instruct the validator to mark bogus messages as indeterminate. The security checks
              are performed, but if the result is bogus  (failed  security),  the  reply  is  not
              withheld  from  the  client  with  SERVFAIL as usual. The client receives the bogus
              data. For messages that are found to be secure the AD bit is set in  replies.  Also
              logging is performed as for full validation.  The default value is "no".

       ignore-cd-flag: <yes or no>
              Instruct  unbound  to  ignore  the  CD flag from clients and refuse to return bogus
              answers to them.  Thus, the CD (Checking Disabled) flag does not  disable  checking
              any more.  This is useful if legacy (w2008) servers that set the CD flag but cannot
              validate DNSSEC themselves are the clients, and then  unbound  provides  them  with
              DNSSEC protection.  The default value is "no".

       val-nsec3-keysize-iterations: <"list of values">
              List  of  keysize  and  iteration  count values, separated by spaces, surrounded by
              quotes. Default is "1024 150 2048 500  4096  2500".  This  determines  the  maximum
              allowed NSEC3 iteration count before a message is simply marked insecure instead of
              performing the many hashing iterations. The list must be  in  ascending  order  and
              have  at  least one entry. If you set it to "1024 65535" there is no restriction to
              NSEC3 iteration values.  This table must be kept short;  a  very  long  list  could
              cause slower operation.

       add-holddown: <seconds>
              Instruct  the  auto-trust-anchor-file probe mechanism for RFC5011 autotrust updates
              to add new trust anchors only after they have been visible for this time.   Default
              is 30 days as per the RFC.

       del-holddown: <seconds>
              Instruct  the  auto-trust-anchor-file probe mechanism for RFC5011 autotrust updates
              to remove revoked trust anchors after they have been kept in the revoked  list  for
              this long.  Default is 30 days as per the RFC.

       keep-missing: <seconds>
              Instruct  the  auto-trust-anchor-file probe mechanism for RFC5011 autotrust updates
              to remove missing trust anchors after they have been unseen for  this  long.   This
              cleans  up  the  state  file  if  the  target  zone  does  not perform trust anchor
              revocation, so this makes the auto probe mechanism work  with  zones  that  perform
              regular  (non-5011)  rollovers.   The  default  is  366 days.  The value 0 does not
              remove missing anchors, as per the RFC.

       key-cache-size: <number>
              Number of bytes size of the key 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).

       key-cache-slabs: <number>
              Number of slabs in the key 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.

       neg-cache-size: <number>
              Number  of  bytes  size of the aggressive negative cache. Default is 1 megabyte.  A
              plain number is in bytes, append 'k',  'm'  or  'g'  for  kilobytes,  megabytes  or
              gigabytes (1024*1024 bytes in a megabyte).

       local-zone: <zone> <type>
              Configure a local zone. The type determines the answer to give if there is no match
              from local-data.  The  types  are  deny,  refuse,  static,  transparent,  redirect,
              nodefault,  typetransparent,  and  are  explained  below.  After  that  the default
              settings are listed. Use local-data: to enter data into the local zone. Answers for
              local zones are authoritative DNS answers. By default the zones are class IN.

              If  you  need  more  complicated  authoritative  data,  with  referrals, wildcards,
              CNAME/DNAME support, or DNSSEC authoritative service, setup a stub-zone for  it  as
              detailed in the stub zone section below.

            deny Do not send an answer, drop the query.  If there is a match from local data, the
                 query is answered.

            refuse
                 Send an error message reply, with rcode REFUSED.  If there is a match from local
                 data, the query is answered.

            static
                 If  there  is  a  match  from local data, the query is answered.  Otherwise, the
                 query is answered with nodata or nxdomain.  For  a  negative  answer  a  SOA  is
                 included in the answer if present as local-data for the zone apex domain.

            transparent
                 If  there  is  a match from local data, the query is answered.  Otherwise if the
                 query has a different name, the query is resolved normally.  If the query is for
                 a name given in localdata but no such type of data is given in localdata, then a
                 noerror nodata answer is returned.  If no local-zone is given local-data  causes
                 a transparent zone to be created by default.

            typetransparent
                 If there is a match from local data, the query is answered.  If the query is for
                 a different name, or for the same name but for a different type,  the  query  is
                 resolved  normally.  So, similar to transparent but types that are not listed in
                 local data are resolved normally, so if an A record is in the  local  data  that
                 does not cause a nodata reply for AAAA queries.

            redirect
                 The  query  is  answered from the local data for the zone name.  There may be no
                 local data beneath the zone name.  This answers queries for the  zone,  and  all
                 subdomains  of  the  zone  with  the local data for the zone.  It can be used to
                 redirect a domain to return a different address record to  the  end  user,  with
                 local-zone:  "example.com."  redirect and local-data: "example.com. A 127.0.0.1"
                 queries for www.example.com and  www.foo.example.com  are  redirected,  so  that
                 users with web browsers cannot access sites with suffix example.com.

            nodefault
                 Used to turn off default contents for AS112 zones. The other types also turn off
                 default contents for the zone. The 'nodefault' option has no other  effect  than
                 turning off default contents for the given zone.

       The default zones are localhost, reverse 127.0.0.1 and ::1, and the AS112 zones. The AS112
       zones are reverse DNS zones for private use  and  reserved  IP  addresses  for  which  the
       servers  on the internet cannot provide correct answers. They are configured by default to
       give nxdomain (no reverse  information)  answers.  The  defaults  can  be  turned  off  by
       specifying  your  own  local-zone  of that name, or using the 'nodefault' type. Below is a
       list of the default zone contents.

            localhost
                 The IP4 and IP6 localhost information is given. NS and SOA records are  provided
                 for completeness and to satisfy some DNS update tools. Default content:
                 local-zone: "localhost." static
                 local-data: "localhost. 10800 IN NS localhost."
                 local-data: "localhost. 10800 IN
                     SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
                 local-data: "localhost. 10800 IN A 127.0.0.1"
                 local-data: "localhost. 10800 IN AAAA ::1"

            reverse IPv4 loopback
                 Default content:
                 local-zone: "127.in-addr.arpa." static
                 local-data: "127.in-addr.arpa. 10800 IN NS localhost."
                 local-data: "127.in-addr.arpa. 10800 IN
                     SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
                 local-data: "1.0.0.127.in-addr.arpa. 10800 IN
                     PTR localhost."

            reverse IPv6 loopback
                 Default content:
                 local-zone: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
                     0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa." static
                 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
                     0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
                     NS localhost."
                 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
                     0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
                     SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"
                 local-data: "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
                     0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa. 10800 IN
                     PTR localhost."

            reverse RFC1918 local use zones
                 Reverse    data    for    zones    10.in-addr.arpa,    16.172.in-addr.arpa    to
                 31.172.in-addr.arpa, 168.192.in-addr.arpa.  The local-zone: is set static and as
                 local-data: SOA and NS records are provided.

            reverse RFC3330 IP4 this, link-local, testnet and broadcast
                 Reverse     data     for     zones     0.in-addr.arpa,     254.169.in-addr.arpa,
                 2.0.192.in-addr.arpa  (TEST  NET  1),  100.51.198.in-addr.arpa  (TEST  NET   2),
                 113.0.203.in-addr.arpa (TEST NET 3), 255.255.255.255.in-addr.arpa.

            reverse RFC4291 IP6 unspecified
                 Reverse data for zone
                 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.
                 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa.

            reverse RFC4193 IPv6 Locally Assigned Local Addresses
                 Reverse data for zone D.F.ip6.arpa.

            reverse RFC4291 IPv6 Link Local Addresses
                 Reverse data for zones 8.E.F.ip6.arpa to B.E.F.ip6.arpa.

            reverse IPv6 Example Prefix
                 Reverse  data for zone 8.B.D.0.1.0.0.2.ip6.arpa. This zone is used for tutorials
                 and examples. You can remove the block on this zone with:
                   local-zone: 8.B.D.0.1.0.0.2.ip6.arpa. nodefault
                 You can also selectively unblock  a  part  of  the  zone  by  making  that  part
                 transparent with a local-zone statement.  This also works with the other default
                 zones.

       local-data: "<resource record string>"
            Configure local data, which is served in reply to queries for it.  The query  has  to
            match  exactly  unless  you  configure  the  local-zone  as  redirect. If not matched
            exactly,  the  local-zone  type  determines  further  processing.  If  local-data  is
            configured  that  is  not  a  subdomain  of a local-zone, a transparent local-zone is
            configured.  For record types such as TXT,  use  single  quotes,  as  in  local-data:
            'example. TXT "text"'.

            If   you  need  more  complicated  authoritative  data,  with  referrals,  wildcards,
            CNAME/DNAME support, or DNSSEC authoritative service, setup a  stub-zone  for  it  as
            detailed in the stub zone section below.

       local-data-ptr: "IPaddr name"
            Configure  local  data  shorthand  for  a  PTR  record with the reversed IPv4 or IPv6
            address and the host name.  For example  "192.0.2.4  www.example.com".   TTL  can  be
            inserted like this: "2001:DB8::4 7200 www.example.com"

   Remote Control Options
       In  the  remote-control:  clause are the declarations for the remote control facility.  If
       this is enabled, the unbound-control(8) utility can  be  used  to  send  commands  to  the
       running unbound server.  The server uses these clauses to setup SSLv3 / TLSv1 security for
       the connection.  The unbound-control(8) utility also reads the remote-control section  for
       options.   To  setup the correct self-signed certificates use the unbound-control-setup(8)
       utility.

       control-enable: <yes or no>
            The option is used to enable remote control, default is "yes".  If  turned  off,  the
            server does not listen for control commands.

       control-interface: <ip address>
            Give  IPv4 or IPv6 addresses to listen on for control commands.  By default localhost
            (127.0.0.1 and ::1) is listened to.  Use 0.0.0.0 and ::0 to listen to all interfaces.

       control-port: <port number>
            The port number to listen on for control commands, default is 8953.   If  you  change
            this  port  number,  and permissions have been dropped, a reload is not sufficient to
            open the port again, you must then restart.

       server-key-file: <private key file>
            Path to the  server  private  key,  by  default  unbound_server.key.   This  file  is
            generated  by  the  unbound-control-setup  utility.  This file is used by the unbound
            server, but not by unbound-control.

       server-cert-file: <certificate file.pem>
            Path to the server self signed certificate, by default unbound_server.pem.  This file
            is  generated by the unbound-control-setup utility.  This file is used by the unbound
            server, and also by unbound-control.

       control-key-file: <private key file>
            Path to the control client private key, by default unbound_control.key.  This file is
            generated   by   the   unbound-control-setup   utility.    This   file   is  used  by
            unbound-control.

       control-cert-file: <certificate file.pem>
            Path to  the  control  client  certificate,  by  default  unbound_control.pem.   This
            certificate  has to be signed with the server certificate.  This file is generated by
            the unbound-control-setup utility.  This file is used by unbound-control.

   Stub Zone Options
       There may be multiple stub-zone: clauses. Each with a name: and zero or more hostnames  or
       IP  addresses.   For  the stub zone this list of nameservers is used. Class IN is assumed.
       The servers should be authority servers, not recursors;  unbound  performs  the  recursive
       processing itself for stub zones.

       The  stub zone can be used to configure authoritative data to be used by the resolver that
       cannot be accessed using the public internet servers.  This is  useful  for  company-local
       data  or  private  zones.  Setup an authoritative server on a different host (or different
       port). Enter a config entry for unbound with stub-addr: <ip address of host[@port]>.   The
       unbound  resolver  can  then access the data, without referring to the public internet for
       it.

       This setup allows DNSSEC signed zones to be served by that authoritative server, in  which
       case  a  trusted  key  entry with the public key can be put in config, so that unbound can
       validate the data and set the AD bit  on  replies  for  the  private  zone  (authoritative
       servers do not set the AD bit).  This setup makes unbound capable of answering queries for
       the private zone, and can even set the AD bit ('authentic'), but the AA  ('authoritative')
       bit is not set on these replies.

       name: <domain name>
              Name of the stub zone.

       stub-host: <domain name>
              Name of stub zone nameserver. Is itself resolved before it is used.

       stub-addr: <IP address>
              IP  address of stub zone nameserver. Can be IP 4 or IP 6.  To use a nondefault port
              for DNS communication append '@' with the port number.

       stub-prime: <yes or no>
              This option is by default off.  If enabled it performs NS  set  priming,  which  is
              similar  to  root  hints,  where  it starts using the list of nameservers currently
              published by the zone.  Thus, if the hint list is slightly outdated,  the  resolver
              picks up a correct list online.

   Forward Zone Options
       There  may be multiple forward-zone: clauses. Each with a name: and zero or more hostnames
       or IP addresses.  For the forward zone this list of nameservers is  used  to  forward  the
       queries  to.  The servers listed as forward-host: and forward-addr: have to handle further
       recursion for the query.  Thus, those servers are not authority  servers,  but  are  (just
       like  unbound is) recursive servers too; unbound does not perform recursion itself for the
       forward zone, it lets the remote server do it.  Class IN is assumed.  A forward-zone entry
       with  name  "."  and  a  forward-addr target will forward all queries to that other server
       (unless it can answer from the cache).

       name: <domain name>
              Name of the forward zone.

       forward-host: <domain name>
              Name of server to forward to. Is itself resolved before it is used.

       forward-addr: <IP address>
              IP address of server to forward to. Can be IP 4 or IP 6.  To use a nondefault  port
              for DNS communication append '@' with the port number.

   Python Module Options
       The  python:  clause gives the settings for the python(1) script module.  This module acts
       like the iterator and validator modules do, on queries and answers.  To enable the  script
       module  it  has to be compiled into the daemon, and the word "python" has to be put in the
       module-config: option (usually first, or between the validator and iterator).

       python-script: <python file>
              The script file to load.

MEMORY CONTROL EXAMPLE

       In the example config settings below memory usage is  reduced.  Some  service  levels  are
       lower,  notable  very  large  data and a high TCP load are no longer supported. Very large
       data and high TCP loads are exceptional for the DNS.  DNSSEC validation is  enabled,  just
       add  trust  anchors.   If  you do not have to worry about programs using more than 3 Mb of
       memory, the below example is not for you. Use the defaults to receive full service,  which
       on BSD-32bit tops out at 30-40 Mb after heavy usage.

       # example settings that reduce memory usage
       server:
            num-threads: 1
            outgoing-num-tcp: 1 # this limits TCP service, uses less buffers.
            incoming-num-tcp: 1
            outgoing-range: 60  # uses less memory, but less performance.
            msg-buffer-size: 8192   # note this limits service, 'no huge stuff'.
            msg-cache-size: 100k
            msg-cache-slabs: 1
            rrset-cache-size: 100k
            rrset-cache-slabs: 1
            infra-cache-numhosts: 200
            infra-cache-slabs: 1
            key-cache-size: 100k
            key-cache-slabs: 1
            neg-cache-size: 10k
            num-queries-per-thread: 30
            target-fetch-policy: "2 1 0 0 0 0"
            harden-large-queries: "yes"
            harden-short-bufsize: "yes"

FILES

       /etc/unbound
              default unbound working directory.

       /etc/unbound
              default chroot(2) location.

       /etc/unbound/unbound.conf
              unbound configuration file.

       /etc/unbound/unbound.pid
              default unbound pidfile with process ID of the running daemon.

       unbound.log
              unbound log file. default is to log to syslog(3).

SEE ALSO

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

AUTHORS

       Unbound was written by NLnet Labs. Please see CREDITS file in the distribution for further
       details.