upstream/knot-dns
1
0
Fork 0
mirror of https://gitlab.nic.cz/knot/knot-dns.git synced 2026-05-28 04:02:31 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: update configuration reference

Browse source
This commit is contained in:
Daniel Salzman 2015-05-31 21:21:29 +02:00
parent e1d7ee5637
commit 6b7bdf74a2
4 changed files with 122 additions and 117 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
doc/configuration.rst
View file

@ -100,7 +100,7 @@ key can be specified::
key: key1 # Access based just on TSIG key
action: transfer
These rules can then be referenced from a zone :ref:`template_acl`::
These rules can then be referenced from a zone :ref:`zone_acl`::
zone:
- domain: example.com
@ -110,10 +110,10 @@ Slave zone
==========
Knot DNS doesn't strictly differ between master and slave zones. The
only requirement is to have :ref:`master<template_master>` statement set for
only requirement is to have :ref:`master<zone_master>` statement set for
the given zone. Also note that you need to explicitly allow incoming zone
changed notifications via ``notify`` :ref:`acl_action` through zone's
:ref:`template_acl` list, otherwise the update will be rejected by the server.
:ref:`zone_acl` list, otherwise the update will be rejected by the server.
If the zone file doesn't exist it will be bootstrapped over AXFR::
remote:
@ -132,7 +132,7 @@ If the zone file doesn't exist it will be bootstrapped over AXFR::
master: master
acl: master_acl
Note that the :ref:`template_master` option accepts a list of multiple remotes.
Note that the :ref:`zone_master` option accepts a list of multiple remotes.
The first remote in the list is used as the primary master, and the rest is used
for failover if the connection with the primary master fails.
The list is rotated in this case, and a new primary is elected.
@ -268,8 +268,8 @@ can operate in two modes:
according to assigned policy and are rolled automatically in a safe manner.
No zone operator intervention is necessary.
The DNSSEC signing is controlled by the :ref:`template_dnssec-signing` and
:ref:`template_kasp_db` configuration options. The first option states
The DNSSEC signing is controlled by the :ref:`zone_dnssec-signing` and
:ref:`zone_kasp_db` configuration options. The first option states
if the signing is enabled for a particular zone, the second option points to
a KASP database holding the signing configuration.
@ -589,7 +589,7 @@ extend it or even change it altogether.
Each module is configured in the corresponding module section and is
identified for the subsequent usage. Then, the identifier is referenced
through :ref:`template_module` option (in the form of ``module_name/module_id``)
through :ref:`zone_module` option (in the form of ``module_name/module_id``)
in the zone section or in the ``default`` template if it used for all queries.
``dnstap`` - dnstap-enabled query logging

84
doc/man/knot.conf.5in
View file

@ -427,9 +427,9 @@ Default: empty
.SH TEMPLATE SECTION
.sp
A template is shareable zone settings which can be used for configuration of
many zones at one place. A special default template (with \fIdefault\fP identifier)
many zones at one place. A special default template (with the \fIdefault\fP identifier)
can be used for general quering configuration or as an implicit default
configuration if a zone doesn\(aqt have a teplate specified.
configuration if a zone doesn\(aqt have another template specified.
.INDENT 0.0
.INDENT 3.5
.sp
@ -437,6 +437,26 @@ configuration if a zone doesn\(aqt have a teplate specified.
.ft C
template:
\- id: STR
# All zone options (excluding \(aqtemplate\(aq item)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A template identifier.
.SH ZONE SECTION
.sp
Definition of zones served by the server.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zone:
\- domain: DNAME
template: template_id
file: STR
storage: STR
master: remote_id ...
notify: remote_id ...
@ -454,9 +474,29 @@ template:
.fi
.UNINDENT
.UNINDENT
.SS id
.SS domain
.sp
A template identifier.
A zone name identifier.
.SS template
.sp
A \fI\%reference\fP to a configuration template. If not specified
and the \fIdefault\fP template exists, the default template is used.
.sp
Default: empty
.SS file
.sp
A path to the zone file. Non absolute path is relative to
\fI\%storage\fP\&. It is also possible to use the following formatters:
.INDENT 0.0
.IP \(bu 2
\fI%s\fP \- means the current zone name in the textual representation (beware of special
characters which are escaped or encoded in the \eDDD form). Each zone name is
terminated with a dot character!
.IP \(bu 2
\fI%%\fP \- means the \fI%\fP character
.UNINDENT
.sp
Default: \fI\%storage\fP/\fB%s\fPzone
.SS storage
.sp
A data directory for storing zone files, journal files and timers database.
@ -606,42 +646,6 @@ An ordered list of references to query modules in the form
\fImodule_name/module_id\fP\&.
.sp
Default: empty
.SH ZONE SECTION
.sp
Definitions of zones served by the server.
.sp
Zone configuration is a superset of \fI\%template configuration\fP,
so each zone configuration can contain all template configuration options which
may override possible template configuration.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zone:
\- domain: DNAME
file: STR
template: template_id
# All template options
.ft P
.fi
.UNINDENT
.UNINDENT
.SS domain
.sp
A zone name identifier.
.SS file
.sp
A path to the zone file. Non absolute path is relative to
\fI\%storage\fP\&.
.sp
Default: \fI\%storage\fP/\fBdomain\fP\&.zone
.SS template
.sp
A \fI\%reference\fP to configuration template. If not specified
and \fIdefault\fP template exists, then the default template is used.
.sp
Default: empty
.SH LOGGING SECTION
.sp
Server can be configured to log to the standard output, standard error

135
doc/reference.rst
View file

@ -515,14 +515,36 @@ Template section
================
A template is shareable zone settings which can be used for configuration of
many zones at one place. A special default template (with *default* identifier)
many zones at one place. A special default template (with the *default* identifier)
can be used for general quering configuration or as an implicit default
configuration if a zone doesn't have a teplate specified.
configuration if a zone doesn't have another template specified.
::
template:
- id: STR
# All zone options (excluding 'template' item)
.. _template_id:
id
--
A template identifier.
.. _Zone section:
Zone section
============
Definition of zones served by the server.
::
zone:
- domain: DNAME
template: template_id
file: STR
storage: STR
master: remote_id ...
notify: remote_id ...
@ -537,14 +559,39 @@ configuration if a zone doesn't have a teplate specified.
serial-policy: increment | unixtime
module: STR/STR ...
.. _template_id:
.. _zone_domain:
id
--
domain
------
A template identifier.
A zone name identifier.
.. _template_storage:
.. _zone_template:
template
--------
A :ref:`reference<template_id>` to a configuration template. If not specified
and the *default* template exists, the default template is used.
Default: empty
.. _zone_file:
file
----
A path to the zone file. Non absolute path is relative to
:ref:`storage<zone_storage>`. It is also possible to use the following formatters:
- `%s` - means the current zone name in the textual representation (beware of special
characters which are escaped or encoded in the \\DDD form). Each zone name is
terminated with a dot character!
- `%%` - means the `%` character
Default: :ref:`storage<zone_storage>`/``%s``\ zone
.. _zone_storage:
storage
-------
@ -553,7 +600,7 @@ A data directory for storing zone files, journal files and timers database.
Default: ``${localstatedir}/lib/knot`` (configured with ``--with-storage=path``)
.. _template_master:
.. _zone_master:
master
------
@ -562,7 +609,7 @@ An ordered list of :ref:`references<remote_id>` to zone master servers.
Default: empty
.. _template_notify:
.. _zone_notify:
notify
------
@ -572,7 +619,7 @@ message is sent if the zone changes.
Default: empty
.. _template_acl:
.. _zone_acl:
acl
---
@ -582,7 +629,7 @@ or disallow zone transfers, updates or incoming notifies.
Default: empty
.. _template_semantic-checks:
.. _zone_semantic-checks:
semantic-checks
---------------
@ -622,7 +669,7 @@ Extra checks:
Default: off
.. _template_disable-any:
.. _zone_disable-any:
disable-any
-----------
@ -633,7 +680,7 @@ the risk of DNS reflection attack.
Default: off
.. _template_zonefile-sync:
.. _zone_zonefile-sync:
zonefile-sync
-------------
@ -650,7 +697,7 @@ the immediate sync to zone file is not desirable, increase the default value.
Default: 0 (immediate)
.. _template_ixfr-from-differences:
.. _zone_ixfr-from-differences:
ixfr-from-differences
---------------------
@ -661,7 +708,7 @@ is a master server for the zone.
Default: off
.. _template_max_journal_size:
.. _zone_max_journal_size:
max-journal-size
----------------
@ -670,7 +717,7 @@ Maximum size of the zone journal file.
Default: unlimited
.. _template_dnssec-signing:
.. _zone_dnssec-signing:
dnssec-signing
--------------
@ -679,17 +726,17 @@ If enabled, automatic DNSSEC signing for the zone is turned on.
Default: off
.. _template_kasp_db:
.. _zone_kasp_db:
kasp-db
-------
A KASP database path. Non absolute path is relative to
:ref:`storage<template_storage>`.
:ref:`storage<zone_storage>`.
Default: :ref:`storage<template_storage>`/keys
Default: :ref:`storage<zone_storage>`/keys
.. _template_serial-policy:
.. _zone_serial-policy:
serial-policy
-------------
@ -710,7 +757,7 @@ done by hand (see RFC 1982).
Default: increment
.. _template_module:
.. _zone_module:
module
------
@ -720,52 +767,6 @@ An ordered list of references to query modules in the form
Default: empty
.. _Zone section:
Zone section
============
Definitions of zones served by the server.
Zone configuration is a superset of :ref:`template configuration<Template section>`,
so each zone configuration can contain all template configuration options which
may override possible template configuration.
::
zone:
- domain: DNAME
file: STR
template: template_id
# All template options
.. _zone_domain:
domain
------
A zone name identifier.
.. _zone_file:
file
----
A path to the zone file. Non absolute path is relative to
:ref:`storage<template_storage>`.
Default: :ref:`storage<template_storage>`/``domain``.zone
.. _zone_template:
template
--------
A :ref:`reference<template_id>` to configuration template. If not specified
and *default* template exists, then the default template is used.
Default: empty
.. _Logging section:
Logging section

6
doc/running.rst
View file

@ -29,7 +29,7 @@ Example of server stop::
For a complete list of actions refer to ``knotd -h`` and ``knotc -h``
or corresponding man pages.
Also, the server needs to create :ref:`server_rundir` and :ref:`template_storage`
Also, the server needs to create :ref:`server_rundir` and :ref:`zone_storage`
directories in order to run properly.
.. _Configuration database:
@ -57,7 +57,7 @@ Running the server as a slave is very straightforward as you usually
bootstrap zones over AXFR and thus avoid any manual zone operations.
In contrast to AXFR, when the incremental transfer finishes, it stores
the differences in the journal file and doesn't update the zone file
immediately but after :ref:`template_zonefile-sync` period elapses.
immediately but after :ref:`zone_zonefile-sync` period elapses.
.. _Running a master server:
@ -94,7 +94,7 @@ action::
$ knotc -c master.conf reload
If you want to enable ixfr differences creation from changes you make to a
zone file, enable :ref:`template_ixfr-from-differences` in the zone configuration
zone file, enable :ref:`zone_ixfr-from-differences` in the zone configuration
and reload your server as seen above. If *SOA*'s *serial* is not changed,
no differences will be created.