#
# knot.sample.conf
#
# This is a sample configuration file for Knot DNS server.
#

# This is a comment.

#
# There are 7 main sections of this config file:
#   system, interfaces, remotes, groups, zones, control and log
#

# 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;

  # 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: 60s
  max-conn-idle 60s;

  # 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: 10s
  max-conn-handshake 10s;

  # 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 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;

  # 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;
  }
}

# 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. Must be turned on at compile time.
#   info      - Informational messages.
#   notice    - Notices and hints.
#   warning   - Warnings. An action from the operator may be required.
#   error     - Recoverable error. Some action should be taken.
#   fatal     - Non-recoverable errors resulting in server shutdown.
#               (Not supported yet.)
#   all       - All severities.
#
# 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.
#   answering - Messages regarding query processing and response creation.
#   any       - All categories
#
# More severities (separated by commas) may be listed for each category.
# All applicable severities must be listed.
#   (I.e. specifying 'error' severity does mean: 'log error messages',
#    and NOT 'log all messages of severity error and above'.)
#
# 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 {

  # Log entry
  #
  # Format 1:
  # <log> {
  #   <category1> <severity1> [, <severity2> ...];
  #   <category2> <severity1> [, <severity2> ...];
  #   ...
  # }
  syslog {     # <log> is a symbolic name of a log device (see above)
    # log errors of any category
    any error;    # for <category> and <severity> see above
    # log also warnings and notices from category 'zone'
    zone warning, notice;
    # log info from server
    server info;
  }

  # Log fatal, warnings and errors to stderr
  stderr {
    any error, warning;
  }

  # Format 2:
  # file <path> {
  #   <category1> <severity1> [, <severity2> ...];
  #   <category2> <severity1> [, <severity2> ...];
  # }
  file "/tmp/knot-sample/knotd.debug" {  # <path> is absolute or relative path to log file
    server debug;
  }
}