diff options
| -rw-r--r-- | doc/Makefile.am | 10 | ||||
| -rw-r--r-- | doc/conf.py.in | 20 | ||||
| -rw-r--r-- | doc/configuration.rst | 792 | ||||
| -rw-r--r-- | doc/installation.rst | 82 | ||||
| -rw-r--r-- | doc/introduction.rst | 24 | ||||
| -rw-r--r-- | doc/migration.rst | 14 | ||||
| -rw-r--r-- | doc/reference.rst | 1531 | ||||
| -rw-r--r-- | doc/requirements.rst | 19 | ||||
| -rw-r--r-- | doc/running.rst | 57 | ||||
| -rw-r--r-- | doc/troubleshooting.rst | 80 | ||||
| -rw-r--r-- | man/knot.conf.5.in | 1338 | ||||
| -rw-r--r-- | man/knotc.8.in | 17 | ||||
| -rw-r--r-- | man/knotd.8.in | 12 | ||||
| -rwxr-xr-x | scripts/update-man.sh | 14 |
14 files changed, 2124 insertions, 1886 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 1bef0b237..735dbcf77 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -15,7 +15,7 @@ EXTRA_DIST = \ SPHINXBUILDDIR = _build ALLSPHINXOPTS = -n -d $(SPHINXBUILDDIR)/doctrees -D latex_paper_size=a4 $(SPHINXOPTS) . -.PHONY: html-local singlehtml pdf-local info-local +.PHONY: html-local singlehtml pdf-local info-local man if HAVE_DOCS @@ -37,7 +37,6 @@ pdf-local: $(MAKE) -C $(SPHINXBUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(SPHINXBUILDDIR)/latex." else -pdf: @echo "You need to install pdflatex and re-run configure to be" @echo "able to generate PDF documentation." endif @@ -53,8 +52,13 @@ else @echo "able to generate info pages." endif +man: + $(SPHINXBUILD) -b man -D version="__VERSION__" -D today="__DATE__" $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/man + @echo + @echo "Build finished. The man pages are in $(SPHINXBUILDDIR)/man." + else -html-local singlehtml pdf-local info-local: +html-local singlehtml pdf-local info-local man: @echo "Please install sphinx (python-sphinx) to generate Knot DNS documentation." endif diff --git a/doc/conf.py.in b/doc/conf.py.in index 7eab8512f..70b1cd873 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -40,8 +40,9 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'Knot DNS' -copyright = "%d, CZ.NIC, z.s.p.o." % time.localtime().tm_year +project = 'Knot DNS' +copyright = 'Copyright 2010-%d, CZ.NIC, z.s.p.o.' % time.localtime().tm_year +author = 'CZ.NIC Labs <http://www.knot-dns.cz>' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -189,8 +190,7 @@ latex_elements = { # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'KnotDNS.tex', u'Knot DNS Documentation', - u'CZ.NIC, z.s.p.o.', 'manual'), + ('index', 'KnotDNS.tex', 'Knot DNS Documentation', copyright, 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -218,10 +218,9 @@ latex_domain_indices = False # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -#man_pages = [ -# ('index', 'knotdns', u'Knot DNS Documentation', -# [u'CZ.NIC, z.s.p.o.'], 1) -#] +man_pages = [ + ('reference', 'knot.conf', 'Knot DNS configuration file', author, 5) +] # If true, show URL addresses after external links. #man_show_urls = False @@ -233,10 +232,7 @@ latex_domain_indices = False # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'KnotDNS', u'Knot DNS Documentation', - u'CZ.NIC, z.s.p.o.', 'KnotDNS', - 'High-performance authoritative DNS server implementation', - 'Miscellaneous'), + ('index', 'KnotDNS', 'Knot DNS Documentation', author) ] # Documents to append as an appendix to all manuals. diff --git a/doc/configuration.rst b/doc/configuration.rst index fc6f9a8f3..c65a483e7 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -1,285 +1,285 @@ .. meta:: :description: reStructuredText plaintext markup language -********************** -Knot DNS Configuration -********************** +.. _Configuration: -In this chapter we provide suggested configurations and explain the -meaning of individual configuration options. +************* +Configuration +************* -Minimal configuration -===================== - -The following configuration presents a minimal configuration file -which can be used as a base for your Knot DNS setup:: - - interfaces { - all_ipv4 { - address 0.0.0.0; - port 53; - } - all_ipv6 { - address [::]; - port 53; - } - } - - zones { - example.com { - file "/etc/knot/example.com"; - } - } - - log { - syslog { any info; } - } - -Now let's go step by step through this minimal configuration file: - -* The ``interfaces`` statement defines interfaces where Knot - DNS will listen for incoming connections. We have defined two - interfaces: one IPv4 called ``all_ipv4`` explicitly listening - on port 53 and second IPv6 called ``all_ipv6`` also listening on - port 53, which is the default port for the DNS. See :ref:`interfaces`. -* The ``log`` statement defines the log facilities for Knot DNS. - In this example we told Knot DNS to send its log messages with the severity - ``info`` or more serious to the syslog. - If you omit this sections, all severities will be printed - either to ``stdout`` or ``stderr``, and the severities - from the ``warning`` and more serious to syslog. You can find all - possible combinations in the :ref:`log`. -* The ``zones`` statement is probably the most important one, - because it defines the zones that Knot DNS will serve. In its most simple - form you can define a zone by its name and zone file. - -Slave configuration -=================== - -Knot DNS doesn't strictly differ between master and slave zones. The -only requirement is to have ``xfr-in`` ``zones`` statement set for -given zone, thus allowing both incoming XFR from that remote and using -it as the zone master. If ``update-in`` is set and zone has a master, -any accepted DNS UPDATE will be forwarded to master. Also note that -you need to explicitly allow incoming NOTIFY, otherwise the daemon -would reject them. Also, you can specify paths, relative to the -storage directory. See :ref:`zones` and :ref:`storage`. If the zone -file doesn't exist and ``xfr-in`` is set, it will be bootstrapped over -AXFR:: - - remotes { - master { address 127.0.0.1@53; } - subnet1 { address 192.168.1.0/24; } - } - - zones { - example.com { - file "example.com"; # relative to 'storage' - xfr-in master; # define 'master' for this zone - notify-in master; # also allow NOTIFY from 'master' - update-in subnet1; # accept UPDATE msgs from subnet1 and forward - # to master - } - } - -Note that the ``xfr-in`` option accepts a list of multiple remotes. -The first remote in the list is used as a primary master, and the rest is used -for failover should the connection with the primary master fail. -The list is rotated in this case, and a new primary is elected. -The preference list is reset on the configuration reload. - -You can also use TSIG for access control. For this, you need to configure a TSIG key -and assign it to a remote. Supported algorithms for TSIG key are: -``hmac-md5``, ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, -and ``hmac-sha512``. Key secret is written in a base64 encoded format. -As of now, it is not possible to associate multiple keys with a remote. -See :ref:`keys`:: - - keys { - key0 hmac-md5 "Wg=="; # keyname algorithm secret - } - remotes { - master { address 127.0.0.1@53; key key0; } - } - zones { - example.com { - file "example.com"; # relative to 'storage' - xfr-in master; # define 'master' for this zone - notify-in master; # also allow NOTIFY from 'master' - } - } - -If Knot DNS is compiled with the LMDB library, the server will be able to -preserve slave zone timers across full server restarts. The zone expire, -refresh, and flush timers are stored in a file-backed database in the -:ref:`storage` directory in the ``timers`` subdirectory. - -Master configuration +Simple configuration ==================== -You can specify which remotes to allow for outgoing XFR and NOTIFY ``zones``:: - - remotes { - slave { address 127.0.0.1@53; } - any { address 0.0.0.0/0; } - subnet1 { address 192.168.1.0/8; } - subnet2 { address 192.168.2.0/8; } - } - zones { - example.com { - file "/var/zones/example.com"; - xfr-out subnet1, subnet2; # allow outgoing transfers - notify-out slave; - update-in subnet1; # only allow DNS UPDATE from subnet1 - } - } - -You can also secure outgoing XFRs with TSIG:: - - keys { - key0 hmac-md5 "Wg=="; # keyname algorithm secret - } - remotes { - any { address 0.0.0.0/0; key key0; } - } - zones { - example.com { - file "/var/zones/example.com"; - xfr-out any; # uses 'any' remote secured with TSIG key 'key0' - } - } - -Configuring multiple interfaces -=============================== - -Knot DNS support binding to multiple available interfaces in the -``interfaces`` section. You can also use the special addresses for -"any address" like ``0.0.0.0`` or ``[::]``:: - - interfaces { - if1 { address 192.168.1.2@53; } - anyv6 { address [::]@53; } - } - -Using DNS UPDATE -================ - -As noted in examples for master and slave, it is possible to accept -DNS UPDATE messages. When the zone is configured as a slave and DNS -UPDATE messages is accepted, server forwards the message to its -primary master specified by ``xfr-in`` directive. When it receives the -response from primary master, it forwards it back to the -originator. This finishes the transaction. - -However, if the zone is configured as master (i.e. not having any -``xfr-in`` directive), it accepts such an UPDATE and processes it. +The following configuration presents a simple configuration file +which can be used as a base for your Knot DNS setup:: -Remote control interface -======================== + # Example of a very simple Knot DNS configuration. -As of v1.3.0, it is possible to control running daemon using UNIX -sockets, which is also preferred over internet sockets. You don't need -any specific configuration, since it is enabled by default and the -UNIX socket is placed in the rundir. To disable remote control -completely, add an empty ``control`` section to the configuration -like:: + server: + listen: 0.0.0.0@53 + listen: ::@53 - control { } + zone: + - domain: example.com + storage: /var/lib/knot/zones/ + file: example.com.zone -However you can still use IPv4/IPv6 address, although with several -shortcomings. You then can use ``allow`` for an ACL list similar to -``xfr-in`` or ``xfr-out``, see that for syntax reference. The -``listen-on`` has syntax equal to an interface specification, but the -default port for remote control protocol is ``5533``. However keep in -mind, that the transferred data isn't encrypted and could be -susceptible to replay attack in a short timeframe. + log: + - to: syslog + any: info -Example configuration:: +Now let's go step by step through this configuration: - control { - listen-on { address 127.0.0.1@5533; } - } +- The :ref:`server_listen` statement in the :ref:`server section<Server section>` + defines where the server will listen for incoming connections. + We have defined the server to listen on all available IPv4 and IPv6 addresses + all on port 53. +- The :ref:`zone section<Zone section>` defines the zones that the server will + serve. In this case we defined one zone named *example.com* which is stored + in the zone file */var/lib/knot/zones/example.com.zone*. +- The :ref:`log section<Logging section>` defines the log facilities for + the server. In this example we told Knot DNS to send its log messages with + the severity ``info`` or more serious to the syslog. + +For detailed description of all configuration items see +:ref:`Configuration Reference`. + +Zone templates +============== + +A zone template allows single zone configuration to be shared among more zones. +Each template option can be explicitly overridden in the zone configuration. +A ``default`` template identifier is reserved for the default template:: + + template: + - id: default + storage: /var/lib/knot/master + semantic-checks: on + + - id: signed + storage: /var/lib/knot/signed + dnssec-enable: on + semantic-checks: on + + - id: slave + storage: /var/lib/knot/slave + + zone: + - domain: example1.com # Uses default template + + - domain: example2.com # Uses default template + semantic-checks: off # Override default settings + + - domain: example.cz + template: signed + + - domain: example1.eu + template: slave + master: master1 + + - domain: example2.eu + template: slave + master: master2 + +Access control list (ACL) +========================= + +ACL list specifies which remotes are allowed to send the server a specific +query or do a specific action. A remote can be a single IP address or a +network subnet. Also a TSIG key can be specified:: + + acl: + - id: single_rule + address: 192.168.1.1 # Single IP address + action: [notify, update] # Allow zone notifications and updates zone + + - id: subnet_rule + address: 192.168.2.0/24 # Network subnet + action: xfer # Allow zone transfers + + - id: deny_rule + address: 192.168.2.100 # Negative match + action: deny # The remote query is denied + + - id: key_rule + key: key1 # Access based just on TSIG key + action: xfer + +Then the rules are referenced from zone :ref:`template_acl` or from +control :ref:`control_acl`:: + + zone: + - domain: example.com + acl: [single_rule, deny_rule, subnet_rule, key_rule] + +Slave zone +========== + +Knot DNS doesn't strictly differ between master and slave zones. The +only requirement is to have :ref:`master<template_master>` statement set for +the given zone. Also note that you need to explicitly allow incoming zone +changed notifications via ``notify`` :ref:`acl_action` through zone's +:ref:`template_acl` list, otherwise the server reject them. If the zone +file doesn't exist it will be bootstrapped over AXFR:: + + remote: + - id: master + address: 192.168.1.1@53 + + acl: + - id: master_acl + address: 192.168.1.1 + action: notify + + zone: + - domain: example.com + storage: /var/lib/knot/zones/ + # file: example.com.zone # Default value + master: master + acl: master_acl + +Note that the :ref:`template_master` option accepts a list of multiple remotes. +The first remote in the list is used as the primary master, and the rest is used +for failover if the connection with the primary master fails. +The list is rotated in this case, and a new primary is elected. +The preference list is reset on the configuration reload. -Enabling zone semantic checks -============================= +You can also use TSIG for authenticated communication. For this, you need +to configure a key and assign it to the remote and to the proper ACL rule:: + + key: + - id: slave1_key + algorithm: hmac-md5 + secret: Wg== + + remote: + - id: master + address: 192.168.1.1@53 + key: slave1_key + + acl: + - id: master_acl + address: 192.168.1.1 + key: slave1_key + action: notify + +Master zone +=========== + +Master zone often needs to specify who is allowed to transfer the zone. This +is done by defining ACL rules with ``xfer`` action. An ACL rule can consists +of single address or network subnet or/with a TSIG key:: + + remote: + - id: slave1 + address: 192.168.2.1@53 + + acl: + - id: slave1_acl + address: 192.168.2.1 + action: xfer + + - id: others_acl + address: 192.168.3.0/24 + action: xfer + + zone: + - domain: example.com + storage: /var/lib/knot/zones/ + file: example.com.zone + notify: slave1 + acl: [slave1_acl, others_acl] + +And TSIG application:: + + key: + - id: slave1_key + algorithm: hmac-md5 + secret: Wg== + + remote: + - id: slave1 + address: 192.168.2.1@53 + key: slave1_key + + acl: + - id: slave1_acl + address: 192.168.2.1 + key: slave1_key + action: xfer + + - id: others_acl + address: 192.168.3.0/24 + action: xfer + +Dynamic updates +=============== + +Dynamic updates for the zone is allowed via proper ACL rule with ``update`` +action. If the zone is configured as a slave and DNS update messages is +accepted, server forwards the message to its primary master. When it +receives the response from primary master, it forwards it back to the +originator. This finishes the transaction. -You can turn on more detailed semantic checks of zone file in this -``zones`` statement :ref:`zones`. Refer to :ref:`zones List of zone -semantic checks` to see which checks are enabled by default and which -are optional. +However, if the zone is configured as master, it accepts such an UPDATE and +processes it:: -Creating IXFR differences from zone file changes -================================================ + acl: + - id: update_acl + address: 192.168.3.0/24 + action: update -If Knot is being run as a master server, feature -``ixfr-from-differences`` can be enabled to create IXFR differences -from changes made to the master zone file. See :ref:`Controlling -running daemon` for more information. For more about ``zones`` -statement see :ref:`zones`. + zone: + - domain: example.com + file: example.com.zone + acl: update_acl -Using Response Rate Limiting -============================ +Response rate limiting +====================== Response rate limiting (RRL) is a method to combat recent DNS -reflection amplification attacks. These attacked rely on the fact +reflection amplification attacks. These attacks rely on the fact that source address of a UDP query could be forged, and without a worldwide deployment of BCP38, such a forgery could not be detected. Attacker could then exploit DNS server responding to every query, potentially flooding the victim with a large unsolicited DNS responses. -As of Knot DNS version 1.2.0, RRL is compiled in, but disabled by -default. You can enable it with the :ref:`rate-limit` option in the -:ref:`system` section. Setting to a value greater than ``0`` means -that every flow is allowed N responses per second, (i.e. ``rate-limit -50;`` means ``50`` responses per second). It is also possible to -configure SLIP interval, which causes every Nth ``blocked`` response to be -slipped as a truncated response. Note that some error responses cannot -be truncated. For more information, refer to the :ref:`rate-limit-slip`. -It is advisable to not set slip interval to a value larger than 2, -as too large slip value means more denial of service for legitimate -requestors, and introduces excessive timeouts during resolution. -On the other hand, slipping truncated answer gives the legitimate -requestors a chance to reconnect over TCP. - -Example configuration:: - - system { - rate-limit 200; # Each flow is allowed to 200 resp. per second - rate-limit-slip 1; # Every response is slipped (default) - } +You can enable RRL with the :ref:`server_rate-limit` option in the +:ref:`server section<Server section>`. Setting to a value greater than ``0`` +means that every flow is allowed N responses per second, (i.e. ``rate-limit +50;`` means ``50`` responses per second). It is also possible to +configure :ref:`server_rate-limit-slip` interval, which causes every Nth +``blocked`` response to be slipped as a truncated response:: + + server: + rate-limit: 200 # Each flow is allowed to 200 resp. per second + rate-limit-slip: 1 # Every response is slipped Automatic DNSSEC signing ======================== -Knot DNS 1.4.0 is the first release to include automatic DNSSEC -signing feature. Automatic DNSSEC signing is currently a technical -preview and there are some limitations we will try to eliminate. The -concept of key management and configuration is likely to change in the -future without maintaining backward compatibility. - Example configuration --------------------- The example configuration enables automatic signing for all zones -using :ref:`dnssec-enable` option in the ``zones`` section, but the +using :ref:`template_dnssec-enable` option in the default template, but the signing is explicitly disabled for zone ``example.dev`` using the same option directly in zone configuration. The location of directory with -signing keys is set globally by option :ref:`dnssec-keydir`:: +signing keys is set globally by option :ref:`template_dnssec-keydir`:: - zones { - dnssec-enable on; - dnssec-keydir "/var/lib/knot/keys"; + template: + - id: default + dnssec-enable: on + dnssec-keydir: /var/lib/knot/keys - example.com { - file "example.com.zone"; - } + zone: + - domain: example.com + file: example.com.zone - example.dev { - file "example.dev.zone"; - dnssec-enable off; - } - } + - domain: example.dev + file: example.dev.zone + dnssec-enable: off Signing keys ------------ @@ -310,8 +310,8 @@ Currently the signing policy is not configurable, except for signature lifetime. * Signature lifetime can be set in configuration globally for all - zones and for each zone in particular. :ref:`signature-lifetime`. If - not set, the default value is 30 days. + zones and for each zone in particular. :ref:`template_signature-lifetime`. + If not set, the default value is 30 days. * Signature is refreshed 2 hours before expiration. The signature lifetime must thus be set to more than 2 hours. @@ -342,8 +342,8 @@ Query modules ============= Knot DNS supports configurable query modules that can alter the way -queries are processed. The concept is quite simple - each query -requires a finite number of steps to be resolved. We call this set of +queries are processed. The concept is quite simple - each query +requires a finite number of steps to be resolved. We call this set of steps a query plan, an abstraction that groups these steps into several stages. @@ -353,116 +353,112 @@ several stages. For example, processing an Internet zone query needs to find an answer. Then based on the previous state, it may also append an -authority SOA or provide additional records. Each of these actions -represents a 'processing step'. Now if a query module is loaded for a +authority SOA or provide additional records. Each of these actions +represents a 'processing step'. Now if a query module is loaded for a zone, it is provided with an implicit query plan, and it is allowed to extend it or even change it altogether. -*Note:* Programmable interface is described in the ``query_module.h``, -it will not be discussed here. - -The general syntax for importing a query module is described in the -:ref:`query_module` configuration reference. Basically, each module is -described by a name and a configuration string. Below is a list of -modules and configuration string reference. +Each module is configured in the corresponding module section and is +identified for the subsequent usage. Then, the identifier is referenced +through :ref:`template_module` option (in the form of ``module_name/module_id``) +in the zone section or in the ``default`` template if it used for all queries. ``dnstap`` - dnstap-enabled query logging ----------------------------------------- -The Knot DNS supports dnstap_ for query and response logging. -You can capture either all or zone-specific queries and responses, usually you want to do -the former. The dnstap module accepts only a sink path as a parameter, which can either be a file -or a UNIX socket prefixed with *unix:*. - -For example:: - - zones { - query_module { - dnstap "/tmp/capture.tap"; - } - } +Module for query and response logging based on dnstap_ library. +You can capture either all or zone-specific queries and responses, usually +you want to do the former. The configuration consists only from a +:ref:`mod-dnstap_sink` path parameter, which can either be a file or +a UNIX socket:: -You can also log to a UNIX socket with the prefix:: + mod-dnstap: + - id: capture_all + sink: /tmp/capture.tap - zones { - query_module { - dnstap "unix:/tmp/capture.tap"; - } - } + template: + - id: default + module: mod-dnstap/capture_all .. _dnstap: http://dnstap.info/ ``synth_record`` - Automatic forward/reverse records ---------------------------------------------------- -This module is able to synthetise either forward or reverse records for given prefix and subnet. -The module configuration string looks like this: ``(forward|reverse) <prefix> <ttl> <address>/<netblock>``. +This module is able to synthetise either forward or reverse records for +given prefix and subnet. -Records are synthetised only if the query can't be satisfied from the zone. Both IPv4 and IPv6 are supported. -*Note: 'prefix' doesn't allow dots, address parts in the synthetic names are separated with a dash.* +Records are synthetised only if the query can't be satisfied from the zone. +Both IPv4 and IPv6 are supported. -Here are a few examples: *Note: long names are snipped for readability.* Automatic forward records ------------------------- -``synth_record "forward dynamic- 400 2620:0:b61::/52"`` on ``example.`` zone will result in following -answer:: +Example:: + + mod-synth-record: + - id: test1 + type: forward + prefix: dynamic- + ttl: 400 + address: 2620:0:b61::/52 + + zone: + - domain: example. + file: example.zone # Zone file have to exist! + module: mod-synth-record/test1 + +Result:: - $ kdig AAAA dynamic-2620-0000-0b61-0100-0000-0000-0000-0000.example. - ... - ;; QUESTION SECTION: - ;; dynamic-2620-0000-0b61-0100-0000-0000-0000-0000.example. 0 IN AAAA + $ kdig AAAA dynamic-2620-0000-0b61-0100-0000-0000-0000-0000.example. + ... + ;; QUESTION SECTION: + ;; dynamic-2620-0000-0b61-0100-0000-0000-0000-0000.example. 0 IN AAAA - ;; ANSWER SECTION: - dynamic-2620-0000-0b61-0100... 400 IN AAAA 2620:0:b61:100:: + ;; ANSWER SECTION: + dynamic-2620-0000-0b61-0100... 400 IN AAAA 2620:0:b61:100:: -You can also have CNAME aliases to the dynamic records, which are going to be further resoluted:: +You can also have CNAME aliases to the dynamic records, which are going to be +further resoluted:: - $ kdig AAAA hostalias.example. - ... - ;; QUESTION SECTION: - ;hostalias.example. 0 IN AAAA + $ kdig AAAA hostalias.example. + ... + ;; QUESTION SECTION: + ;hostalias.example. 0 IN AAAA - ;; ANSWER SECTION: - hostalias.example. 3600 IN CNAME dynamic-2620-0000-0b61-0100... - dynamic-2620-0000-0b61-0100... 400 IN AAAA 2620:0:b61:100:: + ;; ANSWER SECTION: + hostalias.example. 3600 IN CNAME dynamic-2620-0000-0b61-0100... + dynamic-2620-0000-0b61-0100... 400 IN AAAA 2620:0:b61:100:: Automatic reverse records ------------------------- -Module can be configured to synthetise reverse records as well. With -the ``synth_record "reverse dynamic- example. 400 2620:0:b61::/52"`` -string in the ``1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.`` zone -configuration:: - - $ kdig PTR 1.0.0...1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. - ... - ;; QUESTION SECTION: - ;; 1.0.0...1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. 0 IN PTR - - ;; ANSWER SECTION: - ... 400 IN PTR dynamic-2620-0000-0b61-0000-0000-0000-0000-0001.example. - -Here's a full configuration of the aforementioned zones. Note that the zone files have to exist:: - - example. { - query_module { - synth_record "forward dynamic- 400 2620:0:b61::/52"; - synth_record "forward dynamic- 400 192.168.1.0/25"; - } - } - 1.168.192.in-addr.arpa { - query_module { - synth_record "reverse dynamic- example. 400 192.168.1.0/25"; - } - } - 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa { - query_module { - synth_record "reverse dynamic- example. 400 2620:0:b61::/52"; - } - } +Example:: + + mod-synth-record: + - id: test2 + type: reverse + prefix: dynamic- + zone: example + ttl: 400 + address: 2620:0:b61::/52 + + zone: + - domain: 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. + file: 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.zone # Zone file have to exist! + module: mod-synth-record/test2 + +Result:: + + $ kdig PTR 1.0.0...1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. + ... + ;; QUESTION SECTION: + ;; 1.0.0...1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. 0 IN PTR + + ;; ANSWER SECTION: + ... 400 IN PTR dynamic-2620-0000-0b61-0000-0000-0000-0000-0001.example. Limitations ^^^^^^^^^^^ @@ -475,114 +471,124 @@ Limitations ``dnsproxy`` - Tiny DNS proxy ----------------------------- -The module catches all unsatisfied queries and forwards them to the configured server for resolution, -i.e. a tiny DNS proxy. This can be useful to several things: +The module catches all unsatisfied queries and forwards them to the +configured server for resolution, i.e. a tiny DNS proxy. This can be useful +for several things: * A substitute public-facing server in front of the real one * Local zones (poor man's "views"), rest is forwarded to the public-facing server * etc. -The configuration is straightforward and just accepts a single IP address (either IPv4 or IPv6). +*Note: The module does not alter the query/response as the resolver would do, +also the original transport protocol is kept.* -*Note: The module does not alter the query/response as the resolver would do, also the original -transport protocol is kept.* +The configuration is straightforward and just accepts a single IP address +(either IPv4 or IPv6):: -Example -^^^^^^^ + mod-dnsproxy: + - id: default + remote: 10.0.1.1 -Example configuration:: + template: + - id: default + module: mod-dnsproxy/default - $ vim knot.conf - knot.conf: - zones { - local.zone {} - query_module { - dnsproxy "10.0.1.1"; - } - } + zone: + - domain: local.zone -Now when the clients query for anything in the ``local.zone``, it will be answered locally. -Rest of the requests will be forwarded to the specified server (``10.0.1.1`` in this case). +Now when the clients query for anything in the ``local.zone``, it will be +answered locally. Rest of the requests will be forwarded to the specified +server (``10.0.1.1`` in this case). ``rosedb`` - Static resource records ------------------------------------ -The module provides a mean to override responses for certain queries before the record is searched in -the available zones. The modules comes with a tool ``rosedb_tool`` to manipulate with the database -of static records. Neither the tool nor the module are enabled by default, recompile with the configure flag ``--enable-rosedb`` -to enable them. +The module provides a mean to override responses for certain queries before +the record is searched in the available zones. The modules comes with a tool +``rosedb_tool`` to manipulate with the database of static records. +Neither the tool nor the module are enabled by default, recompile with +the configure flag ``--enable-rosedb`` to enable them. For example, suppose we have a database of following records:: - myrecord.com. 3600 IN A 127.0.0.1 - www.myrecord.com. 3600 IN A 127.0.0.2 - ipv6.myrecord.com. 3600 IN AAAA ::1 + myrecord.com. 3600 IN A 127.0.0.1 + www.myrecord.com. 3600 IN A 127.0.0.2 + ipv6.myrecord.com. 3600 IN AAAA ::1 And we query the nameserver with following:: - $ kdig IN A myrecord.com - ... returns NOERROR, 127.0.0.1 - $ kdig IN A www.myrecord.com - ... returns NOERROR, 127.0.0.2 - $ kdig IN A stuff.myrecord.com - ... returns NOERROR, 127.0.0.1 - $ kdig IN AAAA myrecord.com - ... returns NOERROR, NODATA - $ kdig IN AAAA ipv6.myrecord.com - ... returns NOERROR, ::1 - -*Note: An entry in the database matches anything at or below it, i.e. 'myrecord.com' matches 'a.a.myrecord.com' as well. + $ kdig IN A myrecord.com + ... returns NOERROR, 127.0.0.1 + $ kdig IN A www.myrecord.com + ... returns NOERROR, 127.0.0.2 + $ kdig IN A stuff.myrecord.com + ... returns NOERROR, 127.0.0.1 + $ kdig IN AAAA myrecord.com + ... returns NOERROR, NODATA + $ kdig IN AAAA ipv6.myrecord.com + ... returns NOERROR, ::1 + +*Note: An entry in the database matches anything at or below it, +i.e. 'myrecord.com' matches 'a.a.myrecord.com' as well. This can be exploited to create a catch-all entries.* -You can also add an authority information for the entries, provided you create a SOA + NS records for a name, like so:: +You can also add an authority information for the entries, provided you create +a SOA + NS records for a name, like so:: - myrecord.com. 3600 IN SOA master host 1 3600 60 3600 3600 - myrecord.com. 3600 IN NS ns1.myrecord.com. - myrecord.com. 3600 IN NS ns2.myrecord.com. - ns1.myrecord.com. 3600 IN A 127.0.0.1 - ns2.myrecord.com. 3600 IN A 127.0.0.2 + myrecord.com. 3600 IN SOA master host 1 3600 60 3600 3600 + myrecord.com. 3600 IN NS ns1.myrecord.com. + myrecord.com. 3600 IN NS ns2.myrecord.com. + ns1.myrecord.com. 3600 IN A 127.0.0.1 + ns2.myrecord.com. 3600 IN A 127.0.0.2 In this case, the responses will: 1. Be authoritative (AA flag set) 2. Provide an authority section (SOA + NS) -3. NXDOMAIN if the name is found *(i.e. the 'IN AAAA myrecord.com' from the example)*, but not the RR type *(this is to allow synthesis of negative responses)* +3. NXDOMAIN if the name is found *(i.e. the 'IN AAAA myrecord.com' from + the example)*, but not the RR type *(this is to allow synthesis of negative + responses)* -*Note: The SOA record applies only to the 'myrecord.com.', not to any other record (even below it). From this point of view, -all records in the database are unrelated and not hierarchical. The reasoning is to provide a subtree isolation for each entry.* +*Note: The SOA record applies only to the 'myrecord.com.', not to any other +record (even below it). From this point of view, all records in the database +are unrelated and not hierarchical. The reasoning is to provide a subtree +isolation for each entry.* -In addition the module is able to log matching queries via remote syslog if you specify a syslog address endpoint and an -optional string code. +In addition the module is able to log matching queries via remote syslog if +you specify a syslog address endpoint and an optional string code. Here is an example on how to use the module: * Create the entries in the database:: - $ mkdir /tmp/static_rrdb - $ rosedb_tool /tmp/static_rrdb add myrecord.com. A 3600 "127.0.0.1" "-" "-" # No logging - $ rosedb_tool /tmp/static_rrdb add www.myrecord.com. A 3600 "127.0.0.1" "www_query" "10.0.0.1" # Syslog @ 10.0.0.1 - $ rosedb_tool /tmp/static_rrdb add ipv6.myrecord.com. AAAA 3600 "::1" "ipv6_query" "10.0.0.1" # Syslog @ 10.0.0.1 - $ rosedb_tool /tmp/static_rrdb list # Verify - www.myrecord.com. A RDATA=10B www_query 10.0.0.1 - ipv6.myrecord.com. AAAA RDATA=22B ipv6_query 10.0.0.1 - myrecord.com. A RDATA=10B - - + $ mkdir /tmp/static_rrdb + $ rosedb_tool /tmp/static_rrdb add myrecord.com. A 3600 "127.0.0.1" "-" "-" # No logging + $ rosedb_tool /tmp/static_rrdb add www.myrecord.com. A 3600 "127.0.0.1" "www_query" "10.0.0.1" # Syslog @ 10.0.0.1 + $ rosedb_tool /tmp/static_rrdb add ipv6.myrecord.com. AAAA 3600 "::1" "ipv6_query" "10.0.0.1" # Syslog @ 10.0.0.1 + $ rosedb_tool /tmp/static_rrdb list # Verify + www.myrecord.com. A RDATA=10B www_query 10.0.0.1 + ipv6.myrecord.com. AAAA RDATA=22B ipv6_query 10.0.0.1 + myrecord.com. A RDATA=10B - - *Note: the database may be modified while the server is running later on.* -* Configure the query module and start the server:: +* Configure the query module:: + + mod-rosedb: + - id: default + dbdir: /tmp/static_rrdb + + template: + - id: default + module: mod-rosedb/default - $ vim knot.conf - knot.conf: - zones { - query_module { - rosedb "/tmp/static_rrdb"; - } - } + *Note: The module accepts just one parameter - path to the directory where + the database will be stored.* - $ knotd -c knot.conf +* Start the server:: - *Note: The module accepts just one parameter - path to the directory where the database will be stored.* + $ knotd -c knot.conf * Verify the running instance:: - $ kdig @127.0.0.1#6667 A myrecord.com + $ kdig @127.0.0.1#6667 A myrecord.com diff --git a/doc/installation.rst b/doc/installation.rst index 7ae2f89af..45f6c61a1 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -1,11 +1,11 @@ .. meta:: :description: reStructuredText plaintext markup language -.. _Knot DNS Installation: +.. _Installation: -********************* -Knot DNS Installation -********************* +************ +Installation +************ .. _Required build environment: @@ -59,12 +59,12 @@ http://www.openssl.org. Userspace RCU ------------- -liburcu is a LGPLv2.1 userspace RCU (read-copy-update) library. This -data synchronization library provides read-side access which scales +`Liburcu <http://urcu.so>`_ is a userspace RCU (read-copy-update) library. +This data synchronization library provides read-side access which scales linearly with the number of cores. It does so by allowing multiple copies of a given data structure to live at the same time, and by monitoring the data structure accesses to detect grace periods after -which memory reclamation is possible. `Userspace RSU <http://lttng.org/urcu>`_ +which memory reclamation is possible. Binary packages for Debian can be found under ``liburcu1`` for the library and ``liburcu-dev`` for development files. @@ -75,16 +75,16 @@ It is crucial especially on non-Linux systems, as we got some compatibility patches accepted to later releases of Userspace RCU. OpenBSD, NetBSD and OS X platforms are supported from version 0.7.0. -.. _Installation from the source: +.. _Installation from source code: -Installation from the sources +Installation from source code ============================= -You can find the source files for the latest release on `www.knot-dns.cz <https://www.knot-dns.cz>`_. -Alternatively, you can fetch the sources from git repository +You can find the source code for the latest release on `www.knot-dns.cz <https://www.knot-dns.cz>`_. +Alternatively, you can fetch the whole project from the git repository `git://git.nic.cz/knot-dns.git <https://gitlab.labs.nic.cz/labs/knot/tree/master>`_. -After unpacking the sources, the compilation and installation is a +After obtaining the source code the compilation and installation is a quite straightforward process using autotools. .. _Configuring and generating Makefiles: @@ -92,7 +92,7 @@ quite straightforward process using autotools. Configuring and generating Makefiles ------------------------------------ -If you want to compile from Git sources, you need to bootstrap the ``./configure`` file first:: +If compiling from the git source, you need to bootstrap the ``./configure`` file first:: $ autoreconf -i -f @@ -114,19 +114,6 @@ compiler versions and may result in an unexpected behaviour. Link time optimizations also disables the possibility to debug the resulting binaries. -If you want to add debug messages, there are two steps to do that. -First you have to enable modules you are interested in. -Available are: ``server, zones, ns, loader, dnssec``. -You can combine multiple modules as a comma-separated list. -Then you can narrow the verbosity of the debugging message by specifying the -verbosity as ``brief, verbose, details``. - -For example:: - - $ ./configure --enable-debug=server,packet --enable-debuglevel=verbose - -For more detailed information, see :ref:`Debug messages`. - Compilation ----------- @@ -152,17 +139,18 @@ You can do so by executing:: When installing as a non-root user you might have to gain elevated privileges by switching to root user, e.g. ``sudo make install`` or ``su -c 'make install'``. -Installation from packages -========================== +.. _OS specific installation: -In addition to providing the packages in .DEB and .RPM format, -Knot DNS might already be available in your favourite distribution, or -in a ports tree. +OS specific installation +======================== -Installing Knot DNS packages on Debian --------------------------------------- +Knot DNS might already be available in the destination operating system +repository. -Knot DNS is already available from Debian wheezy upwards. In addition +Debian Linux +------------ + +Knot DNS is already available from Debian wheezy upwards. In addition to the official packages we also provide custom repository, which can be used by adding:: @@ -182,11 +170,11 @@ executing following command as the root user:: $ apt-get update $ apt-get install knot -Installing Knot DNS packages on Ubuntu --------------------------------------- +Ubuntu Linux +------------ Prepackaged version of Knot DNS can be found in Ubuntu from -version 12.10 (Quantal Quetzal). In addition to the package included +version 12.10 (Quantal Quetzal). In addition to the package included in the main archive, we provide Personal Package Archive (PPA) as an option to upgrade to the last stable version of Knot DNS or to install it on older versions of Ubuntu Linux. @@ -205,33 +193,33 @@ Running this sequence of commands will ensure that you will install Knot DNS on your system and keep it up-to-date in the future, when new versions are released. -Installing Knot DNS packages on Fedora --------------------------------------- +Fedora Linux +------------ -The RPM packages for ``Knot DNS`` are available in official Fedora +The RPM packages for Knot DNS are available in official Fedora repositories since Fedora 18 (Spherical Cow). Look for ``knot`` package in your package manager. To install the package using Yum, run -a following command as the root user:: +the following command as the root user:: $ yum install knot -Installing Knot DNS from ports on FreeBSD ------------------------------------------ +FreeBSD +------- Knot DNS is in ports tree under ``dns/knot``:: $ cd /usr/ports/dns/knot $ sudo make install -Installing Knot DNS on Arch Linux ---------------------------------- +Arch Linux +---------- Knot DNS is available official package repository (AUR):: https://aur.archlinux.org/packages/knot/ -Installing Knot DNS on Gentoo Linux ------------------------------------ +Gentoo Linux +------------ Knot DNS is available from Gentoo package repository:: diff --git a/doc/introduction.rst b/doc/introduction.rst index 49bf8bc13..57ba2ec56 100644 --- a/doc/introduction.rst +++ b/doc/introduction.rst @@ -1,14 +1,14 @@ .. meta:: :description: reStructuredText plaintext markup language -Introduction -============ +.. _Introduction: -The reader of this document is assumed to know the principles of -Domain Name System. +************ +Introduction +************ What is Knot DNS ----------------- +================ Knot DNS is a high-performance open source DNS server. It implements only authoritative domain name service. Knot DNS @@ -20,9 +20,9 @@ implementation which allows it to scale well on SMP systems and operate non-stop even when adding or removing zones. Knot DNS features ------------------ +================= -Knot DNS supports the following DNS features: +DNS features: * IN class and partially CH class * TCP/UDP protocols @@ -54,15 +54,9 @@ Knot DNS issue tracker: `gitlab.labs.nic.cz/labs/knot/issues <https://gitlab.lab Knot DNS users mailing list: `knot-dns-users@lists.nic.cz <mailto:knot-dns-users@lists.nic.cz>`_ -Scope of this document ----------------------- - -This document covers the basic information on installing, configuring -and troubleshooting the Knot DNS server. - License -------- +======= Knot DNS is licensed under `GNU General Public License <https://www.gnu.org/copyleft/gpl.html>`_ version 3 or (at your option) any later version. The full text of the license -is available in the ``COPYING`` file distributed with the source codes. +is available in the ``COPYING`` file distributed with the source code. diff --git a/doc/migration.rst b/doc/migration.rst index 0bd3667f9..639ba6fa0 100644 --- a/doc/migration.rst +++ b/doc/migration.rst @@ -45,13 +45,11 @@ generated by Bind. You can follow this example:: - zones { - storage "/var/lib/knot"; - example.com { - dnssec-enable on; - dnssec-keydir "example.com.keys"; - file "example.com.db"; - } - } + zone: + - domain: "example.com." + file: "example.com.db" + storage: "/var/lib/knot" + dnssec-enable: on + dnssec-keydir: "example.com.keys" 5. Start Knot DNS and check the log files to make sure that everything went right. diff --git a/doc/reference.rst b/doc/reference.rst index 4fe877d9b..7ba16d69a 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -1,1211 +1,1042 @@ .. meta:: :description: reStructuredText plaintext markup language -.. _Knot DNS Configuration Reference: +.. _Configuration Reference: -******************************** -Knot DNS Configuration Reference -******************************** +*********************** +Configuration Reference +*********************** -This reference describes every configuration option in Knot DNS server. +.. _Description: -.. _system: +Description +=========== -``system`` Statement -==================== +Configuration file for Knot DNS uses simplified YAML format. Simplified means +that not all features are supported. -The ``system`` statement contains general options related to the -operating system and other general options which do not fit anywhere -else. +For the configuration items description, there are some symbol with the +folowing meaning: -.. _system Syntax: +- *INT* - Integer +- *STR* - Textual string +- *HEXSTR* - Hexadecimal string (with ``0x`` prefix) +- *BOOL* - Boolean value (``on`` or ``off``) +- *TIME* - Number of seconds, integer with possible time mutliplier suffix + (``s`` ~ 1, ``m`` ~ 60, ``h`` ~ 3600 or ``d`` ~ 24 * 3600) +- *SIZE* - Number of bytes, integer with possible size multiplier suffix + (``B`` ~ 1, ``K`` ~ 1024, ``M`` ~ 1024^2 or ``G`` ~ 1024^3) +- *BASE64* - Base64 encoded string +- *ADDR* - IPv4 or IPv6 address +- *DNAME* - Domain name +- ... - Multi-valued item, order of the values is preserved +- [ ] - Optional value +- \| - Choice -``system`` Syntax ------------------ +There are 8 main sections (``server``, ``key``, ``acl``, ``control``, +``remote``, ``template``, ``zone`` and ``log``) and module sections with +``mod-`` prefix . Most of the sections (excluding ``server`` and +``control``) are sequences of settings blocks. Each settings block +begins with a unique identifier, which can be used as a reference from other +sections (such identifier must be defined in advance). -:: +Multi-valued item can be specified either as a YAML sequence [val1, val2, ...] +or as more single-valued items each on the extra line. - system { - [ identity ( on | "string" ); ] - [ version ( on | "string" ); ] - [ nsid ( on | "string" | hex_string ); ] - [ rundir "string"; ] - [ pidfile "string"; ] - [ workers integer; ] - [ background-workers integer; ] - [ asynchronous-start ( on | off ); ] - [ user string[.string]; ] - [ max-conn-idle ( integer | integer(s | m | h | d); ) ] - [ max-conn-handshake ( integer | integer(s | m | h | d); ) ] - [ max-conn-reply ( integer | integer(s | m | h | d); ) ] - [ max-tcp-clients integer; ] - [ transfers integer; ] - [ rate-limit integer; ] - [ rate-limit-size integer; ] - [ rate-limit-slip integer; ] - [ max-udp-payload integer; ] - } - -.. _system Statement Definition and Usage: - -``system`` Statement Definition and Usage ------------------------------------------ - -.. _identity: +If an item value contains spaces or other special characters, it is necessary +to double quote such value with ``"`` ``"``. -identity -^^^^^^^^ +.. _Comments: -Identity of the server returned in a response for the query for TXT -record ``id.server.`` or ``hostname.bind.`` in the CHAOS class (see -`RFC\ 4892 <http://tools.ietf.org/html/rfc4892>`_). +Comments +======== -If not specified or empty, the server returns REFUSED status code. If -a boolean value of ``on`` is used, FQDN hostname is used as a default. +A comment begins with a ``#`` character and is ignored during the processing. +Also each configuration section or sequence block allows to specify permanent +comment using ``comment`` item which is stored in the server beside the +configuration. -:: +.. _Includes: - system { - identity "ns01.example.com"; - identity on; - } +Includes +======== -.. _version: - -version -^^^^^^^ - -Version of the server software returned in a response for the query -for TXT record ``version.server.`` or ``version.bind.`` in the CHAOS -class (see `RFC\ 4892 <http://tools.ietf.org/html/rfc4892>`_). - -Option allows a boolean value ``on|off``, if ``on``, automatic version -string is set as a default. If not specified or empty, the server -returns REFUSED status code. +Another configuration file or all configuration files in a directory can be +included at the top level in the current file. If the file or directory path +is not absolute, then it is relative to the current file directory. :: - system { - version "Knot DNS 1.3.0"; - version on; # Reports current version - } + include: STR -.. _nsid: +.. _Server section: -nsid -^^^^ +Server section +============== -DNS Name Server Identifier (see `RFC\ 5001 <http://tools.ietf.org/html/rfc5001>`_). - -Use a string format "text" or a hexstring (e.g. 0x01ab00) If a -boolean value of ``on`` is used, FQDN hostname is used as a default. +General options related to the server. :: - system { - nsid 0x00cafe; - nsid "cafe"; - nsid on; - } + server: + identity: [STR] + version: [STR] + nsid: [STR|HEXSTR] + rundir: STR + user: STR[:STR] + pidfile: STR + workers: INT + background-workers: INT + asynchronous-start: BOOL + max-conn-idle: TIME + max-conn-handshake: TIME + max-conn-reply: TIME + max-tcp-clients: INT + max-udp-payload: SIZE + transfers: INT + rate-limit: INT + rate-limit-slip: INT + rate-limit-size: INT + listen: ADDR[@INT] ... + +.. _server_identity: -.. _rundir: +identity +-------- -rundir -^^^^^^ +An identity of the server returned in the response for the query for TXT +record ``id.server.`` or ``hostname.bind.`` in the CHAOS class (see RFC 4892). +If empty, FQDN hostname is used. -Path for storing run-time data, for example PID file and unix sockets. -Default value: ``${localstatedir}/run/knot``, configured with -``--with-rundir=path`` +Default: disabled -:: +.. _server_version: - system { - rundir "/var/run/knot"; - } +version +------- -.. _pidfile: +A version of the server software returned in the response for the query +for TXT record ``version.server.`` or ``version.bind.`` in the CHAOS +class (see RFC 4892). If empty, automatic version is used. -pidfile -^^^^^^^ +Default: disabled -Specifies a custom PID file location. +.. _server_nsid: -Default value: ``knot.pid`` in ``rundir`` directory. +nsid +---- -:: +A DNS name server identifier (see RFC 5001). If empty, FQDN hostname is used. - system { - pidfile "/var/run/knot/knot_dmz.pid"; - } +Default: disabled -.. _workers: +.. _server_rundir: -workers -^^^^^^^ +rundir +------ -Number of workers (threads) per server interface. This option is used -to force number of threads used per interface. +A path for storing run-time data (PID file, unix sockets, etc.). -Default value: unset (auto-estimates optimal value from the number of -online CPUs) +Default: ``${localstatedir}/run/knot`` (configured with ``--with-rundir=path``) -:: +.. _server_user: - system { - workers 16; - } +user +---- -.. _background-workers: +A system user with an optional system group (*user*:*group*) under which the +server is run after starting and binding to interfaces. Linux capabilities +are employed if supported. -background-workers -^^^^^^^^^^^^^^^^^^ -This option is used to set number of threads used to execute background -operations (e.g., zone loading, zone signing, XFR zone updates, ...). +Default: root:root -Default value: unset (auto-estimates optimal value for the number of online CPUs) +.. _server_pidfile: -:: +pidfile +------- - system { - background-workers 4; - } +A PID file location. -.. _asynchronous-start: +Default: :ref:`rundir<server_rundir>`/knot.pid -asynchronous-start -^^^^^^^^^^^^^^^^^^ +.. _server_workers: -When asynchronous startup is enabled, server doesn't wait for the zones to be -loaded, and starts responding immediately with SERVFAIL answers until the zone -loads. This may be useful in some scenarios, but it is disabled by default. +workers +------- -Default value: ``off`` (wait for zones to be loaded before answering) +A number of quering workers (threads) per server interface. -:: +Default: auto-estimated optimal value based on the number of online CPUs - system { - asynchronous-start off; - } +.. _server_background-workers: -.. _user: +background-workers +------------------ -user -^^^^ +A number of workers (threads) used to execute background operations (zone +loading, zone updates, etc.). -System ``user`` or ``user``.``group`` under which the Knot DNS is run -after starting and binding to interfaces. Linux capabilities -(:ref:`Required libraries`) are employed if supported and this -configuration option is set. +Default: auto-estimated optimal value based on the number of online CPUs -Default value: ``root.root`` +.. _server_asynchronous-start: -:: +asynchronous-start +------------------ - system { - user knot.knot; - } +If enabled, server doesn't wait for the zones to be loaded and starts +responding immediately with SERVFAIL answers until the zone loads. -.. _max-conn-idle: +Default: off + +.. _server_max-conn-idle: max-conn-idle -^^^^^^^^^^^^^ +------------- + +Maximum idle time between requests on a TCP connection. This also limits +receiving of a single query, each query must be received in this time limit. -Maximum idle time between requests on a TCP connection. This also -limits receiving of a single query, each query must be received in -this time limit. +Default: 20 -.. _max-conn-handshake: +.. _server_max-conn-handshake: max-conn-handshake -^^^^^^^^^^^^^^^^^^ +------------------ -Maximum time between newly accepted TCP connection and first query. -This is useful to disconnect inactive connections faster, than -connection that already made at least 1 meaningful query. +Maximum time between newly accepted TCP connection and the first query. +This is useful to disconnect inactive connections faster than connections +that already made at least 1 meaningful query. -.. _max-conn-reply: +Default: 5 + +.. _server_max-conn-reply: max-conn-reply -^^^^^^^^^^^^^^ +-------------- Maximum time to wait for a reply to an issued SOA query. -.. _max-tcp-clients: +Default: 10 + +.. _server_max-tcp-clients: max-tcp-clients -^^^^^^^^^^^^^^^ +--------------- + +A maximum number of TCP clients connected in parallel, set this below the file +descriptor limit to avoid resource exhaustion. -Maximum number of TCP clients connected in parallel, set this below file descriptor limit to avoid resource exhaustion. +Default: 100 -.. _transfers: +.. _server_transfers: transfers -^^^^^^^^^ +--------- -Maximum parallel transfers, including pending SOA queries. Lowest -possible number is the number of CPUs. Default is 10. +A maximum number of parallel transfers, including pending SOA queries. The +minimum value is determined by the number of CPUs. -.. _rate-limit: +Default: 10 + +.. _server_rate-limit: rate-limit -^^^^^^^^^^ +---------- -Rate limiting is based on a token bucket scheme, rate basically -represents number of tokens available each second. Each response is -processed and classified (based on a several discriminators, f.e. -source netblock, qtype, name, rcode, etc.). Classified responses are +Rate limiting is based on the token bucket scheme. Rate basically +represents number of tokens available each second. Each response is +processed and classified (based on several discriminators, e.g. +source netblock, qtype, name, rcode, etc.). Classified responses are then hashed and assigned to a bucket containing number of available -tokens, timestamp and metadata. When available tokens are exhausted, -response is rejected or enters SLIP (server responds with a truncated -response). Number of available tokens is recalculated each second. +tokens, timestamp and metadata. When available tokens are exhausted, +response is rejected or enters :ref:`SLIP<server_rate-limit-slip>` +(server responds with a truncated response). Number of available tokens +is recalculated each second. -Default value: ``0 (disabled)`` +Default: 0 (disabled) -.. _rate-limit-size: +.. _server_rate-limit-size: rate-limit-size -^^^^^^^^^^^^^^^ +--------------- -Option controls the size of a hashtable of buckets. The larger the -hashtable, the lesser probability of a hash collision, but at the -expense of additional memory costs. Each bucket is estimated roughly -to 32B. Size should be selected as a reasonably large prime due to -the better hash function distribution properties. Hash table is -internally chained and works well up to a fill rate of 90%, general -rule of thumb is to select a prime near ``1.2 * maximum_qps``. +Size of hashtable buckets. The larger the hashtable, the lesser probability +of a hash collision, but at the expense of additional memory costs. Each bucket +is estimated roughly to 32 bytes. Size should be selected as a reasonably large +prime due to the better hash function distribution properties. Hash table is +internally chained and works well up to a fill rate of 90 %, general +rule of thumb is to select a prime near 1.2 * maximum_qps. -Default value: ``393241`` +Default: 393241 -.. _rate-limit-slip: +.. _server_rate-limit-slip: rate-limit-slip -^^^^^^^^^^^^^^^ +--------------- As attacks using DNS/UDP are usually based on a forged source address, an attacker could deny services to the victim netblock if all -responses would be completely blocked. The idea behind SLIP mechanism +responses would be completely blocked. The idea behind SLIP mechanism is to send each Nth response as truncated, thus allowing client to -reconnect via TCP for at least some degree of service. It is worth -noting, that some responses can't be truncated (f.e. SERVFAIL). +reconnect via TCP for at least some degree of service. It is worth +noting, that some responses can't be truncated (e.g. SERVFAIL). + +It is advisable not to set the slip interval to a value larger than 2, +as too large slip value means more denial of service for legitimate +requestors, and introduces excessive timeouts during resolution. +On the other hand, slipping truncated answer gives the legitimate +requestors a chance to reconnect over TCP. -Default value: ``1`` +Default: 1 -.. _max-udp-payload: +.. _server_max-udp-payload: max-udp-payload -^^^^^^^^^^^^^^^ +--------------- Maximum EDNS0 UDP payload size. -Default value: ``4096`` +Default: 4096 -.. _system Example: +.. _server_listen: -system Example --------------- +listen +------ -.. parsed-literal :: +One or more IP addresses where the server listens for incoming queries. +Optional port specification (default is 53) can be appended to each address +using ``@`` separator. Use ``0.0.0.0`` for all configured IPv4 addresses or +``::`` for all configured IPv6 addresses. - system { - identity "Knot DNS |version|"; - version "|version|"; - nsid "amaterasu"; - rundir "/var/run/knot"; - workers 16; - user knot.knot; - max-udp-payload 4096; - } +Default: empty -.. _keys: +.. _Key section: -``keys`` Statement -================== +Key section +=========== -The ``keys`` statement sets up the TSIG keys used to authenticate -zone transfers. +Shared TSIG keys used to authenticate communication with the server. -.. _keys Syntax: +:: -keys Syntax ------------ + key: + - id: DNAME + algorithm: hmac-md5 | hmac-sha1 | hmac-sha224 | hmac-sha256 | hmac-sha384 | hmac-sha512 + secret: BASE64 -:: +.. _key_id: - keys { - key_id algorithm "string"; - [ key_id algorithm "string"; ... ] - } +id +-- -.. _keys Statement Definition and Usage: +A key name identifier. -Statement Definition and Usage ------------------------------- +.. _key_algorithm: -.. _key_id: +algorithm +--------- + +A key algorithm. + +Default: empty -``key_id`` Statement -^^^^^^^^^^^^^^^^^^^^ +.. _key_secret: -The ``key_id`` statement defines a secret shared key for use with -TSIG. It consists of its ``name``, ``algorithm`` and ``key`` -contents. +secret +------ -Supported algoritms: +Shared key secret. -* hmac-md5 -* hmac-sha1 -* hmac-sha224 -* hmac-sha256 -* hmac-sha384 -* hmac-sha512 +Default: empty -You need to use bind or ldns utils to generate TSIG keys. -Unfortunately, Knot DNS does not have any own generation utilities -yet. +.. _ACL section: + +ACL section +=========== + +Access control list rules definition. :: - $ dnssec-keygen -a HMAC-SHA256 -b 256 -n HOST foobar.example.com - Kfoobar.example.com.+163+21239 - $ cat Kfoobar.example.com.+163+21239.key - foobar.example.com. ( IN KEY 512 3 163 - rqv2WRyDgIUaHcJi03Zssor9jtG1kOpb3dPywxZfTeo= ) + acl: + - id: STR + address: ADDR[/INT] + key: key_id + action: deny | xfer | notify | update | control ... -Key generated in previous paragraph would be written as:: +.. _acl_id: - keys { - foobar.example.com. hmac-sha256 - "rqv2WRyDgIUaHcJi03Zssor9jtG1kOpb3dPywxZfTeo="; - } +id +-- -.. _keys Example: +An ACL rule identifier. -keys Example ------------- +.. _acl_address: -:: +address +------- - keys { - key0.server0 hmac-md5 "Wg=="; - foobar.example.com. hmac-sha256 "RQ=="; - } +A single IP address or network subnet with the given prefix the query +must match. -.. _interfaces: +Default: empty -``interfaces`` Statement -======================== +.. _acl_key: -The ``interfaces`` statement contains IP interfaces where Knot DNS -listens for incoming queries. +key +--- -.. _interfaces Syntax: +A :ref:`reference<key_id>` to the TSIG key the query must match. -``interfaces`` Syntax ---------------------- +Default: empty -:: +.. _acl_action: - interfaces { - interface_id - ( ip_address[@port_number] | - { address ip_address; [ port port_number; ] @} ) - [ interface_id ...; ...; ] - } +action +------ -.. _interfaces Statement Definition and Usage: +An ordered list of allowed actions. -``interfaces`` Statement Definition and Usage ---------------------------------------------- +Possible values: -.. _interface_id: +- ``deny`` - Block the matching query +- ``xfer`` - Allow zone transfer +- ``notify`` - Allow incoming notify +- ``update`` - Allow zone updates +- ``control`` - Allow remote control -``interface_id`` -^^^^^^^^^^^^^^^^ +Default: deny -The ``interface_id`` is a textual identifier of an IP interface, which -consists of an IP address and a port. +.. _Control section: -The definition of an interface can be written in long or a short form -and it always contains IP (IPv4 or IPv6) address. +Control section +=============== -.. _interfaces Example: +Configuration of the server remote control. -``interfaces`` Example ----------------------- +Caution: The control protocol is not encrypted, and susceptible to replay +attacks in a short timeframe until message digest expires, for that reason, +it is recommended to use default UNIX socket. -Long form:: +:: - interfaces { - my_ip { - address 192.0.2.1; - port 53; - } - } + control: + listen: ADDR[@INT] + acl: acl_id ... -Short form:: +.. _control_listen: - interfaces { - my_second_ip { address 198.51.100.1@53; } - } +listen +------ -Short form without port (defaults to 53):: +A UNIX socket path or IP address where the server listens for remote control +commands. Optional port specification (default is 5533) can be appended to the +address using ``@`` separator. - interfaces { - my_third_ip { address 203.0.113.1; } - } +Default: :ref:`rundir<server_rundir>`/knot.sock -.. _remotes: +.. _control_acl: -``remotes`` Statement -===================== +acl +--- -The ``remotes`` statement sets up all remote servers for zone -transfers. Knot DNS does not distinguish between client or server in -this section. Role of the server is determined at the time of its -usage in the ``zones`` section. One server may act as a client for -one zone (e.g. downloading the updates) and as a master server for a -different zone. +An ordered list of :ref:`references<acl_id>` to ACL rules allowing the remote +control. -.. _remotes Syntax: +Caution: This option has no effect with UNIX socket. -``remotes`` Syntax ------------------- +Default: empty -:: +.. _Remote section: + +Remote section +============== - remotes { - remote_id - ( ip_address[@port_number] | - { address ip_address; - [ port port_number; ] - [ key key_id; ] - [ via [ interface_id | ip_address ]; ] - } - ) - [ remote_id ...; ...; ] - } +Definition of remote servers for zone transfers or notifications. -.. _remotes Statement Definition and Grammar: +:: -``remotes`` Statement Definition and Grammar --------------------------------------------- + remote: + - id: STR + address: ADDR[@INT] + via: ADDR[@INT] + key: key_id .. _remote_id: -``remote_id`` -^^^^^^^^^^^^^ +id +-- + +A remote identifier. -``remote_id`` contains a symbolic name for a remote server. +.. _remote_address: -.. _address: +address +------- -``address`` -^^^^^^^^^^^ +A destination IP address of the remote server. Optional destination port +specification (default is 53) can be appended to the address using ``@`` +separator. -``address`` sets an IPv4 or an IPv6 address for this particular -``remote``. +Default: empty -.. _port: +.. _remote_via: -``port`` -^^^^^^^^ +via +--- -``port`` section contains a port number for the current ``remote``. -This section is optional with default port set to 53. +A source IP address which is used to communicate with the remote server. +Optional source port specification can be appended to the address using +``@`` separator. -.. _key: +Default: empty -``key`` -^^^^^^^ +.. _remote_key: -``key`` section contains a key associated with this ``remote``. This -section is optional. +key +--- -.. _via: +A :ref:`reference<key_id>` to the TSIG key which ise used to autenticate +the communication with the remote server. -via -^^^ +Default: empty -``via`` section specifies which interface will be used to communicate -with this ``remote``. This section is optional. +.. _Template section: -.. _remotes Example: +Template section +================ -``remotes`` Example -------------------- +A template is shareable zone settings which can be used for configuration of +many zones at one place. A special default template (with *default* identifier) +can be used for general quering configuration or as an implicit default +configuration if a zone doesn't have a teplate specified. :: - remotes { - # Long form: - server0 { - address 127.0.0.1; - port 53531; - key key0.server0; - via ipv4; # reference to interface named ipv4 - # via 82.35.64.59; # direct IPv4 - # via [::cafe]; # direct IPv6 - } + template: + - id: STR + storage: STR + master: remote_id ... + notify: remote_id ... + acl: acl_id ... + semantic-checks: BOOL + disable-any: BOOL + notify-timeout: TIME + notify-retries: INT + zonefile-sync: TIME + ixfr-from-differences: BOOL + ixfr-fslimit: SIZE + dnssec-enable: BOOL + dnssec-keydir: STR + signature-lifetime: TIME + serial-policy: increment | unixtime + module: STR/STR ... - # Short form: - server1 { - address 127.0.0.1@53001; - } - } +.. _template_id: -.. _groups: +id +-- -``groups`` Statement -==================== +A template identifier. -The ``groups`` statement is used to create groups of remote machines -defined in :ref:`remotes` statement. The group can substitute multiple -machines specification anywhere in the configuration where the list of -remotes is allowed to be used (namely ``allow`` in :ref:`control` -section and ACLs in :ref:`zones` section). +.. _template_storage: -The remotes definitions must exist prior to using them in group -definitions. One remote can be a member of multiple groups. +storage +------- -.. _groups Syntax: +A data directory for storing zone files, journal files and timers database. -``groups`` Syntax ------------------ +Default: ``${localstatedir}/lib/knot`` (configured with ``--with-storage=path``) -:: +.. _template_master: - groups { - group_id { remote_id [ , ... ] } - [ ... ] - } +master +------ -.. _groups Statement Definition and Grammar: +An ordered list of :ref:`references<remote_id>` to zone master servers. -``groups`` Statement Definition and Grammar -------------------------------------------- +Default: empty -.. _group_id: +.. _template_notify: -``group_id`` -^^^^^^^^^^^^ +notify +------ -``group_id`` contains a symbolic name for a group of remotes. +An ordered list of :ref:`references<remote_id>` to remotes to which notify +message is sent if the zone changes. -.. _groups-remote_id: +Default: empty -``remote_id`` -^^^^^^^^^^^^^ +.. _template_acl: -``remote_id`` contains a symbolic name for a remote server as -specified in :ref:`remotes` section. +acl +--- -.. _groups Example: +An ordered list of :ref:`references<acl_id>` to ACL rules which can allow +or disallow zone transfers, updates or incoming notifies. -``groups`` Example ------------------- +Default: empty -:: +.. _template_semantic-checks: - remotes { - ctl { - # ... - } - alice { - # ... - } - bob { - # ... - } - } - - groups { - admins { alice, bob } - } - - # example usage: - control { - # ... - allow ctl, admins; - } - -.. _control: - -``control`` Statement -===================== - -The ``control`` statement specifies on which interface to listen for -remote control commands. Caution: The control protocol is not -encrypted, and susceptible to replay attack in a short timeframe until -message digest expires, for that reason, it is recommended to use -default UNIX sockets. - -.. _control Syntax: - -``control`` Syntax ------------------- +semantic-checks +--------------- -:: +If enabled, extra zone file semantic checks are turned on. - control { - [ listen-on { - ( address ip_address[@port_number] | - { address ip_address; [ port port_number; ] } ) - } ] - [ allow remote_id [, remote_id, ... ]; ] - } +Several checks are enabled by default and cannot be turned off. An error in +mandatory checks causes zone not to be loaded. An error in extra checks is +logged only. -.. _control Statement Definition and Grammar: +Mandatory checks: -``control`` Statement Definition and Grammar --------------------------------------------- +- An extra record together with CNAME record (except for RRSIG and DS) +- CNAME link chain length greater than 10 (including infinite cycles) +- DNAME and CNAME records under the same owner (RFC 2672) +- CNAME and DNAME wildcards pointing to themselves +- SOA record missing in the zone (RFC 1034) +- DNAME records having records under it (DNAME children) (RFC 2672) -Control interface ``listen-on`` either defines a UNIX socket or an -IPv4/IPv6 ``interface`` definition as in :ref:`interfaces`. Default -port for IPv4/v6 control interface is ``5533``, however UNIX socket is -preferred. UNIX socket address is relative to ``rundir`` if not -specified as an absolute path. Without any configuration, the socket -will be created in ``rundir/knot.sock``. +Extra checks: -.. _control Examples: +- Missing NS record at the zone apex +- Missing glue A or AAAA records +- Broken or non-cyclic NSEC(3) chain +- Wrong NSEC(3) type bitmap +- Multiple NSEC records at the same node +- Missing NSEC records at authoritative nodes +- Extra record types under same name as NSEC3 record (this is RFC-valid, but + Knot will not serve such a zone correctly) +- NSEC3-unsecured delegation that is not part of Opt-out span +- Wrong original TTL value in NSEC3 records +- Wrong RDATA TTL value in RRSIG record +- Signer name in RRSIG RR not the same as in DNSKEY +- Signed RRSIG +- Not all RRs in node are signed +- Wrong key flags or wrong key in RRSIG record (not the same as ZSK) -``control`` Examples --------------------- +Default: off -UNIX socket example:: +.. _template_disable-any: - control { - listen-on "/var/run/knot/knot.sock"; - } +disable-any +----------- -IPv4 socket example:: +If you enabled, all authoritative ANY queries sent over UDP will be answered +with an empty response and with the TC bit set. Use this option to minimize +the risk of DNS reflection attack. - keys { - knotc-key hmac-md5 "Wg=="; - } - remotes { - ctl { address 127.0.0.1; key knotc-key; } - } - control { - listen-on { address 127.0.0.1; } - allow ctl; - } +Default: off -.. _zones: +.. _template_notify-timeout: -``zones`` Statement -=================== +notify-timeout +-------------- -The ``zones`` statement contains definition of zones served by Knot DNS. +The time how long will server wait for a notify response. -.. _zones Syntax: +Default: 60 -``zones`` Syntax ----------------- +.. _template_notify-retries: -:: +notify-retries +-------------- + +The number of retries the server sends a notify message. + +Default: 5 + +.. _template_zonefile-sync: + +zonefile-sync +------------- - zones { - [ zone_options ] - zone_id { - file "string"; - [ xfr-in remote_id [, remote_id, ... ]; ] - [ xfr-out remote_id [, remote_id, ... ]; ] - [ notify-in remote_id [, remote_id, ... ]; ] - [ notify-out remote_id [, remote_id, ... ]; ] - [ update-in remote_id [, remote_id, ... ]; ] - [ zone_options ] - } - } +The time after which the current zone in memory will be synced to zone file +on the disk (see :ref:`file<zone_file>`). The server will serve the latest +zone even after restart using zone journal, but the zone file on the disk will +only be synced after ``zonefile-sync`` time has expired (or after manual zone +flush) This is applicable when the zone is updated via IXFR, DDNS or automatic +DNSSEC signing. - zone_options := - [ storage "string"; ] - [ semantic-checks boolean; ] - [ ixfr-from-differences boolean; ] - [ disable-any boolean; ] - [ notify-timeout integer; ] - [ notify-retries integer; ] - [ zonefile-sync ( integer | integer(s | m | h | d); ) ] - [ ixfr-fslimit ( integer | integer(k | M | G) ); ] - [ ixfr-from-differences boolean; ] - [ dnssec-keydir "string"; ] - [ dnssec-enable ( on | off ); ] - [ signature-lifetime ( integer | integer(s | m | h | d); ) ] - [ serial-policy ( increment | unixtime ); ] - [ query_module { module_name "string"; [ module_name "string"; ... ] } ] +*Caution:* If you are serving large zones with frequent updates where +the immediate sync to zone file is not desirable, increase the default value. -.. _zones Statement Definition and Grammar: +Default: 0 (immediate) -``zones`` Statement Definition and Grammar ------------------------------------------- +.. _template_ixfr-from-differences: -.. _zone_id: +ixfr-from-differences +--------------------- + +If enabled, the server creates zone differences from changes you made to the +zone file upon server reload. This option is only relevant if the server +is a master server for the zone. + +Default: off + +.. _template_ixfr-fslimit: -``zone_id`` -^^^^^^^^^^^ +ixfr-fslimit +------------ + +Maximum zone journal file. -``zone_id`` is a zone origin, and as such is a domain name that may or -may not end with a ".". If no $ORIGIN directive is found inside -actual zone file, this domain name will be used in place of "@". SOA -record in the zone must have this name as its owner. +Default: unlimited -.. _file: +.. _template_dnssec-enable: -``file`` -^^^^^^^^ +dnssec-enable +------------- -The ``file`` statement defines a path to the zone file. You can -either use an absolute path or a relative path. In that case, the -zone file path will be relative to the ``storage`` directory -(:ref:`storage`). +If enabled, automatic DNSSEC signing for the zone is turned on. -.. _xfr-in: +Default: off -``xfr-in`` -^^^^^^^^^^ +.. _template_dnssec-keydir: -In ``xfr-in`` statement user specifies which remotes will be permitted -to perform a zone transfer to update the zone. Remotes are defined in -``remotes`` section of configuration file (:ref:`remotes`). +dnssec-keydir +------------- -.. _xfr-out: +A data directory for storing DNSSEC signing keys. Non absolute path is +relative to :ref:`storage<template_storage>`. -``xfr-out`` -^^^^^^^^^^^ +Default: :ref:`storage<template_storage>`/keys -In ``xfr-out`` statement user specifies which remotes will be -permitted to obtain zone's contents via zone transfer. Remotes are -defined in ``remotes`` section of configuration file -(:ref:`remotes`). +.. _template_signature-lifetime: -.. _notify-in: +signature-lifetime +------------------ -``notify-in`` -^^^^^^^^^^^^^ +The time how long the automatically generated DNSSEC signatures should be valid. +Expiration will thus be set as current time (in the moment of signing) ++ ``signature-lifetime``. The signatures are refreshed one tenth of the +signature lifetime before the signature expiration (i.e. 3 days before the +expiration with the default value). Minimum possible value is 10801. -``notify-in`` defines which remotes will be permitted to send NOTIFY -for this particular zone. Remotes are defined in ``remotes`` section -of configuration file (:ref:`remotes`). +Default: 30 * 24 * 3600 -.. _notify-out: +.. _template_serial-policy: -``notify-out`` -^^^^^^^^^^^^^^ +serial-policy +------------- -``notify-out`` defines to which remotes will your server send NOTIFYs -about this particular zone. Remotes are defined in ``remotes`` -section of configuration file (:ref:`remotes`). +Specifies how the zone serial is updated after a dynamic update or +automatic DNSSEC signing. If the serial is changed by the dynamic update, +no change is made. -.. _update-in: +Possible values: -``update-in`` -^^^^^^^^^^^^^ +- ``increment`` - The serial is incremented according to serial number arithmetic +- ``unixtime`` - The serial is set to the current unix time -In ``update-in`` statement user specifies which remotes will be -permitted to perform a DNS UPDATE. Remotes are defined in ``remotes`` -section of configuration file (:ref:`remotes`). +*Caution:* If your serial was in other than unix time format, be careful +with the transition to unix time. It may happen that the new serial will +be \'lower\' than the old one. If this is the case, the transition should be +done by hand (see RFC 1982). -.. _query_module : +Default: increment -``query_module`` -^^^^^^^^^^^^^^^^ +.. _template_module: -Statement ``query_module`` takes a list of ``module_name -"config_string"`` query modules separated by semicolon. +module +------ -.. _storage: +An ordered list of references to query modules in the form +*module_name/module_id*. -``storage`` -^^^^^^^^^^^ +Default: empty -Data directory for zones. It is used to store zone files and journal -files. If compiled with LMDB support, a database storing persistent zone -event timers for slave zones will be created in the ``timers`` subdirectory. +.. _Zone section: -Value of ``storage`` set in ``zone`` section is relative to -``storage`` in ``zones`` section. +Zone section +============ -Default value (in ``zones`` section): ``${localstatedir}/lib/knot``, -configured with ``--with-storage=path`` +Definitions of zones served by the server. -Default value (in ``zone`` config): inherited from ``zones`` section +Zone configuration is a superset of :ref:`template configuration<Template section>`, +so each zone configuration can contain all template configuration options which +may override possible template configuration. :: - zones { - storage "/var/lib/knot"; - example.com { - storage "com"; - file "example.com"; # /var/lib/knot/com/example.com - } - } + zone: + - domain: DNAME + file: STR + template: template_id + # All template options -.. _semantic-checks: +.. _zone_domain: -``semantic-checks`` -^^^^^^^^^^^^^^^^^^^ +domain +------ -``semantic-checks`` statement turns on optional semantic checks for -this particular zone. See :ref:`zones List of zone semantic checks` for -more information. +A zone name identifier. -Possible values are ``on`` and ``off``. Most checks are disabled by -default. +.. _zone_file: -.. _ixfr-from-differences: +file +---- -``ixfr-from-differences`` -^^^^^^^^^^^^^^^^^^^^^^^^^ +A path to the zone file. Non absolute path is relative to +:ref:`storage<template_storage>`. -Option ``ixfr-from-differences`` is only relevant if you are running -Knot DNS as a master for this zone. By turning the feature on you -tell Knot to create differences from changes you made to a zone file -upon server reload. See :ref:`Controlling running daemon` for more -information. +Default: :ref:`storage<template_storage>`/``domain``.zone -Possible values are ``on`` and ``off``. Disabled by default. +.. _zone_template: -.. _disable-any: +template +-------- -``disable-any`` -^^^^^^^^^^^^^^^ +A :ref:`reference<template_id>` to configuration template. If not specified +and *default* template exists, then the default template is used. -If you enable ``disable-any``, all authoritative ANY queries sent over -UDP will be answered with an empty response and with the TC bit set. -Use to minimize the risk of DNS reflection attack. Disabled by default. +Default: empty -.. _notify-timeout: +.. _Logging section: -``notify-timeout`` -^^^^^^^^^^^^^^^^^^ +Logging section +=============== -``notify-timeout`` in seconds specifies how long will server wait for -NOTIFY response. Possible values are 1 to INT_MAX. By default, this -value is set to 60 seconds. +Server can be configured to log to the standard output, standard error +output, syslog (or systemd journal if systemd is enabled) or into an arbitrary +file. -.. _notify-retries: +There are 6 logging severities: -``notify-retries`` -^^^^^^^^^^^^^^^^^^ +- ``critical`` - Non-recoverable error resulting in server shutdown -``notify-retries`` tells the server how many times it can retry to -send a NOTIFY. Possible values are 1 to INT_MAX and default value -is 5. +- ``error`` - Recoverable error, action should be taken -.. _zonefile-sync: +- ``warning`` - Warning that might require user action -``zonefile-sync`` -^^^^^^^^^^^^^^^^^ +- ``notice`` - Server notice or hint -``zonefile-sync`` specifies a time in seconds after which current zone -in memory will be synced to zone file on the disk (as set in -:ref:`file`). Knot DNS will serve the latest zone even after restart, -but zone file on a disk will only be synced after ``zonefile-sync`` -time has expired (or synced manually via ``knotc flush`` - see -:ref:`Running Knot DNS`). This is applicable when the zone is updated -via IXFR, DDNS or automatic DNSSEC signing. Possible values are 0 to -INT_MAX, optionally suffixed by unit size (s/m/h/d) - *1s* is one -second, *1m* one minute, *1h* one hour and *1d* one day -with default value set to *0s*. +- ``info`` - Informational message -*Important note:* If you are serving large zones with frequent -updates where the immediate sync to zone file is not desirable, set -this value in the configuration file to other value. +- ``debug`` - Debug messages (must be turned on at compile time) -.. _ixfr-fslimit: +In case of missing log section, ``warning`` or more serious messages +will be logged to both standard error output and syslog. The ``info`` and +``notice`` messages will be logged to standard output. -``ixfr-fslimit`` -^^^^^^^^^^^^^^^^ +:: -``ixfr-fslimit`` sets a maximum file size for zone's journal in bytes. -Possible values are 1 to INT_MAX, with optional suffixes k, m and G. -I.e. *1k*, *1m* and *1G* with default value not being set, meaning -that journal file can grow without limitations. + log: + - to: stdout | stderr | syslog | STR + server: critical | error | warning | notice | info | debug + zone: critical | error | warning | notice | info | debug + any: critical | error | warning | notice | info | debug -.. _dnssec-keydir: +.. _log_to: -``dnssec-keydir`` -^^^^^^^^^^^^^^^^^ +to +-- -Location of DNSSEC signing keys, relative to ``storage``. +A logging output. -Default value: not set +Possible values: -.. _dnssec-enable: +- ``stdout`` - Standard output +- ``stderr`` - Standard error output +- ``syslog`` - Syslog +- *file_name* - File. -``dnssec-enable`` -^^^^^^^^^^^^^^^^^ +.. _log_server: -PREVIEW: Enable automatic DNSSEC signing for the zone. +server +------ -Default value (in ``zones`` section): ``off`` +Minimum severity level for messages related to general operation of the server +that are logged. -Default value (in ``zone`` config): inherited from ``zones`` section +Default: empty -.. _signature-lifetime: +.. _log_zone: -``signature-lifetime`` -^^^^^^^^^^^^^^^^^^^^^^ +zone +---- -Specifies how long should the automatically generated DNSSEC signatures be valid. -Expiration will thus be set as current time (in the moment of signing) -+ ``signature-lifetime``. Possible values are from 10801 to INT_MAX. -The signatures are refreshed one tenth of the signature lifetime -before the signature expiration (i.e., 3 days before the expiration -with the default value). For information about zone expiration date, -invoke the ``knotc zonestatus`` command. +Minimum severity level for messages related to zones that are logged. -Default value: ``30d`` (``2592000``) +Default: empty -.. _serial-policy: +.. _log_any: -``serial-policy`` -^^^^^^^^^^^^^^^^^ +any +--- -Specifies how the zone serial is updated after DDNS (dynamic update) -and automatic DNSSEC signing. If the serial is changed by the dynamic -update, no change is made. +Minimum severity level for all message types that are logged. -* ``increment`` - After update or signing, the serial is automatically - incremented (according to serial number arithmetic). -* ``unixtime`` - After update or signing, serial is set to the current - unix time. +Default: empty -*Warning:* If your serial was in other than unix time format, be -careful with transition to unix time. It may happen that the new -serial will be 'lower' than the old one. If this is the case, the -transition should be done by hand (see `RFC\ 1982 -<https://tools.ietf.org/html/rfc1982>`_). +.. _Module dnstap: -Default value: ``increment`` +Module dnstap +============= -.. _zones Example: +Module dnstap allows query and response logging. -``zones`` Example ------------------ +For all queries logging, use this module in the *default* template. For +zone-specific logging, use this module in the proper zone configuration. :: - zones { - - # Shared options for all listed zones - storage "/var/lib/knot"; - ixfr-from-differences off; - semantic-checks off; - disable-any off; - notify-timeout 60; - notify-retries 5; - zonefile-sync 0; - ixfr-fslimit 1G; - dnssec-enable on; - dnssec-keydir "keys"; - signature-lifetime 60d; - serial-policy increment; - example.com { - storage "samples"; - file "example.com.zone"; - ixfr-from-differences off; - disable-any off; - semantic-checks on; - notify-timeout 60; - notify-retries 5; - zonefile-sync 0; - dnssec-keydir "keys"; - dnssec-enable off; - signature-lifetime 30d; - serial-policy increment; - xfr-in server0; - xfr-out server0, server1; - notify-in server0; - notify-out server0, server1; - } - } - -.. _zones List of zone semantic checks: - -``zones`` List of zone semantic checks --------------------------------------- - -The ``semantic-checks`` statement turns on extra zone file semantic -checks. Several checks are enabled by default and cannot be turned -off. If an error is found using these mandatory checks, the zone file -will not be loaded. Upon loading a zone file, occurred errors and -counts of their occurrence will be logged to *stderr*. These -checks are the following: - -* An extra record together with CNAME record (except for RRSIG and DS) -* CNAME link chain length greater than 10 (including infinite cycles) -* DNAME and CNAME records under the same owner (RFC 2672) -* CNAME and DNAME wildcards pointing to themselves -* SOA record missing in the zone (RFC 1034) -* DNAME records having records under it (DNAME children) (RFC 2672) - -Following checks have to be turned on using ``semantic-checks`` and a -zone containing following errors will be loaded even upon discovering -an error: + mod-dnstap: + - id: STR + sink: STR -- Missing NS record at the zone apex -- Missing glue A or AAAA records -- Broken or non-cyclic NSEC(3) chain -- Wrong NSEC(3) type bitmap -- Multiple NSEC records at the same node -- Missing NSEC records at authoritative nodes -- Extra record types under same name as NSEC3 record (this is - RFC-valid, but Knot will not serve such a zone correctly) -- NSEC3-unsecured delegation that is not part of Opt-out span -- Wrong original TTL value in NSEC3 records -- Wrong RDATA TTL value in RRSIG record -- Signer name in RRSIG RR not the same as in DNSKEY -- Signed RRSIG -- Not all RRs in node are signed -- Wrong key flags or wrong key in RRSIG record (not the same as ZSK) +.. _mod-dnstap_id: -.. _log: +id +-- -``log`` Statement -================= +A module identifier. -.. _log Syntax: +.. _mod-dnstap_sink: -``log`` Syntax --------------- +sink +---- + +A sink path, which can either be a file or a UNIX socket prefixed with +``unix:``. + +Default: empty + +.. _Module synth-record: + +Module synth-record +=================== + +This module is able to synthetise either forward or reverse records for the +given prefix and subnet. :: - log { - [ log_name { - [ category severity; ] - } ] - [ log_file filename { - [ category severity; ] - } ] - } + mod-synth-record: + - id: STR + type: forward | reverse + prefix: STR + zone: DNAME + ttl: INT + address: ADDR[/INT] -.. _log Statement Definition and Grammar: +.. _mod-synth-record_id: -``log`` Statement Definition and Grammar ----------------------------------------- +id +-- -The ``log`` statement configures logging output of Knot DNS. You can -configure Knot DNS to log into file or system log. There are several -logging categories to choose from. Each log message has its severity -and user can configure severities for each log destination. +A module identifier. -In case of missing log section, severities from ``warning`` and more -serious will be logged to both ``stderr`` and ``syslog``. The -``info`` and ``notice`` severities will be logged to the ``stdout``. +.. _mod-synth-record_type: -.. _log_name: +type +---- -``log_name`` -^^^^^^^^^^^^ +The type of generated records. -``log_name`` should be replaced with one of 3 symbolic log names: +Possible values: -* ``stdout`` - logging to standard output -* ``stderr`` - logging to standard error output -* ``syslog`` - logging to syslog (or systemd journal, if systemd support is enabled) +- ``forward`` - Forward records +- ``reverse`` - Reverse records -.. _category: +Default: empty -``category`` -^^^^^^^^^^^^ +.. _mod-synth-record_prefix: -Knot DNS allows user to choose from these logging categories: +prefix +------ -* ``server`` - Messages related to general operation of the server. -* ``zone`` - Messages related to zones, zone parsing and loading. -* ``any`` - All categories. +A record owner prefix. -If systemd support is enabled, the log messages in the `zone` category are -given the `ZONE` field containing a name of the zone. The field can be used -to filter the log entries in the journal. +Caution: *prefix* doesn’t allow dots, address parts in the synthetic names are +separated with a dash. -.. _severity: +Default: empty -``severity`` -^^^^^^^^^^^^ +.. _mod-synth-record_zone: -Knot DNS has the following logging severities: +zone +---- -* ``debug`` - Debug messages, must be turned on at compile time (:ref:`Enabling debug messages in server`). -* ``info`` - Informational message. -* ``notice`` - Server notices and hints. -* ``warning`` - Warnings that might require user action. -* ``error`` - Recoverable error. Action should be taken. -* ``critical`` - Non-recoverable error resulting in server shutdown. +A zone name suffix (only valid for :ref:`reverse type<mod-synth-record_type>`). -Each severity level includes all more serious levels, i.e. ``warning`` severity -also includes ``error`` and ``critical`` severities. +Default: empty -.. _log_file: +.. _mod-synth-record_ttl: -``log_file`` -^^^^^^^^^^^^ +ttl +--- -``log_file`` is either absolute or relative path to file user wants to -log to. See following example for clarification. +Time to live of the generated records. -.. _log Example: +Default: 3600 -log Example ------------ +.. _mod-synth-record_address: + +address +------- + +A network subnet in the form of *address/prefix*. + +Default: empty + +.. _Module dnsproxy: + +Module dnsproxy +=============== + +The module catches all unsatisfied queries and forwards them to the configured +server for resolution. :: - log { + mod-dnsproxy: + - id: STR + remote: ADDR[@INT] - syslog { - any error; - zone warning, notice; - server info; - } +.. _mod-dnsproxy_id: - stderr { - any error, warning; - } +id +-- - file "/tmp/knot-sample/knotd.debug" { - server debug; - } - } +A module identifier. -.. _include: +.. _mod-dnsproxy_remote: -``include`` Statement -===================== +remote +------ -The ``include`` statement is a special statement which can be used -almost anywhere on any level in the configuration file. It allows -inclusion of another file or all files in the given directory. +An IP address of the destination server. Optional port specification +(default is 53) can be appended to the address using ``@`` separator. -The path of the included file can be either absolute or relative to a -configuration file currently being processed. +Default: empty -.. _include Syntax: +.. _Module rosedb: -``include`` Syntax ------------------- +Module rosedb +============= + +The module provides a mean to override responses for certain queries before +the record is searched in the available zones. :: - include "filename"; - include "dirname"; + mod-rosedb: + - id: STR + dbdir: STR -.. _include Examples: +.. _mod-rosedb_id: -``include`` Examples --------------------- +id +-- -:: +A module identifier. + +.. _mod-rosedb_dbdir: - include "keys.conf"; +dbdir +----- - remotes { - ctl { - address 127.0.0.1; - key knotc-key; - } - include "remotes.conf"; - } +A path to the directory where the database will is stored. - include "zones"; +Default: empty diff --git a/doc/requirements.rst b/doc/requirements.rst index 19270e471..bc17c75c3 100644 --- a/doc/requirements.rst +++ b/doc/requirements.rst @@ -1,17 +1,20 @@ .. meta:: :description: reStructuredText plaintext markup language -Knot DNS Resource Requirements -============================== +.. _Requirements: -Hardware requirements ---------------------- +************ +Requirements +************ + +Hardware +======== Knot DNS requirements are not very demanding for typical installations, and a commodity server or a virtual solution will be sufficient in most cases. -However please note that there are some scenarios that will require +However, please note that there are some scenarios that will require administrator attention and testing of exact requirements before deploying Knot DNS in production. These cases include deployment for a large number of zones (DNS hosting), a large number of records in one @@ -30,7 +33,7 @@ Memory requirements ------------------- Knot DNS implementation focuses on performance and thus can be quite -demanding for memory. The rough estimate for memory requirements is +demanding for memory. The rough estimate for memory requirements is 3 times of the size of the zone in text format. Again this is only an estimate and you are advised to do your own measurements before deploying Knot DNS into production. @@ -40,8 +43,8 @@ employs a Read-Copy-Update mechanism instead of locking and thus requires twice the amount of memory for the duration of incoming transfers. -Supported operating system --------------------------- +Operating system +================ Knot DNS itself is written in a portable way, but it depends on several libraries. Namely userspace-rcu, which could be a constraint diff --git a/doc/running.rst b/doc/running.rst index 9a9274a60..0ea1a2e5e 100644 --- a/doc/running.rst +++ b/doc/running.rst @@ -1,11 +1,11 @@ .. meta:: :description: reStructuredText plaintext markup language -.. _Running Knot DNS: +.. _Running: -**************** -Running Knot DNS -**************** +******* +Running +******* The Knot DNS server part ``knotd`` can run either in the foreground or in the background, with the ``-d`` option. When run in the foreground, it doesn't create a PID file. @@ -15,9 +15,10 @@ The tool ``knotc`` is designed as a front-end for user, making it easier to cont server daemon. If you want to control the daemon directly, use ``SIGINT`` to quit the process or ``SIGHUP`` to reload configuration. -If you do not pass any configuration via ``-c`` option, it will try to -search configuration in default path that is ``SYSCONFDIR/knot.conf``. The ``SYSCONFDIR`` -depends on what you passed to the ``./configure``, usually ``/etc``. +If you pass neither configuration file (``-c`` parameter) nor configuration +database (``-C`` parameter), server will try to use the default configuration +file stored in ``SYSCONFDIR/knot/knot.conf`` (configured with +``--with-configdir=path``) Example of server start as a daemon:: @@ -30,24 +31,24 @@ Example of server stop:: For a complete list of actions refer to ``knotd -h`` and ``knotc -h`` or corresponding man pages. -Also, the server needs to create several files in order to run properly. These -files are stored in the folowing directories. +Also, the server needs to create :ref:`server_rundir` and :ref:`template_storage` +directories in order to run properly. -``storage`` (:ref:`storage`): +.. _Configuration database: -* *Zone files* - default directory for storing zone files. This can be - overriden using absolute zone file location. +Configuration database +====================== + +In the case of a huge configuration file, the configuration can be preloaded +into the server`s configuration database:: -* *Journal files* - each zone has a journal file to store differences - for IXFR and dynamic updates. Journal for zone ``example.com`` will - be placed in ``example.com.diff.db``. + $ knotc import input.conf -``rundir`` (:ref:`rundir`): +Also the configuration database can be exported into the configuration file:: -* *PID file* - is created automatically when the server is run in background. + $ knotc export output.conf -* *Control sockets* - as a default, UNIX sockets are created here, but - this can be overriden. +It is recommended to process these operations without server running. .. _Running a slave server: @@ -55,12 +56,10 @@ Running a slave server ====================== Running the server as a slave is very straightforward as you usually -bootstrap zones over AXFR and thus avoid any manual zone compilation. +bootstrap zones over AXFR and thus avoid any manual zone operations. In contrast to AXFR, when the incremental transfer finishes, it stores -the differences in a journal file and doesn't update the zone file -immediately. There is a timer that checks periodically for new -differences and updates the zone file. You can configure this timer -with the ``zonefile-sync`` statement in ``zones`` (:ref:`zones`). +the differences in the journal file and doesn't update the zone file +immediately but after :ref:`template_zonefile-sync` period elapses. .. _Running a master server: @@ -96,14 +95,14 @@ action:: $ knotc -c master.conf reload -If you want *IXFR-out* differences created from changes you make to a -zone file, enable :ref:`ixfr-from-differences` in ``zones`` statement, -then reload your server as seen above. If *SOA*'s *serial* is not -changed no differences will be created. +If you want to enable ixfr differences creation from changes you make to a +zone file, enable :ref:`template_ixfr-from-differences` in the zone configuration +and reload your server as seen above. If *SOA*'s *serial* is not changed, +no differences will be created. If you want to refresh the slave zones, you can do this with the ``knotc refresh`` action:: $ knotc -c slave.conf refresh -For the zone retransfer, there is also additional command ``-f``. +For the zone retransfer, there is also an additional command ``-f``. diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index 4a1ea03cb..83e692345 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -1,37 +1,36 @@ .. meta:: :description: reStructuredText plaintext markup language +.. _Troubleshooting: + *************** Troubleshooting *************** -First of all, check the logs (:ref:`log`). By default, Knot DNS logs -all error messages to syslog. Enabling at least the ``warning`` -message severity may help you identify some problems. +First of all, check the logs (:ref:`Logging section`). Enabling at least +the ``warning`` message severity may help you identify some problems. .. _Submitting a bugreport: Submitting a bugreport ====================== -If you are unable to solve the problem by yourselves, you can submit a -bugreport to the Knot DNS team. For security issues (e.g. crash) do -not use the public mailinglist. Instead, write to -`knot-dns@labs.nic.cz <mailto:knot-dns@labs.nic.cz>`_. All other bugs -and questions may be directed to the Knot DNS users mailinglist +If you are unable to solve the problem by yourself, you can submit a +bugreport to the Knot DNS team. For security issues (e.g. crash) do +not use the public mailing list. Instead, write to +`knot-dns@labs.nic.cz <mailto:knot-dns@labs.nic.cz>`_. All other bugs +and questions may be directed to the Knot DNS users mailing list (`knot-dns-users@lists.nic.cz <mailto:knot-dns-users@lists.nic.cz>`_). The bugreport should contain at least: -* Knot DNS version and type of installation (source, package, etc.), -* type and version of your operating system, -* basic hardware information, -* description of the bug, -* log output of all messages (category ``any``) with severity Info and - higher (severities ``info, notice, warning, error``, or ``any`` if - debug messages are not turned on (see below)), -* steps to reproduce the bug (if known), -* backtrace (if the bug caused a crash; see next section). +* Knot DNS version and type of installation (source, package, etc.) +* Type and version of your operating system +* Basic hardware information +* Description of the bug +* Log output of all messages (category ``any``, severity ``info``) +* Steps to reproduce the bug (if known) +* Backtrace (if the bug caused a crash; see next section) If it is possible, the actual configuration file and/or zone file(s) will be very useful as well. @@ -42,22 +41,22 @@ Generating backtrace ==================== There are several ways to achieve that, the most common way is to -leave core dumps and then extract a backtrace from it. This doesn't +leave core dumps and then extract a backtrace from it. This doesn't affect any server operation, you just need to make sure the OS is configured to generate them:: - $ ulimit -c unlimited # enable unlimited core dump size + $ ulimit -c unlimited # Enable unlimited core dump size ... - $ gdb $(which knotd) core.<KNOT_PID> # start gdb on a core dump - (gdb) thread apply all bt # extract backtrace from all threads + $ gdb $(which knotd) core.<KNOT_PID> # Start gdb on the core dump + (gdb) thread apply all bt # Extract backtrace from all threads (gdb) q If the error is repeatable, you can run the binary in a ``gdb`` -debugger or attach the debugger to the running process. The backtrace +debugger or attach the debugger to the running process. The backtrace from a running process is generally useful when debugging problems like stuck process and similar:: - $ knotc -c knot.conf start + $ knotd -c knot.conf $ sudo gdb --pid <KNOT_PID> (gdb) continue ... @@ -70,49 +69,44 @@ Debug messages ============== In some cases the aforementioned information may not be enough to find -and fix the bug. In these cases it may be useful to turn on debug +and fix the bug. In these cases it may be useful to turn on debug messages. -Two steps are required in order to log debug messages. First you need -to allow the debug messages in the server. Then the logging must be -configured to log debug messages (:ref:`log`). It is recommended to -log these messages to a file. Firstly, the debug output may be rather +Two steps are required in order to log debug messages. First you need +to allow the debug messages in the server. Then the logging must be +configured to log debug messages (:ref:`Logging section`). It is recommended to +log these messages to a file. Firstly, the debug output may be rather large and secondly, it is easier to use the data for debugging. -.. _Enabling debug messages in server: +.. _Enabling debug messages: -Enabling debug messages in server ---------------------------------- +Enabling debug messages +----------------------- Allowing debug messages in the server is possible only when -configuring the sources. Two ``configure`` options are required +configuring the sources. Two ``configure`` options are required to do this: * The ``--enable-debug`` option specifies the server modules for which - you want to enable debug messages. One or more of the following + you want to enable debug messages. One or more of the following modules may be listed, separated by commas: * ``server`` - Messages related to networking, threads and low-level journal handling. - * ``zones`` - All operations with zones - loading, updating, saving, - timers, high-level journal management. - * ``xfr`` - AXFR, IXFR and NOTIFY handling. - * ``packet`` - Packet parsing and response creation. - * ``rr`` - Details of processed resource records. + * ``zones`` - All operations with zones (loading, updating, saving, + timers, high-level journal management). * ``ns`` - Query processing, high-level handling of all requests - (transfers, NOTIFY, normal queries). + (transfers, notifies, normal queries). * ``loader`` - Zone loading and semantic checks. * ``dnssec`` - DNSSEC operations. * The ``--enable-debuglevel`` option is used to specify the verbosity - of the debug output. Be careful with this, as the ``details`` + of the debug output. Be careful with this, as the ``details`` verbosity may produce really large logs (in order of GBs). There are three levels of verbosity: ``brief``, ``verbose`` and ``details``. -.. _Debug messages Example: +Example: -Debug messages Example ----------------------- :: $ ./configure --enable-debug=server,zones --enable-debuglevel=verbose diff --git a/man/knot.conf.5.in b/man/knot.conf.5.in index 31f50f430..23b8c3f1a 100644 --- a/man/knot.conf.5.in +++ b/man/knot.conf.5.in @@ -1,474 +1,872 @@ -.TH "knot.conf" "5" "@RELEASE_DATE@" "CZ.NIC Labs" "Knot DNS, version @VERSION@" +.\" Man page generated from reStructuredText. +. +.TH "KNOT.CONF" "5" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" .SH NAME -.B knot.conf -\- Configuration file manual for Knot DNS server. -.SH SYNOPSIS -.B knot.conf +knot.conf \- Knot DNS configuration file +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. .SH DESCRIPTION -.B knot.conf -is an overview of all config options for \fBknotc\fR and \fBknotd\fR. -.SH EXAMPLE +.sp +Configuration file for Knot DNS uses simplified YAML format. Simplified means +that not all features are supported. +.sp +For the configuration items description, there are some symbol with the +folowing meaning: +.INDENT 0.0 +.IP \(bu 2 +\fIINT\fP \- Integer +.IP \(bu 2 +\fISTR\fP \- Textual string +.IP \(bu 2 +\fIHEXSTR\fP \- Hexadecimal string (with \fB0x\fP prefix) +.IP \(bu 2 +\fIBOOL\fP \- Boolean value (\fBon\fP or \fBoff\fP) +.IP \(bu 2 +\fITIME\fP \- Number of seconds, integer with possible time mutliplier suffix +(\fBs\fP ~ 1, \fBm\fP ~ 60, \fBh\fP ~ 3600 or \fBd\fP ~ 24 * 3600) +.IP \(bu 2 +\fISIZE\fP \- Number of bytes, integer with possible size multiplier suffix +(\fBB\fP ~ 1, \fBK\fP ~ 1024, \fBM\fP ~ 1024^2 or \fBG\fP ~ 1024^3) +.IP \(bu 2 +\fIBASE64\fP \- Base64 encoded string +.IP \(bu 2 +\fIADDR\fP \- IPv4 or IPv6 address +.IP \(bu 2 +\fIDNAME\fP \- Domain name +.IP \(bu 2 +\&... \- Multi\-valued item, order of the values is preserved +.IP \(bu 2 +[ ] \- Optional value +.IP \(bu 2 +| \- Choice +.UNINDENT +.sp +There are 8 main sections (\fBserver\fP, \fBkey\fP, \fBacl\fP, \fBcontrol\fP, +\fBremote\fP, \fBtemplate\fP, \fBzone\fP and \fBlog\fP) and module sections with +\fBmod\-\fP prefix . Most of the sections (excluding \fBserver\fP and +\fBcontrol\fP) are sequences of settings blocks. Each settings block +begins with a unique identifier, which can be used as a reference from other +sections (such identifier must be defined in advance). +.sp +Multi\-valued item can be specified either as a YAML sequence [val1, val2, ...] +or as more single\-valued items each on the extra line. +.sp +If an item value contains spaces or other special characters, it is necessary +to double quote such value with \fB"\fP \fB"\fP\&. +.SH COMMENTS +.sp +A comment begins with a \fB#\fP character and is ignored during the processing. +Also each configuration section or sequence block allows to specify permanent +comment using \fBcomment\fP item which is stored in the server beside the +configuration. +.SH INCLUDES +.sp +Another configuration file or all configuration files in a directory can be +included at the top level in the current file. If the file or directory path +is not absolute, then it is relative to the current file directory. +.INDENT 0.0 +.INDENT 3.5 +.sp .nf -# -# There are 8 main sections of this config file: -# system, interfaces, keys, remotes, groups, zones, control and log -# - -# This is a comment. - -# Section 'system' contains general options for the server -system { - - # Identity of the server (see RFC 4892). - # Used for answer to CH TXT 'id.server' or 'hostname.bind' - # Use string format "text" - # Or on|off. When 'on', FQDN hostname will be used as default. - identity off; - - # Version of the server (see RFC 4892). - # Used for answer to CH TXT 'version.server' or 'version.bind' - # Use string format "text" - # Or on|off. When 'on', current server version will be used as default. - version off; - - # Server identifier - # Use string format "text" - # Or hexstring 0x01ab00 - # Or on|off. When 'on', FQDN hostname will be used as default. - nsid off; - - # Directory for storing run-time data - # e.g. PID file and control sockets - # default: ${localstatedir}/run/knot, configured with --with-rundir - rundir "/var/run/knot"; - - # Number of workers per interface - # This option is used to force number of threads used per interface - # Default: unset (auto-estimates optimal value from the number of online CPUs) - # workers 3; - - # Number of background workers - # This option is used to set number of threads used to execute background - # operations (e.g., zone loading, zone signing, XFR zone updates, ...) - # Default: unset (auto-estimates optimal value from the number of online CPUs) - # background-workers 4; - - # Start server asynchronously - # When asynchronous startup is enabled, server doesn't wait for the zones to be loaded, and - # starts responding immediately lame answers until the zone loads. This may be useful in - # some scenarios, but it is disabled by default. - # Default: disabled (wait for zones to be loaded before answering) - asynchronous-start off; - - # User for running server - # May also specify user.group (e.g. knot.users) - # user knot.users; - - # Maximum idle time between requests on a TCP connection - # It is also possible to suffix with unit size [s/m/h/d] - # f.e. 1s = 1 second, 1m = 1 minute, 1h = 1 hour, 1d = 1 day - # Default: 20s - max-conn-idle 20s; - - # Maximum time between newly accepted TCP connection and first query - # This is useful to disconnect inactive connections faster - # It is also possible to suffix with unit size [s/m/h/d] - # f.e. 1s = 1 second, 1m = 1 minute, 1h = 1 hour, 1d = 1 day - # Default: 5s - max-conn-handshake 5s; - - # Maximum time to wait for a reply to SOA query - # It is also possible to suffix with unit size [s/m/h/d] - # f.e. 1s = 1 second, 1m = 1 minute, 1h = 1 hour, 1d = 1 day - # Default: 10s - max-conn-reply 10s; - - # Number of parallel TCP clients - # Set this below the descriptor limit to avoid resource exhaustion - # Default: 100 - max-tcp-clients 100; - - # Number of parallel transfers - # This number also includes pending SOA queries - # Minimal value is number of CPUs - # Default: 10 - transfers 10; - - # Rate limit - # in queries / second - # Default: off (=0) - rate-limit 0; - - # Rate limit bucket size - # Number of hashtable buckets, set to reasonable value as default. - # We chose a reasonably large prime number as it's used for hashtable size, - # it is recommended to do so as well due to better distribution. - # Rule of thumb is to set it to about 1.2 * (maximum_qps) - # Memory cost is approx. 32B per bucket - # Default: 393241 - rate-limit-size 393241; - - # Rate limit SLIP - # Each Nth blocked response will be sent as truncated, this is a way to allow - # legitimate requests to get a chance to reconnect using TCP - # Default: 1 - rate-limit-slip 1; - - # Maximum EDNS0 UDP payload size - # Default value: 4096 - max-udp-payload 4096; -} - -# Includes can be placed anywhere at any level in the configuration file. The -# file name can be relative to current file or absolute. -# -# This include includes keys which are commented out in next section. -include "knot.keys.conf"; - -# Section 'keys' contains list of TSIG keys -#keys { -# -# # TSIG key -# # -# # format: name key-type "<key>"; -# # where key-type may be one of the following: -# # hmac-md5 -# # hmac-sha1 -# # hmac-sha224 -# # hmac-sha256 -# # hmac-sha384 -# # hmac-sha512 -# # and <key> is the private key -# key0.server0 hmac-md5 "Wg=="; -# -# # TSIG key for zone -# key0.example.com hmac-md5 "==gW"; -#} - -# Section 'interfaces' contains definitions of listening interfaces. -interfaces { - - # Interface entry - # - # Format 1: <name> { address <address>; [port <port>;] } - ipv4 { # <name> is an arbitrary symbolic name - address 127.0.0.1; # <address> may be ither IPv4 or IPv6 address - port 53531; # port is required for XFR/IN and NOTIFY/OUT - } - - # Format 2: <name> { address <address>@<port>; } - # shortipv4 { - # address 127.0.0.1@53532; - #} - - # Format 1 (IPv6 interface) - # ipv6 { - # address ::1@53533; - # } - - # Format 2 (IPv6 interface) - # ipv6b { - # address [::1]@53534; - # } - -} - -# Section 'remotes' contains symbolic names for remote servers. -# Syntax for 'remotes' is the same as for 'interfaces'. -remotes { - - # Remote entry - # - # Format 1: <name> { address <address>; [port <port>;] } - server0 { # <name> is an arbitrary symbolic name - address 127.0.0.1; # <address> may be ither IPv4 or IPv6 address - port 53531; # port is optional (default: 53) - key key0.server0; # (optional) specification of TSIG key associated for this remote - via ipv4; # (optional) source interface for queries - via 82.35.64.59; # (optional) source interface for queries, direct IPv4 - via [::cafe]; # (optional) source interface for queries, direct IPv6 - } - - # Format 2: <name> { address <address>@<port>; } - server1 { - address 127.0.0.1@53001; - } - - admin-alice { - address 192.168.100.1; - } - - admin-bob { - address 192.168.100.2; - } -} - -groups { - admins { admin-alice, admin-bob } -} - -# Section 'control' specifies on which interface to listen for RC commands -control { - - # Default: $(run_dir)/knot.sock - listen-on "knot.sock"; - - # As an alternative, you can use an IPv4/v6 address and port - # Same syntax as for 'interfaces' items - # listen-on { address 127.0.0.1@5533; } - - # Specifies ACL list for remote control - # Same syntax as for ACLs in zones - # List of remotes or groups delimited by comma - # Notice: keep in mind that ACLs bear no effect with UNIX sockets - # allow server0, admins; -} - -# Section 'zones' contains information about zones to be served. -zones { - - # Shared options for all listed zones - # - - # This is a default directory to place slave zone files, journals etc. - # default: ${localstatedir}/lib/knot, configured with --with-storage - storage "/var/lib/knot"; - - # Build differences from zone file changes. EXPERIMENTAL feature. - # Possible values: on|off - # Default value: off - ixfr-from-differences off; - - # Enable semantic checks for all zones (if 'on') - # Possible values: on|off - # Default value: off - semantic-checks off; - - # Disable ANY type queries for authoritative answers (if 'on') - # Possible values: on|off - # Default value: off - disable-any off; - - # NOTIFY response timeout - # Possible values: <1,...> (seconds) - # Default value: 60 - notify-timeout 60; - - # Number of retries for NOTIFY - # Possible values: <1,...> - # Default value: 5 - notify-retries 5; - - # Timeout for syncing changes from zone database to zonefile - # Possible values: <1..INT_MAX> (seconds) - # Default value: 0s - immediate sync - # It is also possible to suffix with unit size [s/m/h/d] - # f.e. 1s = 1 day, 1m = 1 minute, 1h = 1 hour, 1d = 1 day - # Warning: If serving a large zone, set this to a larger value - # to keep disk load down. - zonefile-sync 1h; - - # File size limit for IXFR journal - # Possible values: <1..INT_MAX> - # Default value: N/A (infinite) - # It is also possible to suffix with unit size [k/M/G] - # f.e. 1k, 100M, 2G - ixfr-fslimit 1G; - - # Enable DNSSEC online signing (EXPERIMENTAL) - # Possible values: on | off; - # Default value: off - # dnssec-enable off; - - # Location of DNSSEC signing keys (relative to storage dir). - # Default value: not set - # dnssec-keydir "keys"; - - # Validity period for DNSSEC signatures - # Possible values: <10801..INT_MAX> (seconds) - # Default value: 30d (30 days or 2592000 seconds) - # It is also possible to suffix with unit size [s/m/h/d] - # f.e. 1s = 1 day, 1m = 1 minute, 1h = 1 hour, 1d = 1 day - # The signatures are refreshed one tenth of the signature lifetime before - # the signature expiration (i.e., 3 days before by default) - # signature-lifetime 30d; - - # Serial policy after DDNS and automatic DNSSEC signing. - # Possible values: increment | unixtime - # Default value: increment - # serial-policy increment; - - # Query modules are dynamically loaded modules that can alter query plan processing - # Configuration is always module-specific, but passed as a simple string here - # Query modules listed here are effective for all queries (even those without assigned zone) - query_module { - module_name "configuration string"; - } - - # Zone entry - # - # Format: <zone-name> { file "<path-to-zone-file>"; } - example.com { # <zone-name> is the DNS name of the zone (zone root) - # Zone specific storage directory (relative to storage in zones section). - # default: inherited from zones section - storage "example.com"; - - # <path-to-zone-file> may be either absolute or relative, in which case - # it is considered relative to the current directory from which the server - # was started. - file "samples/example.com.zone"; - - # Build differences from zone file changes - # Possible values: on|off - # Default value: off - ixfr-from-differences off; - - # Disable ANY type queries for authoritative answers (if 'on') - # Possible values: on|off - # Default value: off - disable-any off; - - # Enable zone semantic checks - # Possible values: on|off - # Default value: off - semantic-checks on; - - # NOTIFY response timeout (specific for current zone) - # Possible values: <1,...> (seconds) - # Default value: 60 - notify-timeout 60; - - # Number of retries for NOTIFY (specific for current zone) - # Possible values: <1,...> - # Default value: 5 - notify-retries 5; - - # Timeout for syncing changes from zone database to zonefile - # Possible values: <1..INT_MAX> (seconds) - # Default value: inherited from zones.zonefile-sync - # It is also possible to suffix with unit size [s/m/h/d] - # f.e. 1s = 1 second, 1m = 1 minute, 1h = 1 hour, 1d = 1 day - zonefile-sync 1h; - - # File size limit for IXFR journal - # Possible values: <1..INT_MAX> - # Default value: N/A (infinite) - # It is also possible to suffix with unit size [k/M/G] - # f.e. 1k, 100M, 2G - ixfr-fslimit 1G; - - # Location of DNSSEC signing keys (relative to storage directory in zone). - # Default value: inherited from zones section - dnssec-keydir "keys"; - - # Enable DNSSEC online signing (EXPERIMENTAL) - # Possible values: on | off; - # Default value: inherited from zones section - dnssec-enable off; - - # Validity period for DNSSEC signatures - # Possible values: <10801..INT_MAX> (seconds) - # Default value: 30d (30 days or 2592000 seconds) - # It is also possible to suffix with unit size [s/m/h/d] - # f.e. 1s = 1 day, 1m = 1 minute, 1h = 1 hour, 1d = 1 day - # The lower limit is because the server will trigger resign when any of the - # signatures expires in 7200 seconds or less and it was chosen as a - # reasonable value with regard to signing overhead. - # signature-lifetime 30d; - - # Serial policy after DDNS and automatic DNSSEC signing. - # Possible values: increment | unixtime - # Default value: increment - # serial-policy increment; - - # XFR master server - xfr-in server0; - - # ACL list of XFR slaves - xfr-out server0, server1; - - # ACL list of servers allowed to send NOTIFY queries - notify-in server0; - - # List of servers to send NOTIFY to - notify-out server0, server1; - - # List of servers to allow UPDATE queries - update-in server0, admins; - - # Query modules are dynamically loaded modules that can alter query plan processing - # Configuration is always module-specific, but passed as a simple string here - query_module { - module_one "configuration string"; - module_two "specific configuration string"; - } - - } -} - -# Section 'log' configures logging of server messages. -# -# Logging recognizes 3 symbolic names of log devices: -# stdout - Standard output -# stderr - Standard error output -# syslog - Syslog -# -# In addition, arbitrary number of log files may be specified (see below). -# -# Log messages are characterized by severity and category. -# Supported severities: -# debug - Debug messages and below. Must be turned on at compile time. -# info - Informational messages and below. -# notice - Notices and hints and below. -# warning - Warnings and below. An action from the operator may be required. -# error - Recoverable error and below. Some action should be taken. -# critical - Non-recoverable errors resulting in server shutdown. -# (Not supported yet.) -# -# Categories designate the source of the log message and roughly correspond -# to server modules -# Supported categories: -# server - Messages related to general operation of the server. -# zone - Messages related to zones, zone parsing and loading. -# any - All categories -# -# Default settings (in case there are no entries in 'log' section or the section -# is missing at all): -# -# stderr { any error; } -# syslog { any error; } -log { - - # Format 1: - # <log> { - # <category1> <severity1>; - # <category2> <severity2>; - # ... - # } - - syslog { - # Log any error or critical to syslog - any error; - # Log all (excluding debug) from server to syslog - server info; - } - - # Log any warning, error or critical to stderr - stderr { - any warning; - } - - # Format 2: - # file <path> { # <path> is absolute or relative path to log file - # <category1> <severity1>; - # <category2> <severity2>; - # } - - file "/tmp/knot-sample/knotd.debug" { - server debug; - } -} +.ft C +include: STR +.ft P .fi -.SH "SEE ALSO" -.BR knotd (8), -.BR knotc (8). +.UNINDENT +.UNINDENT +.SH SERVER SECTION +.sp +General options related to the server. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +server: + identity: [STR] + version: [STR] + nsid: [STR|HEXSTR] + rundir: STR + user: STR[:STR] + pidfile: STR + workers: INT + background\-workers: INT + asynchronous\-start: BOOL + max\-conn\-idle: TIME + max\-conn\-handshake: TIME + max\-conn\-reply: TIME + max\-tcp\-clients: INT + max\-udp\-payload: SIZE + transfers: INT + rate\-limit: INT + rate\-limit\-slip: INT + rate\-limit\-size: INT + listen: ADDR[@INT] ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS identity +.sp +An identity of the server returned in the response for the query for TXT +record \fBid.server.\fP or \fBhostname.bind.\fP in the CHAOS class (see RFC 4892). +If empty, FQDN hostname is used. +.sp +Default: disabled +.SS version +.sp +A version of the server software returned in the response for the query +for TXT record \fBversion.server.\fP or \fBversion.bind.\fP in the CHAOS +class (see RFC 4892). If empty, automatic version is used. +.sp +Default: disabled +.SS nsid +.sp +A DNS name server identifier (see RFC 5001). If empty, FQDN hostname is used. +.sp +Default: disabled +.SS rundir +.sp +A path for storing run\-time data (PID file, unix sockets, etc.). +.sp +Default: \fB${localstatedir}/run/knot\fP (configured with \fB\-\-with\-rundir=path\fP) +.SS user +.sp +A system user with an optional system group (\fIuser\fP:\fIgroup\fP) under which the +server is run after starting and binding to interfaces. Linux capabilities +are employed if supported. +.sp +Default: root:root +.SS pidfile +.sp +A PID file location. +.sp +Default: \fI\%rundir\fP/knot.pid +.SS workers +.sp +A number of quering workers (threads) per server interface. +.sp +Default: auto\-estimated optimal value based on the number of online CPUs +.SS background\-workers +.sp +A number of workers (threads) used to execute background operations (zone +loading, zone updates, etc.). +.sp +Default: auto\-estimated optimal value based on the number of online CPUs +.SS asynchronous\-start +.sp +If enabled, server doesn\(aqt wait for the zones to be loaded and starts +responding immediately with SERVFAIL answers until the zone loads. +.sp +Default: off +.SS max\-conn\-idle +.sp +Maximum idle time between requests on a TCP connection. This also limits +receiving of a single query, each query must be received in this time limit. +.sp +Default: 20 +.SS max\-conn\-handshake +.sp +Maximum time between newly accepted TCP connection and the first query. +This is useful to disconnect inactive connections faster than connections +that already made at least 1 meaningful query. +.sp +Default: 5 +.SS max\-conn\-reply +.sp +Maximum time to wait for a reply to an issued SOA query. +.sp +Default: 10 +.SS max\-tcp\-clients +.sp +A maximum number of TCP clients connected in parallel, set this below the file +descriptor limit to avoid resource exhaustion. +.sp +Default: 100 +.SS transfers +.sp +A maximum number of parallel transfers, including pending SOA queries. The +minimum value is determined by the number of CPUs. +.sp +Default: 10 +.SS rate\-limit +.sp +Rate limiting is based on the token bucket scheme. Rate basically +represents number of tokens available each second. Each response is +processed and classified (based on several discriminators, e.g. +source netblock, qtype, name, rcode, etc.). Classified responses are +then hashed and assigned to a bucket containing number of available +tokens, timestamp and metadata. When available tokens are exhausted, +response is rejected or enters \fI\%SLIP\fP +(server responds with a truncated response). Number of available tokens +is recalculated each second. +.sp +Default: 0 (disabled) +.SS rate\-limit\-size +.sp +Size of hashtable buckets. The larger the hashtable, the lesser probability +of a hash collision, but at the expense of additional memory costs. Each bucket +is estimated roughly to 32 bytes. Size should be selected as a reasonably large +prime due to the better hash function distribution properties. Hash table is +internally chained and works well up to a fill rate of 90 %, general +rule of thumb is to select a prime near 1.2 * maximum_qps. +.sp +Default: 393241 +.SS rate\-limit\-slip +.sp +As attacks using DNS/UDP are usually based on a forged source address, +an attacker could deny services to the victim netblock if all +responses would be completely blocked. The idea behind SLIP mechanism +is to send each Nth response as truncated, thus allowing client to +reconnect via TCP for at least some degree of service. It is worth +noting, that some responses can\(aqt be truncated (e.g. SERVFAIL). +.sp +It is advisable not to set the slip interval to a value larger than 2, +as too large slip value means more denial of service for legitimate +requestors, and introduces excessive timeouts during resolution. +On the other hand, slipping truncated answer gives the legitimate +requestors a chance to reconnect over TCP. +.sp +Default: 1 +.SS max\-udp\-payload +.sp +Maximum EDNS0 UDP payload size. +.sp +Default: 4096 +.SS listen +.sp +One or more IP addresses where the server listens for incoming queries. +Optional port specification (default is 53) can be appended to each address +using \fB@\fP separator. Use \fB0.0.0.0\fP for all configured IPv4 addresses or +\fB::\fP for all configured IPv6 addresses. +.sp +Default: empty +.SH KEY SECTION +.sp +Shared TSIG keys used to authenticate communication with the server. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +key: + \- id: DNAME + algorithm: hmac\-md5 | hmac\-sha1 | hmac\-sha224 | hmac\-sha256 | hmac\-sha384 | hmac\-sha512 + secret: BASE64 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A key name identifier. +.SS algorithm +.sp +A key algorithm. +.sp +Default: empty +.SS secret +.sp +Shared key secret. +.sp +Default: empty +.SH ACL SECTION +.sp +Access control list rules definition. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +acl: + \- id: STR + address: ADDR[/INT] + key: key_id + action: deny | xfer | notify | update | control ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +An ACL rule identifier. +.SS address +.sp +A single IP address or network subnet with the given prefix the query +must match. +.sp +Default: empty +.SS key +.sp +A \fI\%reference\fP to the TSIG key the query must match. +.sp +Default: empty +.SS action +.sp +An ordered list of allowed actions. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBdeny\fP \- Block the matching query +.IP \(bu 2 +\fBxfer\fP \- Allow zone transfer +.IP \(bu 2 +\fBnotify\fP \- Allow incoming notify +.IP \(bu 2 +\fBupdate\fP \- Allow zone updates +.IP \(bu 2 +\fBcontrol\fP \- Allow remote control +.UNINDENT +.sp +Default: deny +.SH CONTROL SECTION +.sp +Configuration of the server remote control. +.sp +Caution: The control protocol is not encrypted, and susceptible to replay +attacks in a short timeframe until message digest expires, for that reason, +it is recommended to use default UNIX socket. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +control: + listen: ADDR[@INT] + acl: acl_id ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS listen +.sp +A UNIX socket path or IP address where the server listens for remote control +commands. Optional port specification (default is 5533) can be appended to the +address using \fB@\fP separator. +.sp +Default: \fI\%rundir\fP/knot.sock +.SS acl +.sp +An ordered list of \fI\%references\fP to ACL rules allowing the remote +control. +.sp +Caution: This option has no effect with UNIX socket. +.sp +Default: empty +.SH REMOTE SECTION +.sp +Definition of remote servers for zone transfers or notifications. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +remote: + \- id: STR + address: ADDR[@INT] + via: ADDR[@INT] + key: key_id +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A remote identifier. +.SS address +.sp +A destination IP address of the remote server. Optional destination port +specification (default is 53) can be appended to the address using \fB@\fP +separator. +.sp +Default: empty +.SS via +.sp +A source IP address which is used to communicate with the remote server. +Optional source port specification can be appended to the address using +\fB@\fP separator. +.sp +Default: empty +.SS key +.sp +A \fI\%reference\fP to the TSIG key which ise used to autenticate +the communication with the remote server. +.sp +Default: empty +.SH TEMPLATE SECTION +.sp +A template is shareable zone settings which can be used for configuration of +many zones at one place. A special default template (with \fIdefault\fP identifier) +can be used for general quering configuration or as an implicit default +configuration if a zone doesn\(aqt have a teplate specified. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +template: + \- id: STR + storage: STR + master: remote_id ... + notify: remote_id ... + acl: acl_id ... + semantic\-checks: BOOL + disable\-any: BOOL + notify\-timeout: TIME + notify\-retries: INT + zonefile\-sync: TIME + ixfr\-from\-differences: BOOL + ixfr\-fslimit: SIZE + dnssec\-enable: BOOL + dnssec\-keydir: STR + signature\-lifetime: TIME + serial\-policy: increment | unixtime + module: STR/STR ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A template identifier. +.SS storage +.sp +A data directory for storing zone files, journal files and timers database. +.sp +Default: \fB${localstatedir}/lib/knot\fP (configured with \fB\-\-with\-storage=path\fP) +.SS master +.sp +An ordered list of \fI\%references\fP to zone master servers. +.sp +Default: empty +.SS notify +.sp +An ordered list of \fI\%references\fP to remotes to which notify +message is sent if the zone changes. +.sp +Default: empty +.SS acl +.sp +An ordered list of \fI\%references\fP to ACL rules which can allow +or disallow zone transfers, updates or incoming notifies. +.sp +Default: empty +.SS semantic\-checks +.sp +If enabled, extra zone file semantic checks are turned on. +.sp +Several checks are enabled by default and cannot be turned off. An error in +mandatory checks causes zone not to be loaded. An error in extra checks is +logged only. +.sp +Mandatory checks: +.INDENT 0.0 +.IP \(bu 2 +An extra record together with CNAME record (except for RRSIG and DS) +.IP \(bu 2 +CNAME link chain length greater than 10 (including infinite cycles) +.IP \(bu 2 +DNAME and CNAME records under the same owner (RFC 2672) +.IP \(bu 2 +CNAME and DNAME wildcards pointing to themselves +.IP \(bu 2 +SOA record missing in the zone (RFC 1034) +.IP \(bu 2 +DNAME records having records under it (DNAME children) (RFC 2672) +.UNINDENT +.sp +Extra checks: +.INDENT 0.0 +.IP \(bu 2 +Missing NS record at the zone apex +.IP \(bu 2 +Missing glue A or AAAA records +.IP \(bu 2 +Broken or non\-cyclic NSEC(3) chain +.IP \(bu 2 +Wrong NSEC(3) type bitmap +.IP \(bu 2 +Multiple NSEC records at the same node +.IP \(bu 2 +Missing NSEC records at authoritative nodes +.IP \(bu 2 +Extra record types under same name as NSEC3 record (this is RFC\-valid, but +Knot will not serve such a zone correctly) +.IP \(bu 2 +NSEC3\-unsecured delegation that is not part of Opt\-out span +.IP \(bu 2 +Wrong original TTL value in NSEC3 records +.IP \(bu 2 +Wrong RDATA TTL value in RRSIG record +.IP \(bu 2 +Signer name in RRSIG RR not the same as in DNSKEY +.IP \(bu 2 +Signed RRSIG +.IP \(bu 2 +Not all RRs in node are signed +.IP \(bu 2 +Wrong key flags or wrong key in RRSIG record (not the same as ZSK) +.UNINDENT +.sp +Default: off +.SS disable\-any +.sp +If you enabled, all authoritative ANY queries sent over UDP will be answered +with an empty response and with the TC bit set. Use this option to minimize +the risk of DNS reflection attack. +.sp +Default: off +.SS notify\-timeout +.sp +The time how long will server wait for a notify response. +.sp +Default: 60 +.SS notify\-retries +.sp +The number of retries the server sends a notify message. +.sp +Default: 5 +.SS zonefile\-sync +.sp +The time after which the current zone in memory will be synced to zone file +on the disk (see \fI\%file\fP). The server will serve the latest +zone even after restart using zone journal, but the zone file on the disk will +only be synced after \fBzonefile\-sync\fP time has expired (or after manual zone +flush) This is applicable when the zone is updated via IXFR, DDNS or automatic +DNSSEC signing. +.sp +\fICaution:\fP If you are serving large zones with frequent updates where +the immediate sync to zone file is not desirable, increase the default value. +.sp +Default: 0 (immediate) +.SS ixfr\-from\-differences +.sp +If enabled, the server creates zone differences from changes you made to the +zone file upon server reload. This option is only relevant if the server +is a master server for the zone. +.sp +Default: off +.SS ixfr\-fslimit +.sp +Maximum zone journal file. +.sp +Default: unlimited +.SS dnssec\-enable +.sp +If enabled, automatic DNSSEC signing for the zone is turned on. +.sp +Default: off +.SS dnssec\-keydir +.sp +A data directory for storing DNSSEC signing keys. Non absolute path is +relative to \fI\%storage\fP\&. +.sp +Default: \fI\%storage\fP/keys +.SS signature\-lifetime +.sp +The time how long the automatically generated DNSSEC signatures should be valid. +Expiration will thus be set as current time (in the moment of signing) ++ \fBsignature\-lifetime\fP\&. The signatures are refreshed one tenth of the +signature lifetime before the signature expiration (i.e. 3 days before the +expiration with the default value). Minimum possible value is 10801. +.sp +Default: 30 * 24 * 3600 +.SS serial\-policy +.sp +Specifies how the zone serial is updated after a dynamic update or +automatic DNSSEC signing. If the serial is changed by the dynamic update, +no change is made. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBincrement\fP \- The serial is incremented according to serial number arithmetic +.IP \(bu 2 +\fBunixtime\fP \- The serial is set to the current unix time +.UNINDENT +.sp +\fICaution:\fP If your serial was in other than unix time format, be careful +with the transition to unix time. It may happen that the new serial will +be \(aqlower\(aq than the old one. If this is the case, the transition should be +done by hand (see RFC 1982). +.sp +Default: increment +.SS module +.sp +An ordered list of references to query modules in the form +\fImodule_name/module_id\fP\&. +.sp +Default: empty +.SH ZONE SECTION +.sp +Definitions of zones served by the server. +.sp +Zone configuration is a superset of \fI\%template configuration\fP, +so each zone configuration can contain all template configuration options which +may override possible template configuration. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +zone: + \- domain: DNAME + file: STR + template: template_id + # All template options +.ft P +.fi +.UNINDENT +.UNINDENT +.SS domain +.sp +A zone name identifier. +.SS file +.sp +A path to the zone file. Non absolute path is relative to +\fI\%storage\fP\&. +.sp +Default: \fI\%storage\fP/\fBdomain\fP\&.zone +.SS template +.sp +A \fI\%reference\fP to configuration template. If not specified +and \fIdefault\fP template exists, then the default template is used. +.sp +Default: empty +.SH LOGGING SECTION +.sp +Server can be configured to log to the standard output, standard error +output, syslog (or systemd journal if systemd is enabled) or into an arbitrary +file. +.sp +There are 6 logging severities: +.INDENT 0.0 +.IP \(bu 2 +\fBcritical\fP \- Non\-recoverable error resulting in server shutdown +.IP \(bu 2 +\fBerror\fP \- Recoverable error, action should be taken +.IP \(bu 2 +\fBwarning\fP \- Warning that might require user action +.IP \(bu 2 +\fBnotice\fP \- Server notice or hint +.IP \(bu 2 +\fBinfo\fP \- Informational message +.IP \(bu 2 +\fBdebug\fP \- Debug messages (must be turned on at compile time) +.UNINDENT +.sp +In case of missing log section, \fBwarning\fP or more serious messages +will be logged to both standard error output and syslog. The \fBinfo\fP and +\fBnotice\fP messages will be logged to standard output. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +log: + \- to: stdout | stderr | syslog | STR + server: critical | error | warning | notice | info | debug + zone: critical | error | warning | notice | info | debug + any: critical | error | warning | notice | info | debug +.ft P +.fi +.UNINDENT +.UNINDENT +.SS to +.sp +A logging output. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBstdout\fP \- Standard output +.IP \(bu 2 +\fBstderr\fP \- Standard error output +.IP \(bu 2 +\fBsyslog\fP \- Syslog +.IP \(bu 2 +\fIfile_name\fP \- File. +.UNINDENT +.SS server +.sp +Minimum severity level for messages related to general operation of the server +that are logged. +.sp +Default: empty +.SS zone +.sp +Minimum severity level for messages related to zones that are logged. +.sp +Default: empty +.SS any +.sp +Minimum severity level for all message types that are logged. +.sp +Default: empty +.SH MODULE DNSTAP +.sp +Module dnstap allows query and response logging. +.sp +For all queries logging, use this module in the \fIdefault\fP template. For +zone\-specific logging, use this module in the proper zone configuration. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mod\-dnstap: + \- id: STR + sink: STR +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A module identifier. +.SS sink +.sp +A sink path, which can either be a file or a UNIX socket prefixed with +\fBunix:\fP\&. +.sp +Default: empty +.SH MODULE SYNTH-RECORD +.sp +This module is able to synthetise either forward or reverse records for the +given prefix and subnet. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mod\-synth\-record: + \- id: STR + type: forward | reverse + prefix: STR + zone: DNAME + ttl: INT + address: ADDR[/INT] +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A module identifier. +.SS type +.sp +The type of generated records. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBforward\fP \- Forward records +.IP \(bu 2 +\fBreverse\fP \- Reverse records +.UNINDENT +.sp +Default: empty +.SS prefix +.sp +A record owner prefix. +.sp +Caution: \fIprefix\fP doesn’t allow dots, address parts in the synthetic names are +separated with a dash. +.sp +Default: empty +.SS zone +.sp +A zone name suffix (only valid for \fI\%reverse type\fP). +.sp +Default: empty +.SS ttl +.sp +Time to live of the generated records. +.sp +Default: 3600 +.SS address +.sp +A network subnet in the form of \fIaddress/prefix\fP\&. +.sp +Default: empty +.SH MODULE DNSPROXY +.sp +The module catches all unsatisfied queries and forwards them to the configured +server for resolution. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mod\-dnsproxy: + \- id: STR + remote: ADDR[@INT] +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A module identifier. +.SS remote +.sp +An IP address of the destination server. Optional port specification +(default is 53) can be appended to the address using \fB@\fP separator. +.sp +Default: empty +.SH MODULE ROSEDB +.sp +The module provides a mean to override responses for certain queries before +the record is searched in the available zones. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mod\-rosedb: + \- id: STR + dbdir: STR +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A module identifier. +.SS dbdir +.sp +A path to the directory where the database will is stored. +.sp +Default: empty +.SH AUTHOR +CZ.NIC Labs <http://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010-2015, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. diff --git a/man/knotc.8.in b/man/knotc.8.in index 85ac01bf9..da7f60e5e 100644 --- a/man/knotc.8.in +++ b/man/knotc.8.in @@ -9,10 +9,13 @@ .SS "Parameters:" .TP \fB\-c\fR, \fB\-\-config\fR \fIfile\fR -Select configuration file. +Use textual configuration file (default is @config_dir@/knot.conf). +.TP +\fB\-C\fR, \fB\-\-confdb\fR \fIdirectory\fR +Use configuration database. .TP \fB\-s\fR, \fB\-\-server\fR \fIserver\fR -Remote UNIX socket/IP address (default @run_dir@/knot.sock). +Remote UNIX socket/IP address (default is @run_dir@/knot.sock). .TP \fB\-p\fR, \fB\-\-port\fR \fIport\fR Remote server port (only for IP). @@ -21,7 +24,7 @@ Remote server port (only for IP). Use key specified on the command line (default algorithm is hmac\-md5). .TP \fB\-k\fR, \fB\-\-keyfile\fR \fIfile\fR -Use key file (as in config section 'keys'). +Use key file. .TP \fB\-f\fR, \fB\-\-force\fR Force operation \- override some checks. @@ -54,7 +57,7 @@ Check if server is running. Show status of configured zones. .TP \fBrefresh\fR [\fIzone\fR] ... -Refresh slave zones. Flag '-f' forces retransfer (zone(s) must be specified). +Refresh slave zones. Flag \fB-f\fR forces retransfer (zone(s) must be specified). .TP \fBcheckconf\fR Check current server configuration. @@ -67,6 +70,12 @@ Estimate memory consumption for zones. .TP \fBsignzone\fR \fIzone\fR ... Sign zones with available DNSSEC keys. +.TP +\fBimport\fR \fIfile\fR +Import configuration database from file. +.TP +\fBexport\fR \fIfile\fR +Export configuration database to file. Flag \fB-f\fR is required. .SH EXAMPLES .TP .B Setup a keyfile for remote control diff --git a/man/knotd.8.in b/man/knotd.8.in index 0fdb6b33a..cbd14ee4b 100644 --- a/man/knotd.8.in +++ b/man/knotd.8.in @@ -9,10 +9,14 @@ .SS "Parameters:" .TP \fB\-c\fR, \fB\-\-config\fR \fIfile\fR -Select configuration file. +Use textual configuration file (default is @config_dir@/knot.conf). .TP -\fB\-d\fR, \fB\-\-daemonize\fR=[\fIdir\fR] -Run server as a daemon. Working directory may be set. +\fB\-C\fR, \fB\-\-confdb\fR \fIdirectory\fR +Use configuration database. +.TP +\fB\-d\fR, \fB\-\-daemonize\fR=[\fIdirectory\fR] +Run server as a daemon. Working directory may be set +(default directory is /). .TP \fB\-V\fR, \fB\-\-version\fR Print version of the server. @@ -24,4 +28,4 @@ Print help and usage. .BR knot.conf (5). .SH NOTE If the \fBinfo\fR program is properly installed at your site, -the \fBinfo\ Knot\fR command should give you an access to the complete manual.
\ No newline at end of file +the \fBinfo\ Knot\fR command should give you an access to the complete manual. diff --git a/scripts/update-man.sh b/scripts/update-man.sh new file mode 100755 index 000000000..4475ef457 --- /dev/null +++ b/scripts/update-man.sh @@ -0,0 +1,14 @@ +#!/bin/bash + +pushd ../doc + +make man + +for f in ./_build/man/*; do + file=`basename $f` + echo "Processing '${file}' file..." + sed -e "s/__VERSION__/@VERSION@/g; s/__DATE__/@RELEASE_DATE@/g" ${f} > ../man/${file}.in +done + +popd + |