samples: replace knot.full.conf with man/knot.conf.5.in

.gitignore

@@ -83,10 +83,6 @@
 /*.info
 /*coverage/
 
-# alternative allocators
-/src/allocator.h
-/src/allocators/
-
 # sphinx documentation
 /doc/_build/
 /doc/conf.py

doc/configuration.rst

@@ -11,25 +11,25 @@ Minimal configuration
 The following configuration presents a minimal configuration file
 which can be used as a base for your Knot DNS setup::
 
-    # This is a sample of a minimal configuration file for Knot DNS.
-    #
-    # For exhaustive list of all options see samples/knot.full.conf
-    # in the source directory.
-    #
-
     interfaces {
-        my_interface { address 127.0.0.1@53; }
-        second_int { address ::1; }
+        all_ipv4 {
+            address 0.0.0.0;
+            port 53;
+        }
+        all_ipv6 {
+            address [::];
+            port 53;
+        }
     }
 
-    log {
-      syslog { any info; }
+    zones {
+        example.com {
+            file "/etc/knot/example.com";
+        }
     }
 
-    zones {
-      example.com {
-        file "/etc/knot/example.com";
-      }
+    log {
+        syslog { any info; }
     }
 
 Now let's go step by step through this minimal configuration file:

man/knot.conf.5.in

 .TH "knot.conf" "5" "@RELEASE_DATE@" "CZ.NIC Labs" "Knot DNS, version @VERSION@"
-.SH "NAME"
-.LP
+.SH NAME
 .B knot.conf
 \- Configuration file manual for Knot DNS server.
-.SH "SYNOPSIS"
-.LP
+.SH SYNOPSIS
 .B knot.conf
-.SH "DESCRIPTION"
+.SH DESCRIPTION
 .B knot.conf
-serves as an example of the configuration for knotc(8) and knotd(8).
-.SH "EXAMPLE"
-.LP
+is an overview of all config options for \fBknotc\fR and \fBknotd\fR.
+.SH EXAMPLE
+.nf
+#
+# There are 8 main sections of this config file:
+#   system, interfaces, keys, remotes, groups, zones, control and log
+#
 
- #
- # There are 7 main sections of this config file:
- #   system, interfaces, remotes, groups, zones, control and log
- #
+# This is a comment.
 
- # Section 'system' contains general options for the server
- system {
+# 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'
@@ -58,7 +57,7 @@ serves as an example of the configuration for knotc(8) and knotd(8).
   # 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: off (wait for zones to be loaded before answering)
+  # Default: disabled (wait for zones to be loaded before answering)
   asynchronous-start off;
 
   # User for running server
@@ -113,36 +112,36 @@ serves as an example of the configuration for knotc(8) and knotd(8).
   # 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 {
+}
+
+# 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
   #
@@ -167,11 +166,11 @@ serves as an example of the configuration for knotc(8) and knotd(8).
   #   address [::1]@53534;
   # }
 
- }
+}
 
- # Section 'remotes' contains symbolic names for remote servers.
- # Syntax for 'remotes' is the same as for 'interfaces'.
- remotes {
+# Section 'remotes' contains symbolic names for remote servers.
+# Syntax for 'remotes' is the same as for 'interfaces'.
+remotes {
 
   # Remote entry
   #
@@ -197,14 +196,14 @@ serves as an example of the configuration for knotc(8) and knotd(8).
   admin-bob {
     address 192.168.100.2;
   }
- }
+}
 
- groups {
+groups {
   admins { admin-alice, admin-bob }
- }
+}
 
- # Section 'control' specifies on which interface to listen for RC commands
- control {
+# Section 'control' specifies on which interface to listen for RC commands
+control {
 
   # Default: $(run_dir)/knot.sock
   listen-on "knot.sock";
@@ -218,10 +217,10 @@ serves as an example of the configuration for knotc(8) and knotd(8).
   # 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 {
+# Section 'zones' contains information about zones to be served.
+zones {
 
   # Shared options for all listed zones
   #
@@ -230,7 +229,7 @@ serves as an example of the configuration for knotc(8) and knotd(8).
   # default: ${localstatedir}/lib/knot, configured with --with-storage
   storage "/var/lib/knot";
 
-  # Build differences from zone file changes
+  # Build differences from zone file changes. EXPERIMENTAL feature.
   # Possible values: on|off
   # Default value: off
   ixfr-from-differences off;
@@ -257,10 +256,12 @@ serves as an example of the configuration for knotc(8) and knotd(8).
 
   # Timeout for syncing changes from zone database to zonefile
   # Possible values: <1..INT_MAX> (seconds)
-  # Default value: 0s (immediately)
+  # 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
-  zonefile-sync 0s;
+  # 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>
@@ -269,14 +270,14 @@ serves as an example of the configuration for knotc(8) and knotd(8).
   # f.e. 1k, 100M, 2G
   ixfr-fslimit 1G;
 
-  # Enable DNSSEC online signing (technical preview)
+  # Enable DNSSEC online signing (EXPERIMENTAL)
   # Possible values: on | off;
   # Default value: off
-  dnssec-enable off;
+  # dnssec-enable off;
 
-  # Location of DNSSEC signing keys (relative to storage directory).
+  # Location of DNSSEC signing keys (relative to storage dir).
   # Default value: not set
-  dnssec-keydir "keys";
+  # dnssec-keydir "keys";
 
   # Validity period for DNSSEC signatures
   # Possible values: <10801..INT_MAX> (seconds)
@@ -285,12 +286,12 @@ serves as an example of the configuration for knotc(8) and knotd(8).
   # 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;
-  
+  # signature-lifetime 30d;
+
   # Serial policy after DDNS and automatic DNSSEC signing.
   # Possible values: increment | unixtime
   # Default value: increment
-  serial-policy increment;
+  # serial-policy increment;
 
   # Zone entry
   #
@@ -348,7 +349,7 @@ serves as an example of the configuration for knotc(8) and knotd(8).
     # Default value: inherited from zones section
     dnssec-keydir "keys";
 
-    # Enable DNSSEC online signing (technical preview)
+    # Enable DNSSEC online signing (EXPERIMENTAL)
     # Possible values: on | off;
     # Default value: inherited from zones section
     dnssec-enable off;
@@ -359,14 +360,14 @@ serves as an example of the configuration for knotc(8) and knotd(8).
     # 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
+    # signatures expires in 7200 seconds or less and it was chosen as a 
     # reasonable value with regard to signing overhead.
-    signature-lifetime 30d;
+    # signature-lifetime 30d;
 
     # Serial policy after DDNS and automatic DNSSEC signing.
     # Possible values: increment | unixtime
     # Default value: increment
-    serial-policy increment;
+    # serial-policy increment;
 
     # XFR master server
     xfr-in server0;
@@ -383,87 +384,78 @@ serves as an example of the configuration for knotc(8) and knotd(8).
     # List of servers to allow UPDATE queries
     update-in server0, admins;
 
-	# Query modules are dynamically loaded modules that can alter query plan
-	# Configuration is always module-specific, but passed as a simple string
-	query_module {
-		module_one "configuration string";
-		module_two "specific configuration string";
-	}
+    # 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. 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
-  #
+}
+
+# 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> [, <severity2> ...];
-  #   <category2> <severity1> [, <severity2> ...];
+  #   <category1> <severity1>;
+  #   <category2> <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
+
+  syslog {
+    # Log any error or critical to syslog
+    any error;
+    # Log all (excluding debug) from server to syslog
     server info;
   }
 
-  # Log fatal, warnings and errors to stderr
+  # Log any warning, error or critical to stderr
   stderr {
-    any error, warning;
+    any warning;
   }
 
   # Format 2:
-  # file <path> {
-  #   <category1> <severity1> [, <severity2> ...];
-  #   <category2> <severity1> [, <severity2> ...];
+  # file <path> { # <path> is absolute or relative path to log file
+  #   <category1> <severity1>;
+  #   <category2> <severity2>;
   # }
-  file "/tmp/knot-sample/knotd.debug" {  # <path> is absolute or relative path to log file
+
+  file "/tmp/knot-sample/knotd.debug" {
     server debug;
   }
- }
-
+}
+.fi
 .SH "SEE ALSO"
-.LP
-knotd(8), knotc(8)
+.BR knotd (8),
+.BR knotc (8).

man/knotc.8.in

@@ -83,7 +83,8 @@ Make sure the key can be read/written only by the owner for security reasons.
 .TP
 # knotc \-s 127.0.0.1 \-k knotc.key reload
 .SH "SEE ALSO"
-.BR knotd (8)
+.BR knotd (8),
+.BR knot.conf (5).
 .SH NOTE
 The full documentation for \fBKnot DNS\fR is maintained
 as a Texinfo manual. If the \fBinfo\fR program is properly

man/knotd.8.in

@@ -20,7 +20,8 @@ Print version of the server.
 \fB\-h\fR, \fB\-\-help\fR
 Print help and usage.
 .SH "SEE ALSO"
-.BR knotc (8)
+.BR knotc (8),
+.BR knot.conf (5).
 .SH NOTE
 The full documentation for \fBKnot DNS\fR is maintained
 as a Texinfo manual. If the \fBinfo\fR program is properly

samples/Makefile.am

@@ -15,7 +15,7 @@ knot.sample.conf: knot.sample.conf.in
 	  $(edit) $${srcdir}$@.in >$@.tmp
 	mv $@.tmp $@
 
-EXTRA_DIST = knot.sample.conf.in knot.full.conf knot.keys.conf example.com.zone
+EXTRA_DIST = knot.sample.conf.in example.com.zone
 
 install-data-local: knot.sample.conf
 	[ -d $(DESTDIR)/$(config_dir) ] || \

samples/knot.full.conf

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