path: root/doc/reference.texi

@node Knot DNS Configuration Reference, , Statement Index, Top
@appendix Knot DNS Configuration Reference

This reference describes every configuration option in Knot DNS server.

@menu
* system::                      
* keys::                        
* interfaces::                  
* remotes::                     
* zones::                       
* log::                         
@end menu

@node system
@section @code{system} Statement
@stindex system

The @code{system} statement contains general options related to the
operating system and other general options which do not fit anywhere
else.

@menu
* system Syntax::               
* system Statement Definition and Usage::  
* system Example::              
@end menu

@node system Syntax
@subsection @code{system} Syntax

@example
@code{system} @code{@{}
  [ @code{identity} @code{"}@kbd{string}@code{";} ]
  [ @code{version} @code{"}@kbd{string}@code{";} ]
  [ @code{nsid} ( @code{"}@kbd{string}@code{"} | @kbd{hex_string} )@code{;} ]
  [ @code{storage} @code{"}@kbd{string}@code{";} ]
  [ @code{pidfile} @code{"}@kbd{string}@code{";} ]
  [ @code{workers} @kbd{integer}@code{;} ]
  [ @code{user} @kbd{string}[@code{.}@kbd{string}]@code{;} ]
@code{@}}
@end example

@node system Statement Definition and Usage
@subsection Statement Definition and Usage

@menu
* identity::                    
* version::                     
* nsid::                        
* storage::                     
* pidfile::                     
* workers::                     
* user::                        
@end menu

@node identity
@subsubsection identity
@vindex identity

Identity of the server (see @url{http://tools.ietf.org/html/rfc4892,RFC 4892}). Not used yet.

@example
system @{
  identity "Knot DNS";
@}
@end example

@node version
@subsubsection version
@vindex version

Version of the server (see @url{http://tools.ietf.org/html/rfc4892,RFC 4892}). Not used yet.

@example
system @{
  version "1.1.0";
@}
@end example

@node nsid
@subsubsection nsid
@vindex nsid

DNS Name Server Identifier (see @url{http://tools.ietf.org/html/rfc5001,RFC 5001}).

Use a string format "text" or a hexstring (e.g. 0x01ab00)

@example
system @{
  nsid 0x00cafe;
@}
@end example

@node storage
@subsubsection storage
@vindex storage

The working directory of Knot DNS, it is used to store compiled zone files and it is also a default location of the PID file.

@example
system @{
  storage "/var/lib/knot";
@}
@end example

@node pidfile
@subsubsection pidfile
@vindex pidfile

Specifies a custom PID file location.

Default value: @file{knot.pid} in @code{storage} directory.

@example
system @{
  pidfile "/var/run/knot.pid";
@}
@end example

@node workers
@subsubsection workers
@vindex workers

Number of workers (threads) per server interface.  This option is used to
force number of threads used per interface.

Default value: unset (auto-estimates optimal value from the number of online CPUs)

@example
system @{
  workers 16;
@}
@end example

@node user
@subsubsection user
@vindex user

System @kbd{user} or @kbd{user}.@kbd{group} under which the Knot DNS
is run after starting and binding to interfaces.
Linux capabilities (@pxref{Required libraries}) are employed if supported
and this configuration option is set.

Default value: @kbd{root.root}

@example
system @{
  user knot.knot;
@}
@end example

@node system Example
@subsection system Example

@example
system @{
  identity "Knot DNS @value{VERSION}";
  version "@value{VERSION}";
  nsid    "amaterasu";
  storage "/var/lib/knot";
  pidfile "/var/run/knot.pid";
  workers 16;
  user knot.knot;
@}
@end example

@node keys
@section @code{keys} Statement
@stindex keys

The @code{keys} statement sets up the TSIG keys used to authenticate
zone transfers.

@menu
* keys Syntax::                 
* keys Statement Definition and Usage::  
* Example::                     
@end menu

@node keys Syntax
@subsection keys Syntax

@example
keys @{
  key_id algorithm "string"; ]
  [ key_id algorithm "string"; ... ]
@}
@end example

@node keys Statement Definition and Usage
@subsection Statement Definition and Usage

@menu
* key_id::                      
@end menu

@node key_id
@subsubsection @code{key_id} Statement
@vindex key_id

The @kbd{key_id} statement defines a secret shared key for use with
TSIG.  It consists of its @kbd{name}, @kbd{algorithm} and @kbd{key} contents.

Supported algoritms:

@itemize
@item
hmac-md5
@item
hmac-sha1
@item
hmac-sha224
@item
hmac-sha256
@item
hmac-sha384
@item
hmac-sha512
@end itemize

You need to use bind or ldns utils to generate TSIG keys. Unfortunately, Knot DNS does not have any own generation utilities yet.

@example

$ 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= )
	  
@end example

Key generated in previous paragraph would be written as:

@example

keys @{
  foobar.example.com. hmac-sha256
  "rqv2WRyDgIUaHcJi03Zssor9jtG1kOpb3dPywxZfTeo=";
@}
	  
@end example

@node Example
@subsection keys Example


@example

keys @{
  key0.server0 hmac-md5 "Wg==";
  foobar.example.com. hmac-sha256 "RQ==";
@}
	
@end example

@node interfaces
@section interfaces
@stindex interfaces

The @code{interfaces} statement contains IP interfaces where Knot DNS listens for incoming queries.

@menu
* interfaces Syntax::           
* interfaces Statement Definition and Usage::  
* interfaces Examples::         
@end menu

@node interfaces Syntax
@subsection Syntax

@example
@code{interfaces} @code{@{}
  @kbd{interface_id}
    ( @kbd{ip_address}[@@@kbd{port_number}] |
      @code{@{} @code{address} @kbd{ip_address}@code{;} [ @code{port} @kbd{port_number}@code{;} ] @code{@}} )
  [ @kbd{interface_id ...}@code{;} @kbd{...}@code{;} ]
@code{@}}
@end example

@node interfaces Statement Definition and Usage
@subsection Statement Definition and Usage

@menu
* interface_id::                
@end menu

@node interface_id
@subsubsection @kbd{interface_id}
@vindex interface_id

The @kbd{interface_id} is a textual identifier of an IP interface,
which consists of an IP address and a port.

The definition of an interface can be written in long or a short form and
it always contains IP (IPv4 or IPv6) address.

@node interfaces Examples
@subsection interfaces Examples

Long form:

@example

interfaces @{
  my_ip @{
    address 192.0.2.1;
    port 53;
  @}
@}
	
@end example

Short form:

@example

interfaces @{
  my_second_ip @{ address 198.51.100.1@@53; @}
@}
	
@end example

Short form without port (defaults to 53):

@example

interfaces @{
  my_third_ip @{ address 203.0.113.1; @}
@}
	
@end example

@node remotes
@section @code{remotes} Statement
@stindex remotes

The @code{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 @code{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.

@menu
* remotes Syntax::              
* remotes Statement Definition and Grammar::  
* remotes Examples::
@end menu

@node remotes Syntax
@subsection Syntax

@example
@code{remotes} @code{@{}
  @kbd{remote_id}
    ( @kbd{ip_address}[@code{@@}@kbd{port_number}] |
      @code{@{}   @code{address} @kbd{ip_address};
         [ @code{port} @kbd{port_number}; ]
         [ @code{key} @kbd{key_id}; ]
         [ @code{via} [ @kbd{interface_id} | @kbd{ip_address} ]; ]
      @code{@}}
    )
  [ @kbd{remote_id} @dots{}; @dots{}; ]
@code{@}}
@end example

@node remotes Statement Definition and Grammar
@subsection Statement Definition and Grammar

@menu
* remote_id::
* address::
* port::
* key::
* via::
@end menu

@node remote_id
@subsubsection @kbd{remote_id}
@vindex remote_id

@kbd{remote_id} contains a symbolic name for a remote server.

@node address
@subsubsection address
@vindex address

@kbd{address} sets an IPv4 or an IPv6 address for this particular @code{remote}.

@node port
@subsubsection port
@vindex port

@code{port} section contains a port number for the current @code{remote}.  This section is optional with default port set to 53.

@node key
@subsubsection key
@vindex key

@code{key} section contains a key associated with this @code{remote}. This section is optional.


@node via
@subsubsection via
@vindex via

@code{via} section specifies which interface will be used to communicate with this @code{remote}. This section is optional.

@node remotes Examples
@subsection remotes Examples

@example

remotes @{

  # Format 1:
  server0 @{            
    address 127.0.0.1; 
    port 53531;       
    key key0.server0;
    via ipv4;             # reference to 'remotes'
    # via 82.35.64.59;    # direct IPv4
    # via [::cafe];       # direct IPv6
  @}

  # Format 2:
  server1 @{
    address 127.0.0.1@@53001;
  @}
@}

@end example

@node zones
@section @code{zones} Statement

The @code{zones} statement contains definition of zones served by Knot DNS.

@menu
* zones Syntax::                
* zones Statement Definition and Grammar::
* zones Example::
* zones List of zone semantic checks::     
@end menu

@node zones Syntax
@subsection Syntax

@example
@code{zones} @code{@{}
  [ @kbd{zone_options} ]
  @kbd{zone_id} @code{@{}
    @code{file} @code{"}@kbd{string}@code{";}
    [ @code{xfr-in} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
    [ @code{xfr-out} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
    [ @code{notify-in} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
    [ @code{notify-out} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
    [ @kbd{zone_options} ]
  @code{@}}
@code{@}}

@kbd{zone_options} :=
  [ @code{semantic-checks} @kbd{boolean}@code{;} ]
  [ @code{ixfr-from-differences} @kbd{boolean}@code{;} ]
  [ @code{disable-any} @kbd{boolean}@code{;} ]
  [ @code{notify-timeout} @kbd{integer}@code{;} ]
  [ @code{notify-retries} @kbd{integer}@code{;} ]
  [ @code{zonefile-sync} ( @kbd{integer} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
  [ @code{ixfr-fslimit} ( @kbd{integer} | @kbd{integer}(@code{k} | @code{M} | @code{G}) )@code{;} ]
  [ @code{ixfr-from-differences} @kbd{boolean}@code{;} ]
@end example

@node zones Statement Definition and Grammar
@subsection Statement Definition and Grammar

@menu
* zone_id::
* file::
* xfr-in::                    
* xfr-out::                     
* notify-in::                        
* notify-out::                     
* semantic-checks::                     
* ixfr-from-differences::
* disable-any::                     
* notify-timeout::                     
* notify-retries::                     
* zonefile-sync::                    
* ixfr-fslimit::                     
@end menu

@node zone_id
@subsubsection @kbd{zone_id}
@vindex zone_id

@code{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.

@node file
@subsubsection file
@vindex file

The @code{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 @code{storage} directory (@pxref{storage}).

@node xfr-in
@subsubsection xfr-in
@vindex xfr-in

In @code{xfr-in} statement user specifies which remotes will be permitted to perform a zone transfer to update the zone.
Remotes are defined in @code{remotes} section of configuration file (@pxref{remotes}).

@node xfr-out
@subsubsection xfr-out
@vindex xfr-out

In @code{xfr-out} statement user specifies which remotes will be permitted to obtain zone's contents via zone transfer.
Remotes are defined in @code{remotes} section of configuration file (@pxref{remotes}).

@node notify-in
@subsubsection notify-in
@vindex notify-in

@code{notify-in} defines which remotes will be permitted to send NOTIFY for this particular zone.

@node notify-out
@subsubsection notify-out
@vindex notify-out

@code{notify-out} defines to which remotes will your server send NOTIFYs about this particular zone.

@node semantic-checks
@subsubsection semantic-checks
@vindex semantic-checks 

@code{semantic-checks} statement turns on optional semantic checks for this particular zone.
See @ref{zones List of zone semantic checks} for more information. Possible values are @code{on} and @code{off}.
Most checks are disabled by default.

@node ixfr-from-differences
@subsubsection ixfr-from-differences
@vindex ixfr-from-differences

EXPERIMENTAL: option @code{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. Possible values are @code{on} and @code{off}. Disabled by default.

@node disable-any
@subsubsection disable-any
@vindex disable-any

If you enable @code{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 replay attack. Disabled by default.

@node notify-timeout
@subsubsection notify-timeout
@vindex notify-timeout

@code{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.

@node notify-retries
@subsubsection notify-retries
@vindex notify-retries

@code{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.

@node zonefile-sync
@subsubsection zonefile-sync
@vindex zonefile-sync

@code{zonefile-sync} is only relevant in a slave server scenario and only after receiving IXFR. It is a time in seconds after which current zone in memory will be synced to its file on a 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 @code{zonefile-sync} time has expired. Possible values are 1 to INT_MAX, optionally suffixed by unit size (s/m/h/d) - @emph{1s} is one second, @emph{1m} one minute, @emph{1h} one hour and @emph{1d} one day with default value set to @emph{1h}.

@node ixfr-fslimit
@subsubsection ixfr-fslimit
@vindex ixfr-fslimit

@code{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. @emph{1k}, @emph{1m} and @emph{1G} with default value not being set, meaning that journal file can grow without limitations.

@node zones Example
@subsection zones Example

@example
@group
zones @{

  # Shared options for all listed zones
  ixfr-from-differences off;
  semantic-checks off;
  disable-any off;
  notify-timeout 60;
  notify-retries 5;
  zonefile-sync 1h;
  ixfr-fslimit 1G;
  example.com @{
    file "samples/example.com.zone";
    ixfr-from-differences off; #experimental
    disable-any off;
    semantic-checks on;
    notify-timeout 60;
    notify-retries 5;
    zonefile-sync 1h;
    xfr-in server0;
    xfr-out server0, server1;
    notify-in server0;
    notify-out server0, server1;
  @}
@}

@end group
@end example

@node zones List of zone semantic checks 
@subsection List of zone semantic checks

The @code{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 @emph{stderr}.
These checks are the following:

@example
- 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)
@end example

Following checks have to be turned on using @code{semantic-checks} and
a zone containing following errors will be 
loaded even upon discovering an error:

@example
- 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)
@end example

@node log
@section @code{log} Statement
@stindex log

@menu
* log Syntax::                  
* log Statement Definition and Grammar::
* log Example::
@end menu

@node log Syntax
@subsection Syntax

@example
@code{log} @code{@{}
  [ @kbd{log_name} @code{@{}
    [ @kbd{category} @kbd{severity} [ @kbd{severity} @dots{} ]@code{;} ]
  @code{@}} ]
  [ @code{log_file} @kbd{filename} @{
    [ @kbd{category} @kbd{severity} [ @kbd{severity} @dots{} ]@code{;} ] 
  @} ]
@code{@}}

@end example

@node log Statement Definition and Grammar
@subsection Statement Definition and Grammar

@menu
* log_name::
* category::
* severity::
* log_file::
@end menu

The @code{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.

In case of missing log section, severities from @kbd{warning} and more serious
will be logged to both @kbd{stderr} and @kbd{syslog}. The @kbd{info} and @kbd{notice}
severities will be logged to the @kbd{stdout}.

@node log_name
@subsubsection @kbd{log_name}
@vindex @kbd{log_name}

@kbd{log_name} should be replaced with one of 3 symbolic log names :
@itemize
@item @emph{stdout} - logging to standard output
@item @emph{stderr} - logging to standard error output
@item @emph{syslog} - logging to syslog
@end itemize

@node category
@subsubsection @kbd{category}
@vindex category

Knot DNS allows user to choose from these logging categories:

@itemize
@item @emph{server} - Messages related to general operation of the server.
@item @emph{zone} - Messages related to zones, zone parsing and loading.
@item @emph{answering} - Messages regarding query processing and response creation.
@item @emph{any} - All categories.
@end itemize

@node severity
@subsubsection @kbd{severity}
@vindex severity

Knot DNS has the following logging severities:
@itemize
@item @emph{debug} - Debug messages, must be turned on at compile time (@pxref{Enabling debug messages in server}).
@item @emph{info} - Informational message.
@item @emph{notice} - Server notices and hints.
@item @emph{warning} - Warnings that might require user action.
@item @emph{error} - Recoverable error. Action should be taken.
@item @emph{all} - All severities.
@end itemize

More severities may be listed for each category, but all severities have to be listed explicitly, i.e. using @emph{warning} severity does not mean that @emph{error} severity messages will be logged as well.

@node log_file
@subsubsection @kbd{log_file}
@vindex @kbd{log_file}

@kbd{log_file} is either absolute or relative path to file user wants to log to.
See following example for clarification.

@node log Example
@subsection log Example

@example

log @{

  syslog @{
    any error;
    zone warning, notice;
    server info;
  @}

  stderr @{
    any error, warning;
  @}

  file "/tmp/knot-sample/knotd.debug" @{
    server debug;
  @}
@}

@end example