Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
KNOT.CONF(5)			   Knot	DNS			  KNOT.CONF(5)

NAME
       knot.conf - Knot	DNS configuration file

DESCRIPTION
       Configuration files for Knot DNS	use simplified YAML format. Simplified
       means that not all of the features are supported.

       For the description of configuration items, we have to declare a	 mean-
       ing of the following symbols:

       o INT a Integer

       o STR a Textual string

       o HEXSTR	a Hexadecimal string (with 0x prefix)

       o BOOL a	Boolean	value (on/off or true/false)

       o TIME  a  Number  of seconds, an integer with possible time multiplier
	 suffix	(s ~ 1,	m ~ 60,	h ~ 3600 or d ~	24 * 3600)

       o SIZE a	Number of bytes, an integer with possible size multiplier suf-
	 fix (B	~ 1, K ~ 1024, M ~ 1024^2 or G ~ 1024^3)

       o BASE64	a Base64 encoded string

       o ADDR a	IPv4 or	IPv6 address

       o DNAME a Domain	name

       o ... a Multi-valued item, order	of the values is preserved

       o [ ] a Optional	value

       o | a Choice

       The  configuration consists of several fixed sections and optional mod-
       ule sections. There are 14 fixed	 sections  (module,  server,  control,
       log, statistics,	database, keystore, key, remote, acl, submission, pol-
       icy, template, zone).  Module sections are prefixed with	the mod-  pre-
       fix (e.g. mod-stats).

       Most of the sections (e.g. zone)	are sequences of settings blocks. Each
       settings	block begins with a unique identifier, which can be used as  a
       reference  from	other  sections	(such an identifier must be defined in
       advance).

       A multi-valued item can be specified either as a	YAML sequence:

	  address: [10.0.0.1, 10.0.0.2]

       or as more single-valued	items each on an extra line:

	  address: 10.0.0.1
	  address: 10.0.0.2

       If an item value	contains spaces	or other  special  characters,	it  is
       necessary to enclose such a value within	double quotes "	".

COMMENTS
       A  comment  begins with a # character and is ignored during processing.
       Also each configuration section or sequence block  allows  a  permanent
       comment using the comment item which is stored in the server beside the
       configuration.

INCLUDES
       Another configuration file or files, matching a	pattern,  can  be  in-
       cluded  at  the top level in the	current	file. If the path is not abso-
       lute, then it is	considered to be relative to  the  current  file.  The
       pattern	can  be	 an  arbitrary string meeting POSIX glob requirements,
       e.g. dir/*.conf.	 Matching files	are processed in sorted	order.

	  include: STR

MODULE SECTION
       Dynamic modules loading configuration.

       NOTE:
	  If configured	with non-empty `--with-moduledir=path` parameter,  all
	  shared modules in this directory will	be automatically loaded.

	  module:
	    - id: STR
	      file: STR

   id
       A module	identifier in the form of the mod- prefix and module name suf-
       fix.

   file
       A path to a shared library file with the	module implementation.

       WARNING:
	  If the path is not absolute, the library is searched in the  set  of
	  system directories. See man dlopen for more details.

       Default:	     ${libdir}/knot/modules-${version}/module_name.so	   (or
       ${path}/module_name.so if configured with --with-moduledir=path)

SERVER SECTION
       General options related to the server.

	  server:
	      identity:	[STR]
	      version: [STR]
	      nsid: [STR|HEXSTR]
	      rundir: STR
	      user: STR[:STR]
	      pidfile: STR
	      udp-workers: INT
	      tcp-workers: INT
	      background-workers: INT
	      async-start: BOOL
	      tcp-idle-timeout:	TIME
	      tcp-io-timeout: INT
	      tcp-remote-io-timeout: INT
	      tcp-max-clients: INT
	      tcp-reuseport: BOOL
	      udp-max-payload: SIZE
	      udp-max-payload-ipv4: SIZE
	      udp-max-payload-ipv6: SIZE
	      edns-client-subnet: BOOL
	      answer-rotation: BOOL
	      listen: ADDR[@INT] ...
	      listen-xdp: STR[@INT] | ADDR[@INT] ...

       CAUTION:
	  When you change configuration	parameters dynamically or via configu-
	  ration  file	reload,	 some parameters in the	Server section require
	  restarting the Knot server so	that the changes take effect. See  be-
	  low for the details.

   identity
       An identity of the server returned in the response to the query for TXT
       record id.server. or hostname.bind. in the CHAOS	class (RFC 4892).  Set
       to an empty value to disable.

       Default:	FQDN hostname

   version
       A  version of the server	software returned in the response to the query
       for TXT record version.server. or version.bind. in the CHAOS class (RFC
       4892). Set to an	empty value to disable.

       Default:	server version

   nsid
       A  DNS name server identifier (RFC 5001). Set to	an empty value to dis-
       able.

       Default:	FQDN hostname

   rundir
       A path for storing run-time data	(PID file, unix	sockets, etc.).

       Depending on the	usage  of  this	 parameter,  its  change  may  require
       restart of the Knot server to take effect.

       Default:	${localstatedir}/run/knot (configured with --with-rundir=path)

   user
       A  system  user	with an	optional system	group (user:group) under which
       the server is run after starting	and binding to interfaces. Linux capa-
       bilities	are employed if	supported.

       Change  of  this	 parameter requires restart of the Knot	server to take
       effect.

       Default:	root:root

   pidfile
       A PID file location.

       Change of this parameter	requires restart of the	Knot  server  to  take
       effect.

       Default:	rundir/knot.pid

   udp-workers
       A number	of UDP workers (threads) used to process incoming queries over
       UDP.

       Change of this parameter	requires restart of the	Knot  server  to  take
       effect.

       Default:	equal to the number of online CPUs

   tcp-workers
       A number	of TCP workers (threads) used to process incoming queries over
       TCP.

       Change of this parameter	requires restart of the	Knot  server  to  take
       effect.

       Default:	 equal to the number of	online CPUs, default value is at least
       10

   background-workers
       A number	of workers (threads) used  to  execute	background  operations
       (zone loading, zone updates, etc.).

       Change  of  this	 parameter requires restart of the Knot	server to take
       effect.

       Default:	equal to the number of online CPUs, default value is  at  most
       10

   async-start
       If  enabled,  server doesn't wait for the zones to be loaded and	starts
       responding immediately with SERVFAIL answers until the zone loads.

       Default:	off

   tcp-idle-timeout
       Maximum idle time (in seconds) between requests on an inbound TCP  con-
       nection.	 It means if there is no activity on an	inbound	TCP connection
       during this limit, the connection is closed by the server.

       Minimum:	1 s

       Default:	10 s

   tcp-io-timeout
       Maximum time (in	milliseconds) to receive or send one DNS message  over
       an  inbound  TCP	 connection. It	means this limit applies to normal DNS
       queries and replies, incoming DDNS, and outgoing	 zone  transfers.  The
       timeout	is  measured since some	data is	already	available for process-
       ing.  Set to 0 for infinity.

       Default:	500 ms

       CAUTION:
	  In order to reduce the risk of Slow Loris attacks, it's  recommended
	  setting this limit as	low as possible	on public servers.

   tcp-remote-io-timeout
       Maximum	time (in milliseconds) to receive or send one DNS message over
       an outbound TCP connection which	has already been established to	a con-
       figured	remote	server.	  It means this	limit applies to incoming zone
       transfers, sending NOTIFY, DDNS forwarding, and DS check	or push.  This
       timeout	includes  the  time  needed for	a network round-trip and for a
       query processing	by the remote.	Set to 0 for infinity.

       Default:	5000 ms

   tcp-reuseport
       If enabled, each	TCP worker listens on its own socket and the OS	kernel
       socket load balancing is	emloyed	using SO_REUSEPORT (or SO_REUSEPORT_LB
       on FreeBSD). Due	to the lack of one shared socket, the server can offer
       higher  response	 rate  processing  over	 TCP.  However,	in the case of
       time-consuming requests (e.g. zone transfers of a  TLD  zone),  enabled
       reuseport may result in delayed or not being responded client requests.
       So it is	advisable to use this option on	slave servers.

       Change of this parameter	requires restart of the	Knot  server  to  take
       effect.

       Default:	off

   tcp-max-clients
       A  maximum  number of TCP clients connected in parallel,	set this below
       the file	descriptor limit to avoid resource exhaustion.

       NOTE:
	  It is	advisable to adjust the	 maximum  number  of  open  files  per
	  process in your operating system configuration.

       Default:	one half of the	file descriptor	limit for the server process

   udp-max-payload
       Maximum EDNS0 UDP payload size default for both IPv4 and	IPv6.

       Default:	1232

   udp-max-payload-ipv4
       Maximum EDNS0 UDP payload size for IPv4.

       Default:	1232

   udp-max-payload-ipv6
       Maximum EDNS0 UDP payload size for IPv6.

       Default:	1232

   edns-client-subnet
       Enable  or disable EDNS Client Subnet support. If enabled, responses to
       queries containing the EDNS Client Subnet option	always contain a valid
       EDNS Client Subnet option according to RFC 7871.

       Default:	off

   answer-rotation
       Enable or disable sorted-rrset rotation in the answer section of	normal
       replies.	 The rotation shift is simply determined by a query ID.

       Default:	off

   listen
       One or more IP addresses	where the server listens for incoming queries.
       Optional	port specification (default is 53) can be appended to each ad-
       dress using @ separator.	Use 0.0.0.0 for	all configured IPv4  addresses
       or  ::  for all configured IPv6 addresses. Non-local address binding is
       automatically enabled if	supported by the operating system.

       Change of this parameter	requires restart of the	Knot  server  to  take
       effect.

       Default:	not set

   listen-xdp
       One  or more network device names (e.g. ens786f0) on which the Mode XDP
       is enabled. Alternatively, an IP	address	can be used instead of	a  de-
       vice  name, but the server will still listen on all addresses belonging
       to the same interface!  Optional	port specification (default is 53) can
       be appended to each device name or address using	@ separator.

       Change  of  this	 parameter requires restart of the Knot	server to take
       effect.

       Default:	not set

       CAUTION:
	  Since	XDP workers only process regular DNS traffic over UDP,	it  is
	  strongly  recommended	 to also listen	on the addresses which are in-
	  tended to offer the DNS service, at least to fulfil the DNS require-
	  ment for working TCP.

CONTROL	SECTION
       Configuration of	the server control interface.

	  control:
	      listen: STR
	      timeout: TIME

   listen
       A UNIX socket path where	the server listens for control commands.

       Default:	rundir/knot.sock

   timeout
       Maximum	time (in seconds) the control socket operations	can take.  Set
       to 0 for	infinity.

       Default:	5

LOGGING	SECTION
       Server can be configured	to log to the standard output, standard	 error
       output,	syslog	(or  systemd journal if	systemd	is enabled) or into an
       arbitrary file.

       There are 6 logging severity levels:

       o critical a Non-recoverable error resulting in server shutdown.

       o error a Recoverable error, action should be taken.

       o warning a Warning that	might require user action.

       o notice	a Server notice	or hint.

       o info a	Informational message.

       o debug a Debug or detailed message.

       In the case of a	missing	log section, warning or	more serious  messages
       will  be	 logged	to both	standard error output and syslog. The info and
       notice messages will be logged to standard output.

	  log:
	    - target: stdout | stderr |	syslog | STR
	      server: critical | error | warning | notice | info | debug
	      control: critical	| error	| warning | notice | info | debug
	      zone: critical | error | warning | notice	| info | debug
	      any: critical | error | warning |	notice | info |	debug

   target
       A logging output.

       Possible	values:

       o stdout	a Standard output.

       o stderr	a Standard error output.

       o syslog	a Syslog or systemd journal.

       o file_name a A specific	file.

       With syslog target, syslog service is used. However, if	Knot  DNS  has
       been compiled with systemd support and operating	system has been	booted
       with systemd, systemd journal is	used for logging instead of syslog.

   server
       Minimum severity	level for messages related to general operation	of the
       server to be logged.

       Default:	not set

   control
       Minimum	severity  level	 for  messages related to server control to be
       logged.

       Default:	not set

   zone
       Minimum severity	level for messages related to zones to be logged.

       Default:	not set

   any
       Minimum severity	level for all message types to be logged.

       Default:	not set

STATISTICS SECTION
       Periodic	server statistics dumping.

	  statistics:
	      timer: TIME
	      file: STR
	      append: BOOL

   timer
       A period	after which all	available statistics metrics will  by  written
       to the file.

       Default:	not set

   file
       A file path of statistics output	in the YAML format.

       Default:	rundir/stats.yaml

   append
       If enabled, the output will be appended to the file instead of file re-
       placement.

       Default:	off

DATABASE SECTION
       Configuration of	databases for zone contents, DNSSEC metadata, or event
       timers.

	  database:
	      storage: STR
	      journal-db: STR
	      journal-db-mode: robust |	asynchronous
	      journal-db-max-size: SIZE
	      kasp-db: STR
	      kasp-db-max-size:	SIZE
	      timer-db:	STR
	      timer-db-max-size: SIZE
	      catalog-db: str
	      catalog-db-max-size: SIZE

   storage
       A data directory	for storing journal, KASP, and timer databases.

       Default:	  ${localstatedir}/lib/knot   (configured   with  --with-stor-
       age=path)

   journal-db
       An explicit specification of the	persistent journal database directory.
       Non-absolute path (i.e. not starting with /) is relative	to storage.

       Default:	storage/journal

   journal-db-mode
       Specifies  journal LMDB backend configuration, which influences perfor-
       mance and durability.

       Possible	values:

       o robust	a The journal database disk  sychronization  ensures  database
	 durability but	is generally slower.

       o asynchronous a	The journal database disk synchronization is optimized
	 for better performance	at the expense of lower	database durability in
	 the  case  of	a  crash. This mode is recommended on slave nodes with
	 many zones.

       Default:	robust

   journal-db-max-size
       The hard	limit for the journal  database	 maximum  size.	 There	is  no
       cleanup	logic  in journal to recover from reaching this	limit. Journal
       simply starts refusing changes across all zones.	Decreasing this	 value
       has no effect if	it is lower than the actual database file size.

       It  is  recommended  to	limit  journal-max-usage  per-zone  instead of
       journal-db-max-size in most cases. Please keep this value  larger  than
       the  sum	of all zones' journal usage limits. See	more details regarding
       journal behaviour.

       NOTE:
	  This value also influences server's usage of virtual memory.

       Default:	20 GiB (512 MiB	for 32-bit)

   kasp-db
       An explicit specification of the	KASP database directory.  Non-absolute
       path (i.e. not starting with /) is relative to storage.

       Default:	storage/keys

   kasp-db-max-size
       The hard	limit for the KASP database maximum size.

       NOTE:
	  This value also influences server's usage of virtual memory.

       Default:	500 MiB

   timer-db
       An  explicit  specification of the persistent timer database directory.
       Non-absolute path (i.e. not starting with /) is relative	to storage.

       Default:	storage/timers

   timer-db-max-size
       The hard	limit for the timer database maximum size.

       NOTE:
	  This value also influences server's usage of virtual memory.

       Default:	100 MiB

   catalog-db
       An explicit specification of the	zone catalog database directory.  Only
       useful  if  catalog-zones  are  enabled.	  Non-absolute	path (i.e. not
       starting	with /)	is relative to storage.

       Default:	storage/catalog

   catalog-db-max-size
       The hard	limit for the catalog database maximum size.

       NOTE:
	  This value also influences server's usage of virtual memory.

       Default:	20 GiB (512 MiB	for 32-bit)

KEYSTORE SECTION
       DNSSEC keystore configuration.

	  keystore:
	    - id: STR
	      backend: pem | pkcs11
	      config: STR

   id
       A keystore identifier.

   backend
       A key storage backend type.

       Possible	values:

       o pem a PEM files.

       o pkcs11	a PKCS #11 storage.

       Default:	pem

   config
       A backend specific configuration. A directory with PEM files (the  path
       can  be	specified  as  a  relative path	to kasp-db) or a configuration
       string for PKCS #11 storage (_pkcs11-url_ _module-path_).

       NOTE:
	  Example configuration	string for PKCS	#11:

	      "pkcs11:token=knot;pin-value=1234	/usr/lib64/pkcs11/libsofthsm2.so"

       Default:	kasp-db/keys

KEY SECTION
       Shared TSIG keys	used to	authenticate communication with	the server.

	  key:
	    - id: DNAME
	      algorithm: hmac-md5 | hmac-sha1 |	hmac-sha224 | hmac-sha256 | hmac-sha384	| hmac-sha512
	      secret: BASE64

   id
       A key name identifier.

       NOTE:
	  This value MUST be exactly the same as the name of the TSIG  key  on
	  the opposite master/slave server(s).

   algorithm
       A TSIG key algorithm. See TSIG Algorithm	Numbers.

       Possible	values:

       o hmac-md5

       o hmac-sha1

       o hmac-sha224

       o hmac-sha256

       o hmac-sha384

       o hmac-sha512

       Default:	not set

   secret
       Shared key secret.

       Default:	not set

REMOTE SECTION
       Definitions  of	remote	servers	 for outgoing connections (source of a
       zone transfer, target for a notification, etc.).

	  remote:
	    - id: STR
	      address: ADDR[@INT] ...
	      via: ADDR[@INT] ...
	      key: key_id
	      block-notify-after-transfer: BOOL

   id
       A remote	identifier.

   address
       An ordered list of destination IP addresses which are used for communi-
       cation  with the	remote server. The addresses are tried in sequence un-
       til the remote is reached. Optional destination port  (default  is  53)
       can be appended to the address using @ separator.

       Default:	not set

       NOTE:
	  If  the  remote is contacted and it refuses to perform requested ac-
	  tion,	no more	addresses will be tried	for this remote.

   via
       An ordered list of source IP addresses. The first address with the same
       family  as  the	destination address is used. Optional source port (de-
       fault is	random)	can be appended	to the address using @ separator.

       Default:	not set

   key
       A reference to the TSIG key which is used to authenticate the  communi-
       cation with the remote server.

       Default:	not set

   block-notify-after-transfer
       When  incoming AXFR/IXFR	from this remote (as a master),	suppress send-
       ing NOTIFY messages to all configured slaves.

       Default:	off

ACL SECTION
       Access control list rule	definitions. The ACLs are used to match	incom-
       ing connections to allow	or deny	requested operation (zone transfer re-
       quest, DDNS update, etc.).

	  acl:
	    - id: STR
	      address: ADDR[/INT] | ADDR-ADDR ...
	      key: key_id ...
	      remote: remote_id	...
	      action: notify | transfer	| update ...
	      deny: BOOL
	      update-type: STR ...
	      update-owner: key	| zone | name
	      update-owner-match: sub-or-equal | equal | sub
	      update-owner-name: STR ...

   id
       An ACL rule identifier.

   address
       An ordered list of IP addresses,	network	subnets,  or  network  ranges.
       The  query's  source  address must match	one of them. Empty value means
       that address match is not required.

       Default:	not set

   key
       An ordered list of references to	TSIG keys. The query must match	one of
       them. Empty value means that transaction	authentication is not used.

       Default:	not set

   remote
       An  ordered  list of references to remotes. The query must match	one of
       the remotes. Specifically, one of the remote's addresses	 and  remote's
       TSIG key	if configured must match.

       NOTE:
	  This option cannot be	specified along	with the address or key	option
	  at one ACL item.

       Default:	not set

   action
       An ordered list of allowed (or denied) actions.

       Possible	values:

       o notify	a Allow	incoming notify.

       o transfer a Allow zone transfer.

       o update	a Allow	zone updates.

       Default:	not set

   deny
       If enabled, instead of allowing,	deny the  specified  action,  address,
       key, or combination if these items. If no action	is specified, deny all
       actions.

       Default:	off

   update-type
       A list of allowed types of Resource Records in  a  zone	update.	 Every
       record in an update must	match one of the specified types.

       Default:	not set

   update-owner
       This option restricts possible owners of	Resource Records in a zone up-
       date by comparing them to either	the TSIG  key  identity,  the  current
       zone  name, or to a list	of domain names	given by the update-owner-name
       option.	The comparison method is given by the  update-owner-match  op-
       tion.

       Possible	values:

       o key  a	 The  owner  of	each updated RR	must match the identity	of the
	 TSIG key if used.

       o name a	The owner of each updated RR must match	at least one  name  in
	 the update-owner-name list.

       o zone a	The owner of each updated RR must match	the current zone name.

       Default:	not set

   update-owner-match
       This option defines how the owners of Resource Records in an update are
       matched to the domain name(s) set by the	update-owner option.

       Possible	values:

       o sub-or-equal a	The owner of each Resource Record in  an  update  must
	 either	 be  equal  to or be a subdomain of at least one domain	set by
	 update-owner.

       o equal a The owner of each updated RR must be equal to	at  least  one
	 domain	set by update-owner.

       o sub  a	 The owner of each updated RR must be a	subdomain of, but MUST
	 NOT be	equal to at least one domain set by update-owner.

       Default:	sub-or-equal

   update-owner-name
       A list of allowed owners	of RRs in a zone update	used with update-owner
       set to name. Every listed owner name which is not FQDN (i.e. it doesn't
       end in a	dot) is	considered as if it was	appended with the target  zone
       name.   Such a relative owner name specification	allows better ACL rule
       reusability across multiple zones.

       Default:	not set

SUBMISSION SECTION
       Parameters of KSK submission checks.

	  submission:
	    - id: STR
	      parent: remote_id	...
	      check-interval: TIME
	      timeout: TIME

   id
       A submission identifier.

   parent
       A list of references to parent's	DNS servers to be checked for presence
       of  corresponding DS records in the case	of KSK submission. All of them
       must have a corresponding DS for	the rollover to	continue. If  none  is
       specified, the rollover must be pushed forward manually.

       Default:	not set

       TIP:
	  A DNSSEC-validating resolver can be set as a parent.

   check-interval
       Interval	for periodic checks of DS presence on parent's DNS servers, in
       the case	of the KSK submission.

       Default:	1 hour

   timeout
       After this time period (in seconds) the KSK submission is automatically
       considered  successful, even if all the checks were negative or no par-
       ents are	configured.  Set to 0 for infinity.

       Default:	0

POLICY SECTION
       DNSSEC policy configuration.

	  policy:
	    - id: STR
	      keystore:	STR
	      manual: BOOL
	      single-type-signing: BOOL
	      algorithm: rsasha1 | rsasha1-nsec3-sha1 |	rsasha256 | rsasha512 |	ecdsap256sha256	| ecdsap384sha384 | ed25519 | ed448
	      ksk-size:	SIZE
	      zsk-size:	SIZE
	      ksk-shared: BOOL
	      dnskey-ttl: TIME
	      zone-max-ttl: TIME
	      ksk-lifetime: TIME
	      zsk-lifetime: TIME
	      propagation-delay: TIME
	      rrsig-lifetime: TIME
	      rrsig-refresh: TIME
	      rrsig-pre-refresh: TIME
	      reproducible-signing: BOOL
	      nsec3: BOOL
	      nsec3-iterations:	INT
	      nsec3-opt-out: BOOL
	      nsec3-salt-length: INT
	      nsec3-salt-lifetime: TIME
	      signing-threads: INT
	      ksk-submission: submission_id
	      ds-push: remote_id
	      cds-cdnskey-publish: none	| delete-dnssec	| rollover | always | double-ds
	      offline-ksk: BOOL

   id
       A policy	identifier.

   keystore
       A reference to a	keystore holding private key material for zones.

       Default:	an imaginary keystore with all default values

       NOTE:
	  A configured keystore	called "default" won't be used unless  explic-
	  itly referenced.

   manual
       If enabled, automatic key management is not used.

       Default:	off

   single-type-signing
       If  enabled,  Single-Type  Signing  Scheme is used in the automatic key
       management mode.

       Default:	off (module onlinesign has default on)

   algorithm
       An algorithm of signing keys and	issued signatures.  See	 DNSSEC	 Algo-
       rithm Numbers.

       Possible	values:

       o rsasha1

       o rsasha1-nsec3-sha1

       o rsasha256

       o rsasha512

       o ecdsap256sha256

       o ecdsap384sha384

       o ed25519

       o ed448

       NOTE:
	  Ed25519 algorithm is only available if compiled with GnuTLS 3.6.0+.

	  Ed448	 algorithm  is	only available if compiled with	GnuTLS 3.6.12+
	  and Nettle 3.6+.

       Default:	ecdsap256sha256

   ksk-size
       A length	of newly generated KSK or CSK keys.

       Default:	2048 (rsa*), 256 (ecdsap256), 384 (ecdsap384), 256  (ed25519),
       456 (ed448)

   zsk-size
       A length	of newly generated ZSK keys.

       Default:	see default for	ksk-size

   ksk-shared
       If enabled, all zones with this policy assigned will share one KSK.

       Default:	off

   dnskey-ttl
       A TTL value for DNSKEY records added into zone apex.

       NOTE:
	  Has infuence over ZSK	key lifetime.

       WARNING:
	  Ensure all DNSKEYs with updated TTL are propagated before any	subse-
	  quent	DNSKEY rollover	starts.

       Default:	zone SOA TTL

   zone-max-ttl
       Declare (override) maximal TTL value among all the records in zone.

       NOTE:
	  It's generally recommended to	override the maximal  TTL  computation
	  by  setting  this  explicitly	 whenever  possible. It's required for
	  DNSSEC Offline KSK and really	reasonable when	records	are  generated
	  dynamically (e.g. by a module).

       Default:	computed after zone is loaded

   ksk-lifetime
       A period	between	KSK activation and the next rollover initiation.

       NOTE:
	  KSK key lifetime is also infuenced by	propagation-delay, dnskey-ttl,
	  and KSK submission delay.

	  Zero (aka infinity) value causes no KSK rollover as a	result.

	  This applies for CSK lifetime	if single-type-signing is enabled.

       Default:	0

   zsk-lifetime
       A period	between	ZSK activation and the next rollover initiation.

       NOTE:
	  More exactly,	this period is measured	since a	ZSK is activated,  and
	  after	 this,	a  new ZSK is generated	to replace it within following
	  roll-over.

	  ZSK  key  lifetime  is  also	infuenced  by  propagation-delay   and
	  dnskey-ttl

	  Zero (aka infinity) value causes no ZSK rollover as a	result.

       Default:	30 days

   propagation-delay
       An  extra  delay	added for each key rollover step. This value should be
       high enough to cover propagation	of data	from the master	server to  all
       slaves.

       NOTE:
	  Has infuence over ZSK	key lifetime.

       Default:	1 hour

   rrsig-lifetime
       A validity period of newly issued signatures.

       NOTE:
	  The  RRSIG's	signature  inception  time is set to 90	minutes	in the
	  past.	This time period is not	counted	to the signature lifetime.

       Default:	14 days

   rrsig-refresh
       A period	how long at least before a signature expiration	the  signature
       will  be	refreshed, in order to prevent expired RRSIGs on slaves	or re-
       solvers'	caches.

       Default:	7 days

   rrsig-pre-refresh
       A period	how long at most before	a signature refresh time the signature
       might  be  refreshed, in	order to refresh RRSIGs	in bigger batches on a
       frequently updated zone (avoid re-sign event too	often).

       Default:	1 hour

   reproducible-signing
       For ECDSA algorithms, generate RRSIG signatures deterministically  (RFC
       6979).	Besides	 better	 theoretical cryptographic security, this mode
       allows significant speed-up of loading  signed  (by  the	 same  method)
       zones. However, the zone	signing	is a bit slower.

       Default:	off

   nsec3
       Specifies if NSEC3 will be used instead of NSEC.

       Default:	off

   nsec3-iterations
       A number	of additional times the	hashing	is performed.

       Default:	5

   nsec3-opt-out
       If  set,	NSEC3 records won't be created for insecure delegations.  This
       speeds up the zone signing and reduces overall zone size.

       WARNING:
	  NSEC3	with the Opt-Out bit set no longer works as a proof of non-ex-
	  istence in this zone.

       Default:	off

   nsec3-salt-length
       A  length  of a salt field in octets, which is appended to the original
       owner name before hashing.

       Default:	8

   nsec3-salt-lifetime
       A validity period of newly issued salt field.

       Zero value means	infinity.

       Default:	30 days

   signing-threads
       When signing zone or update, use	this number of	threads	 for  parallel
       signing.

       Those are extra threads independent of Background workers.

       NOTE:
	  Some steps of	the DNSSEC signing operation are not parallelized.

       Default:	1 (no extra threads)

   ksk-submission
       A  reference to submission section holding parameters of	KSK submission
       checks.

       Default:	not set

   ds-push
       An optional reference to	authoritative DNS server of the	parent's zone.
       The  remote  server  must be configured to accept DS record updates via
       DDNS. Whenever a	CDS record in the local	zone is	 changed,  the	corre-
       sponding	DS record is sent as a dynamic update (DDNS) to	the parent DNS
       server. All previous DS records are deleted within  the	DDNS  message.
       It's  possible  to  manage both child and parent	zones by the same Knot
       DNS server.

       NOTE:
	  This feature requires	cds-cdnskey-publish not	to be set to none.

       NOTE:
	  Module Onlinesign doesn't support DS push.

       Default:	not set

   cds-cdnskey-publish
       Controls	if and how shall the CDS and CDNSKEY be	published in the zone.

       Possible	values:

       o none a	Never publish any CDS or CDNSKEY records in the	zone.

       o delete-dnssec a Publish special CDS and  CDNSKEY  records  indicating
	 turning off DNSSEC.

       o rollover  a  Publish  CDS  and	CDNSKEY	records	only in	the submission
	 phase of KSK rollover.

       o always	a Always publish one CDS and one CDNSKEY records for the  cur-
	 rent KSK.

       o double-ds  a Always publish up	to two CDS and two CDNSKEY records for
	 ready and/or active KSKs.

       NOTE:
	  If the zone keys are managed manually, the CDS  and  CDNSKEY	rrsets
	  may contain more records depending on	the keys available.

       Default:	rollover

   offline-ksk
       Specifies if Offline KSK	feature	is enabled.

       Default:	off

TEMPLATE SECTION
       A template is shareable zone settings, which can	simplify configuration
       by reducing duplicates. A special default template  (with  the  default
       identifier) can be used for global zone configuration or	as an implicit
       configuration if	a zone doesn't have another template specified.

	  template:
	    - id: STR
	      global-module: STR/STR ...
	      #	All zone options (excluding 'template' item)

   id
       A template identifier.

   global-module
       An ordered list of references to	query modules  in  the	form  of  mod-
       ule_name	or module_name/module_id. These	modules	apply to all queries.

       NOTE:
	  This option is only available	in the default template.

       Default:	not set

ZONE SECTION
       Definition of zones served by the server.

	  zone:
	    - domain: DNAME
	      template:	template_id
	      storage: STR
	      file: STR
	      master: remote_id	...
	      ddns-master: remote_id
	      notify: remote_id	...
	      acl: acl_id ...
	      semantic-checks: BOOL
	      zonefile-sync: TIME
	      zonefile-load: none | difference | difference-no-serial |	whole
	      journal-content: none | changes |	all
	      journal-max-usage: SIZE
	      journal-max-depth: INT
	      zone-max-size : SIZE
	      adjust-threads: INT
	      dnssec-signing: BOOL
	      dnssec-validation: BOOL
	      dnssec-policy: STR
	      serial-policy: increment | unixtime | dateserial
	      refresh-min-interval: TIME
	      refresh-max-interval: TIME
	      catalog-role: none | interpret
	      catalog-template:	template_id
	      module: STR/STR ...

   domain
       A zone name identifier.

   template
       A reference to a	configuration template.

       Default:	not set	or default (if the template exists)

   storage
       A data directory	for storing zone files.

       Default:	  ${localstatedir}/lib/knot   (configured   with  --with-stor-
       age=path)

   file
       A path to the zone file.	Non-absolute path (i.e.	not starting  with  /)
       is  relative to storage.	 It is also possible to	use the	following for-
       matters:

       o %c[N] or %c[N-M] a Means the Nth character or a sequence  of  charac-
	 ters  beginning from the Nth and ending with the Mth character	of the
	 textual zone name (see	%s). The indexes are counted from 0  from  the
	 left.	All  dots  (including the terminal one)	are considered.	If the
	 character is not available, the formatter has no effect.

       o %l[N] a Means the Nth label of	the textual zone name  (see  %s).  The
	 index	is  counted  from 0 from the right (0 ~	TLD).  If the label is
	 not available,	the formatter has no effect.

       o %s a Means the	current	zone name in the textual representation.   The
	 zone  name  doesn't  include  the terminating dot (the	result for the
	 root zone is the empty	string!).

       o %% a Means the	% character.

       WARNING:
	  Beware of special characters which are escaped  or  encoded  in  the
	  \DDD form where DDD is corresponding decimal ASCII code.

       Default:	storage/%s.zone

   master
       An ordered list of references to	zone master servers.

       Default:	not set

   ddns-master
       A reference to zone primary master server.  If not specified, the first
       master server is	used.

       Default:	not set

   notify
       An ordered list of references to	remotes	to  which  notify  message  is
       sent if the zone	changes.

       Default:	not set

   acl
       An  ordered list	of references to ACL rules which can allow or disallow
       zone transfers, updates or incoming notifies.

       Default:	not set

   semantic-checks
       If enabled, extra zone semantic checks are turned on.

       Several checks are enabled by default and cannot	be turned off. An  er-
       ror in mandatory	checks causes zone not to be loaded. An	error in extra
       checks is logged	only.

       Mandatory checks:

       o SOA record missing in the zone	(RFC 1034)

       o An extra record together with CNAME record except for RRSIG and DS (-
	 RFC 1034)

       o Multiple CNAME	record with the	same owner

       o DNAME record having a record under it (RFC 2672)

       Extra checks:

       o Missing NS record at the zone apex

       o Missing glue A	or AAAA	record

       o Invalid DNSKEY, DS, or	NSEC3PARAM record

       o CDS or	CDNSKEY	inconsistency

       o Missing, invalid, or unverifiable RRSIG record

       o Invalid NSEC(3) record

       o Broken	or non-cyclic NSEC(3) chain

       Default:	off

   zonefile-sync
       The  time  after	which the current zone in memory will be synced	with a
       zone file on the	disk (see file). The server will serve the latest zone
       even  after a restart using zone	journal, but the zone file on the disk
       will only be synced after zonefile-sync time has	expired	(or after man-
       ual  zone flush). This is applicable when the zone is updated via IXFR,
       DDNS or automatic DNSSEC	signing. In order to completely	disable	 auto-
       matic  zone file	synchronization, set the value to -1. In that case, it
       is still	possible to force a manual zone	flush using the	-f option.

       NOTE:
	  If you are serving large zones with frequent updates where the imme-
	  diate	sync with a zone file is not desirable,	increase the value.

       Default:	0 (immediate)

   zonefile-load
       Selects how the zone file contents are applied during zone load.

       Possible	values:

       o none a	The zone file is not used at all.

       o difference a If the zone contents are already available during	server
	 start or reload, the difference is computed between them and the con-
	 tents	of the zone file. This difference is then checked for semantic
	 errors	and applied to the current zone	contents.

       o difference-no-serial a	Same as	difference, but	the SOA	serial in  the
	 zone  file  is	ignored, the server takes care of incrementing the se-
	 rial automatically.

       o whole a Zone contents are loaded from the zone	file.

       When difference is configured and there are no zone contents yet	 (cold
       start of	Knot and no zone contents in journal), it behaves the same way
       like whole.

       Default:	whole

   journal-content
       Selects how the journal shall be	used to	store zone and its changes.

       Possible	values:

       o none a	The journal is not used	at all.

       o changes a Zone	changes	history	is stored in journal.

       o all a Zone contents and history is stored in journal.

       Default:	changes

   journal-max-usage
       Policy how much space in	journal	DB will	the zone's journal occupy.

       NOTE:
	  Journal DB may grow far above	the sum	 of  journal-max-usage	across
	  all zones, because of	DB free	space fragmentation.

       Default:	100 MiB

   journal-max-depth
       Maximum history length of journal.

       Minimum:	2

       Default:	2^64

   zone-max-size
       Maximum	size  of  the  zone.  The size is measured as size of the zone
       records in wire format without compression. The limit is	 enforced  for
       incoming	zone transfers and dynamic updates.

       For  incremental	 transfers  (IXFR),  the effective limit for the total
       size of the records in the transfer is twice the	configured value. How-
       ever the	final size of the zone must satisfy the	configured value.

       Default:	2^64

   adjust-threads
       Parallelize  internal  zone  adjusting  procedures. This	is useful with
       huge zones with NSEC3. Speedup observable at server startup  and	 while
       processing NSEC3	re-salt.

       Default:	1

   dnssec-signing
       If enabled, automatic DNSSEC signing for	the zone is turned on.

       Default:	off

   dnssec-validation
       If  enabled, the	zone contents are validated for	being correctly	signed
       (including NSEC/NSEC3 chain) with DNSSEC	signatures every time the zone
       is loaded or changed (including AXFR/IXFR).

       When  the  validation  fails, the zone being loaded or update being ap-
       plied is	cancelled with an error, and  either  none  or	previous  zone
       state is	published.

       List of DNSSEC checks:

       o Every zone RRSet is correctly signed by at least one present DNSKEY.

       o DNSKEY	RRSet is signed	by KSK.

       o NSEC(3) RR exists for each name (unless opt-out) with correct bitmap.

       o Every NSEC(3) RR is linked to the lexicographically next one.

       The  validation	is not affected	by dnssec-policy configuration,	except
       for signing-threads option, which specifies the number of  threads  for
       parallel	validation.

       NOTE:
	  Redundant or garbage NSEC3 records are ignored.

	  This mode is not compatible with dnssec-signing.

   dnssec-policy
       A reference to DNSSEC signing policy.

       Default:	an imaginary policy with all default values

       NOTE:
	  A configured policy called "default" won't be	used unless explicitly
	  referenced.

   serial-policy
       Specifies how the zone serial is	updated	after a	dynamic	update or  au-
       tomatic DNSSEC signing. If the serial is	changed	by the dynamic update,
       no change is made.

       Possible	values:

       o increment a The serial	is  incremented	 according  to	serial	number
	 arithmetic.

       o unixtime a The	serial is set to the current unix time.

       o dateserial  a	The  10-digit  serial (YYYYMMDDnn) is incremented, the
	 first 8 digits	match the current iso-date.

       NOTE:
	  In case of unixtime, if the resulting	serial is lower	or equal  than
	  current zone (this happens e.g. in case of migrating from other pol-
	  icy or frequent updates) the serial is incremented instead.

	  Use dateserial only if you expect less than 100 updates per day  per
	  zone.

       Default:	increment

   refresh-min-interval
       Forced minimum zone refresh interval to avoid flooding master.

       Default:	2

   refresh-max-interval
       Forced maximum zone refresh interval.

       Default:	not set

   catalog-role
       Trigger zone catalog feature. Possible values:

       o none a	Not a catalog zone.

       o interpret  a  A catalog zone which is loaded from a zone file or XFR,
	 and member zones shall	be configured based on its contents.

       Default:	none

   catalog-template
       For the catalog-member zones, the specified configuration template will
       be applied.

       NOTE:
	  This option must be set if and only if catalog-role is interpret.

       Default:	not set

   module
       An  ordered  list  of  references  to query modules in the form of mod-
       ule_name	or module_name/module_id. These	modules	apply only to the cur-
       rent zone queries.

       Default:	not set

AUTHOR
       CZ.NIC Labs <https://www.knot-dns.cz>

COPYRIGHT
       Copyright 2010a2020, CZ.NIC, z.s.p.o.

3.0.3				  2020-12-15			  KNOT.CONF(5)

NAME | DESCRIPTION | COMMENTS | INCLUDES | MODULE SECTION | SERVER SECTION | CONTROL SECTION | LOGGING SECTION | STATISTICS SECTION | DATABASE SECTION | KEYSTORE SECTION | KEY SECTION | REMOTE SECTION | ACL SECTION | SUBMISSION SECTION | POLICY SECTION | TEMPLATE SECTION | ZONE SECTION | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=knot.conf&sektion=5&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help