path: root/doc/reference.texi

@node Knot DNS Configuration Reference, Migration from other DNS servers, Statement Index, Top
@appendix Knot DNS Configuration Reference

This reference describes every configuration option in Knot DNS server.

@menu
* system::
* keys::
* interfaces::
* remotes::
* groups::
* control::
* zones::
* log::
* include::
@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{on} | @code{"}@kbd{string}@code{"} )@code{;} ]
  [ @code{version} ( @code{on} | @code{"}@kbd{string}@code{"} )@code{;} ]
  [ @code{nsid} ( @code{on} | @code{"}@kbd{string}@code{"} | @kbd{hex_string} )@code{;} ]
  [ @code{rundir} @code{"}@kbd{string}@code{";} ]
  [ @code{pidfile} @code{"}@kbd{string}@code{";} ]
  [ @code{workers} @kbd{integer}@code{;} ]
  [ @code{user} @kbd{string}[@code{.}@kbd{string}]@code{;} ]
  [ @code{max-conn-idle} ( @kbd{integer} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
  [ @code{max-conn-handshake} ( @kbd{integer} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
  [ @code{max-conn-reply} ( @kbd{integer} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
  [ @code{transfers} @kbd{integer}@code{;} ]
  [ @code{rate-limit} @kbd{integer}@code{;} ]
  [ @code{rate-limit-size} @kbd{integer}@code{;} ]
  [ @code{rate-limit-slip} @kbd{integer}@code{;} ]
  [ @code{max-udp-payload} @kbd{integer}@code{;} ]
@code{@}}
@end example

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

@menu
* identity::
* version::
* nsid::
* rundir::
* pidfile::
* workers::
* user::
* max-conn-idle::
* max-conn-handshake::
* max-conn-reply::
* transfers::
* rate-limit::
* rate-limit-size::
* rate-limit-slip::
* max-udp-payload::
@end menu

@node identity
@subsubsection identity
@vindex identity

Identity of the server returned in a response for the query for TXT record
@code{id.server.} or @code{hostname.bind.} in the CHAOS class
(see @url{http://tools.ietf.org/html/rfc4892,RFC 4892}).

If not specified or empty, the server returns REFUSED status code.
If a boolean value of @code{on} is used, FQDN hostname is used as a default.

@example
system @{
  identity "ns01.example.com";
  identity on;
@}
@end example

@node version
@subsubsection version
@vindex version

Version of the server software returned in a response for the query for TXT
record @code{version.server.} or @code{version.bind.} in the CHAOS class
(see @url{http://tools.ietf.org/html/rfc4892,RFC 4892}).

Option allows a boolean value @code{on|off}, if @code{on}, automatic version
string is set as a default. If not specified or empty, the server returns REFUSED status code.

@example
system @{
  version "Knot DNS 1.3.0";
  version on; # Reports current version
@}
@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)
If a boolean value of @code{on} is used, FQDN hostname is used as a default.

@example
system @{
  nsid 0x00cafe;
  nsid "cafe";
  nsid on;
@}
@end example

@node rundir
@subsubsection rundir
@vindex rundir

Path for storing run-time data, for example PID file and unix sockets.
Default: @file{$@{localstatedir@}/run/knot}, configured with @code{--with-rundir=path}

@example
system @{
  rundir "/var/run/knot";
@}
@end example

@node pidfile
@subsubsection pidfile
@vindex pidfile

Specifies a custom PID file location.

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

@example
system @{
  pidfile "/var/run/knot/knot_dmz.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 max-conn-idle
@subsubsection max-conn-idle
@vindex 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.

@node max-conn-handshake
@subsubsection max-conn-handshake
@vindex 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.

@node max-conn-reply
@subsubsection max-conn-reply
@vindex max-conn-reply

Maximum time to wait for a reply to an issued SOA query.

@node transfers
@subsubsection transfers
@vindex transfers

Maximum parallel transfers, including pending SOA queries.
Lowest possible number is the number of CPUs.
Default is 10.

@node rate-limit
@subsubsection rate-limit
@vindex 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 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.

Default value: @kbd{0 (disabled)}

@node rate-limit-size
@subsubsection rate-limit-size
@vindex 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
@kbd{1.2 * maximum_qps}.

Default value: @kbd{393241}

@node rate-limit-slip
@subsubsection rate-limit-slip
@vindex 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 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).

Default value: @kbd{1}

@node max-udp-payload
@subsubsection max-udp-payload
@vindex max-udp-payload

Maximum EDNS0 UDP payload size.

Default value: @kbd{4096}

@node system Example
@subsection system Example

@example
system @{
  identity "Knot DNS @value{VERSION}";
  version "@value{VERSION}";
  nsid    "amaterasu";
  rundir "/var/run/knot";
  workers 16;
  user knot.knot;
  max-udp-payload 4096;
@}
@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 groups
@section @code{groups} Statement
@stindex groups

The @code{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 @code{allow} in @ref{control} section and ACLs in
@ref{zones} section).

The remotes definitions must exist prior to using them in group definitions.
One remote can be a member of multiple groups.

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

@node groups Syntax
@subsection Syntax

@example
@code{groups} @code{@{}
  @kbd{group_id} @code{@{} @kbd{remote_id} [ @code{,} @kbd{...} ] @code{@}}
  [ @kbd{...} ]
@code{@}}
@end example

@node groups Statement Definition and Grammar
@subsection Statement Definition and Grammar

@menu
* group_id::
* remote_id:groups_remote_id.
@end menu

@node group_id
@subsubsection @kbd{group_id}
@vindex group_id

@kbd{group_id} contains a symbolic name for a group of remotes.

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

@kbd{remote_id} contains a symbolic name for a remote server as specified in
@ref{remotes} section.

@node groups Examples
@subsection Examples

@example
remotes @{
  ctl @{
    # ...
  @}
  alice @{
    # ...
  @}
  bob @{
    # ...
  @}
@}

groups @{
  admins @{ alice, bob @}
@}

# example usage:
control @{
  # ...
  allow ctl, admins;
@}
@end example

@node control
@section @code{control} Statement

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

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

@node control Syntax
@subsection Syntax

@example
@code{control} @code{@{}
  [ @kbd{listen-on} @code{@{}
    ( @code{address} @kbd{ip_address}[@@@kbd{port_number}] |
      @code{@{} @code{address} @kbd{ip_address}@code{;} [ @code{port} @kbd{port_number}@code{;} ] @code{@}} )
  @code{@}} ]
  [ @code{allow} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
@code{@}}
@end example

@node control Statement Definition and Grammar
@subsection Statement Definition and Grammar

Control interface @code{listen-on} either defines a UNIX socket or an
IPv4/IPv6 @code{interface} definition as in @ref{interfaces}.
Default port for IPv4/v6 control interface is @code{5533},
however UNIX socket is preferred.
UNIX socket address is relative to @code{rundir} if not specified as an absolute
path. Without any configuration, the socket will be created in @code{rundir/knot.sock}.

@node control Examples
@subsection Examples

UNIX socket example:
@example
control @{
        listen-on "/var/run/knot/knot.sock";
@}
@end example

IPv4 socket example:
@example
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;
@}
@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{;} ]
    [ @code{update-in} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
    [ @kbd{zone_options} ]
  @code{@}}
@code{@}}

@kbd{zone_options} :=
  [ @code{storage} @code{"}@kbd{string}@code{";} ]
  [ @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{;} ]
  [ @code{dnssec-keydir} @code{"}@kbd{string}@code{"}@code{;} ]
  [ @code{dnssec-enable} ( @code{on} | @code{off} )@code{;} ]
  [ @code{signature-lifetime} ( @kbd{integer} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
  [ @code{serial-policy} ( increment | unixtime ); ]
@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::
* update-in::
* storage::
* semantic-checks::
* ixfr-from-differences::
* disable-any::
* notify-timeout::
* notify-retries::
* zonefile-sync::
* ixfr-fslimit::
* dnssec-keydir::
* dnssec-enable::
* signature-lifetime::
* serial-policy::
@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 update-in
@subsubsection update-in
@vindex update-in

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

@node storage
@subsubsection storage
@vindex storage

Data directory for zones. It is used to store zone files and journal files.

Value of @code{storage} set in @code{zone} section is relative to @code{storage} in @code{zones} section.

Default value (in @code{zones} section): @file{$@{localstatedir@}/lib/knot}, configured with @code{--with-storage=path}

Default value (in @code{zone} config): inherited from @code{zones} section

@example
zones @{
  storage "/var/lib/knot";
  example.com @{
    storage "com";
    file "example.com"; # /var/lib/knot/com/example.com
  @}
@}
@end example

@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

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} 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 @code{zonefile-sync} time has expired (or synced manually via @code{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) - @emph{1s} is one second, @emph{1m} one minute, @emph{1h} one hour and @emph{1d} one day with default value set to @emph{0s}.

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

@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 dnssec-keydir
@subsubsection dnssec-keydir
@vindex dnssec-keydir

Location of DNSSEC signing keys, relative to @code{storage}.

Default value: not set

@node dnssec-enable
@subsubsection dnssec-enable
@vindex dnssec-enable

PREVIEW: Enable automatic DNSSEC signing for the zone.

Default value (in @code{zones} section): off

Default value (in @code{zone} config): inherited from @code{zones} section

@node signature-lifetime
@subsubsection signature-lifetime
@vindex signature-lifetime

Specifies how long should the automatically generated DNSSEC signatures be valid.
Expiration will thus be set as current time (in the moment of signing)
+ @code{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
@code{knotc zonestatus} command.

Default value: @kbd{30d} (@kbd{2592000})

@node serial-policy
@subsubsection serial-policy
@vindex serial-policy

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.

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.

@strong{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 (consult:
 http://www.zytrax.com/books/dns/ch9/serial.html).

Default value: increment

@node zones Example
@subsection zones Example

@example
@group
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;
  @}
@}

@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

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

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

The path of the included file can be either absolute or relative to a
configuration file currently being processed.

@menu
* include Syntax::
* include Examples::
@end menu

@node include Syntax
@subsection Syntax

@example
@code{include} "filename"@code{;}
@code{include} "dirname"@code{;}
@end example

@node include Examples
@subsection Examples

@example
include "keys.conf";

remotes @{
  ctl @{
    address 127.0.0.1;
    key knotc-key;
  @}
  include "remotes.conf";
@}

include "zones";
@end example