summaryrefslogtreecommitdiff
path: root/doc/reference.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/reference.texi')
-rw-r--r--doc/reference.texi322
1 files changed, 243 insertions, 79 deletions
diff --git a/doc/reference.texi b/doc/reference.texi
index bb2bf39..57324b7 100644
--- a/doc/reference.texi
+++ b/doc/reference.texi
@@ -4,13 +4,15 @@
This reference describes every configuration option in Knot DNS server.
@menu
-* system::
-* keys::
-* interfaces::
-* remotes::
+* system::
+* keys::
+* interfaces::
+* remotes::
+* groups::
* control::
-* zones::
-* log::
+* zones::
+* log::
+* include::
@end menu
@node system
@@ -22,9 +24,9 @@ operating system and other general options which do not fit anywhere
else.
@menu
-* system Syntax::
-* system Statement Definition and Usage::
-* system Example::
+* system Syntax::
+* system Statement Definition and Usage::
+* system Example::
@end menu
@node system Syntax
@@ -34,16 +36,18 @@ else.
@code{system} @code{@{}
[ @code{identity} @code{"}@kbd{string}@code{";} ]
[ @code{version} @code{"}@kbd{string}@code{";} ]
+ [ @code{hostname} @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{rundir} @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-hs} ( @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} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
+ [ @code{rate-limit-size} @kbd{integer}@code{;} ]
[ @code{rate-limit-slip} @kbd{integer}@code{;} ]
@code{@}}
@end example
@@ -52,16 +56,18 @@ else.
@subsection Statement Definition and Usage
@menu
-* identity::
-* version::
-* nsid::
-* storage::
-* pidfile::
-* workers::
-* user::
-* max-conn-idle::
-* max-conn-hs::
-* max-conn-reply::
+* identity::
+* version::
+* hostname::
+* nsid::
+* storage::
+* rundir::
+* workers::
+* user::
+* max-conn-idle::
+* max-conn-hs::
+* max-conn-reply::
+* transfers::
* rate-limit::
* rate-limit-size::
* rate-limit-slip::
@@ -71,7 +77,11 @@ else.
@subsubsection identity
@vindex identity
-Identity of the server (see @url{http://tools.ietf.org/html/rfc4892,RFC 4892}). Not used yet.
+Identity of the server returned in a response for the query for TXT record
+@code{id.server.} 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.
@example
system @{
@@ -83,11 +93,31 @@ system @{
@subsubsection version
@vindex version
-Version of the server (see @url{http://tools.ietf.org/html/rfc4892,RFC 4892}). Not used yet.
+Version of the server software returned in a response for the query for TXT
+record @code{version.server.} 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.
@example
system @{
- version "1.1.0";
+ version "1.3.0";
+@}
+@end example
+
+@node hostname
+@subsubsection hostname
+@vindex hostname
+
+Host name of the server returned in a response for the query for TXT record
+@code{hostname.server.} 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.
+
+@example
+system @{
+ hostname "a.ns.example.com";
@}
@end example
@@ -109,7 +139,9 @@ system @{
@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.
+The working directory of Knot DNS, it is used to store compiled zone files and
+other persistent data.
+Default: @file{$@{sharedstatedir@}/knot}, configured with @code{--with-storage=path}
@example
system @{
@@ -117,17 +149,16 @@ system @{
@}
@end example
-@node pidfile
-@subsubsection pidfile
-@vindex pidfile
-
-Specifies a custom PID file location.
+@node rundir
+@subsubsection rundir
+@vindex rundir
-Default value: @file{knot.pid} in @code{storage} directory.
+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 @{
- pidfile "/var/run/knot.pid";
+ rundir "/var/run/knot";
@}
@end example
@@ -184,6 +215,14 @@ that already made at least 1 meaningful query.
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
@@ -227,7 +266,7 @@ system @{
version "@value{VERSION}";
nsid "amaterasu";
storage "/var/lib/knot";
- pidfile "/var/run/knot.pid";
+ rundir "/var/run/knot";
workers 16;
user knot.knot;
@}
@@ -241,9 +280,9 @@ The @code{keys} statement sets up the TSIG keys used to authenticate
zone transfers.
@menu
-* keys Syntax::
-* keys Statement Definition and Usage::
-* Example::
+* keys Syntax::
+* keys Statement Definition and Usage::
+* Example::
@end menu
@node keys Syntax
@@ -260,7 +299,7 @@ keys @{
@subsection Statement Definition and Usage
@menu
-* key_id::
+* key_id::
@end menu
@node key_id
@@ -293,10 +332,10 @@ You need to use bind or ldns utils to generate TSIG keys. Unfortunately, Knot DN
$ dnssec-keygen -a HMAC-SHA256 -b 256 -n HOST foobar.example.com
Kfoobar.example.com.+163+21239
-$ cat Kfoobar.example.com.+163+21239.key
+$ 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:
@@ -307,7 +346,7 @@ keys @{
foobar.example.com. hmac-sha256
"rqv2WRyDgIUaHcJi03Zssor9jtG1kOpb3dPywxZfTeo=";
@}
-
+
@end example
@node Example
@@ -320,7 +359,7 @@ keys @{
key0.server0 hmac-md5 "Wg==";
foobar.example.com. hmac-sha256 "RQ==";
@}
-
+
@end example
@node interfaces
@@ -330,9 +369,9 @@ keys @{
The @code{interfaces} statement contains IP interfaces where Knot DNS listens for incoming queries.
@menu
-* interfaces Syntax::
-* interfaces Statement Definition and Usage::
-* interfaces Examples::
+* interfaces Syntax::
+* interfaces Statement Definition and Usage::
+* interfaces Examples::
@end menu
@node interfaces Syntax
@@ -351,7 +390,7 @@ The @code{interfaces} statement contains IP interfaces where Knot DNS listens fo
@subsection Statement Definition and Usage
@menu
-* interface_id::
+* interface_id::
@end menu
@node interface_id
@@ -377,7 +416,7 @@ interfaces @{
port 53;
@}
@}
-
+
@end example
Short form:
@@ -387,7 +426,7 @@ Short form:
interfaces @{
my_second_ip @{ address 198.51.100.1@@53; @}
@}
-
+
@end example
Short form without port (defaults to 53):
@@ -397,7 +436,7 @@ Short form without port (defaults to 53):
interfaces @{
my_third_ip @{ address 203.0.113.1; @}
@}
-
+
@end example
@node remotes
@@ -412,8 +451,8 @@ 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 Syntax::
+* remotes Statement Definition and Grammar::
* remotes Examples::
@end menu
@@ -484,9 +523,9 @@ server for a different zone.
remotes @{
# Format 1:
- server0 @{
- address 127.0.0.1;
- port 53531;
+ server0 @{
+ address 127.0.0.1;
+ port 53531;
key key0.server0;
via ipv4; # reference to 'remotes'
# via 82.35.64.59; # direct IPv4
@@ -501,18 +540,94 @@ remotes @{
@end example
-@node control
+@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 enable remote control only on private networks
-or loopback.
+for that reason, it is recommended to use default UNIX sockets.
@menu
-* control Syntax::
-* control Statement Definition and Grammar::
+* control Syntax::
+* control Statement Definition and Grammar::
* control Examples::
@end menu
@@ -532,12 +647,24 @@ or loopback.
@node control Statement Definition and Grammar
@subsection Statement Definition and Grammar
-Control interface @code{listen-on} definition is equal to @code{interface} definition in @ref{interfaces}.
-Default port for control interface is @code{5553}.
+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==";
@@ -558,10 +685,10 @@ control @{
The @code{zones} statement contains definition of zones served by Knot DNS.
@menu
-* zones Syntax::
+* zones Syntax::
* zones Statement Definition and Grammar::
* zones Example::
-* zones List of zone semantic checks::
+* zones List of zone semantic checks::
@end menu
@node zones Syntax
@@ -598,18 +725,18 @@ The @code{zones} statement contains definition of zones served by Knot DNS.
@menu
* zone_id::
* file::
-* xfr-in::
-* xfr-out::
-* notify-in::
-* notify-out::
+* xfr-in::
+* xfr-out::
+* notify-in::
+* notify-out::
* update-in::
-* semantic-checks::
+* semantic-checks::
* ixfr-from-differences::
-* disable-any::
-* notify-timeout::
-* notify-retries::
-* zonefile-sync::
-* ixfr-fslimit::
+* disable-any::
+* notify-timeout::
+* notify-retries::
+* zonefile-sync::
+* ixfr-fslimit::
@end menu
@node zone_id
@@ -663,7 +790,7 @@ Remotes are defined in @code{remotes} section of configuration file (@pxref{remo
@node semantic-checks
@subsubsection semantic-checks
-@vindex 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.
@@ -677,7 +804,7 @@ Most checks are disabled by default.
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.
+See @ref{Controlling running daemon} for more information.
Possible values are @code{on} and @code{off}. Disabled by default.
@@ -699,7 +826,7 @@ By default, this value is set to 60 seconds.
@subsubsection notify-retries
@vindex notify-retries
-@code{notify-retries} tells the server how many times it can retry to send a NOTIFY. Possible values
+@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
@@ -747,7 +874,7 @@ zones @{
@end group
@end example
-@node zones List of zone semantic checks
+@node zones List of zone semantic checks
@subsection List of zone semantic checks
The @code{semantic-checks} statement turns on extra zone file semantic
@@ -767,7 +894,7 @@ These checks are the following:
@end example
Following checks have to be turned on using @code{semantic-checks} and
-a zone containing following errors will be
+a zone containing following errors will be
loaded even upon discovering an error:
@example
@@ -793,7 +920,7 @@ loaded even upon discovering an error:
@stindex log
@menu
-* log Syntax::
+* log Syntax::
* log Statement Definition and Grammar::
* log Example::
@end menu
@@ -807,7 +934,7 @@ loaded even upon discovering an error:
[ @kbd{category} @kbd{severity} [ @kbd{severity} @dots{} ]@code{;} ]
@code{@}} ]
[ @code{log_file} @kbd{filename} @{
- [ @kbd{category} @kbd{severity} [ @kbd{severity} @dots{} ]@code{;} ]
+ [ @kbd{category} @kbd{severity} [ @kbd{severity} @dots{} ]@code{;} ]
@} ]
@code{@}}
@@ -904,3 +1031,40 @@ log @{
@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 makes inclusion of another
+file possible.
+
+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{;}
+@end example
+
+@node include Examples
+@subsection Examples
+
+@example
+include "keys.conf";
+
+remotes @{
+ ctl @{
+ address 127.0.0.1;
+ key knotc-key;
+ @}
+ include "remotes.conf";
+@}
+@end example
generated by cgit v1.2.3 (git 2.39.1) at 2025-07-29 18:17:26 +0000