Commit a62a293e authored by Libor Peltan's avatar Libor Peltan

doc: update to track journal_lmdb refactoring

...including configuration changes of max-journal-size, max-journal-usage, max-journal-depth ...
parent c96aa5c9
......@@ -46,7 +46,8 @@ Removes changes coloring.
Limits the number of displayed changes.
.TP
\fB\-t\fP, \fB\-\-list\-zones\fP
Instead of reading jurnal, display the list of zones in the DB (\fIzone_name\fP not needed)
Instead of reading jurnal, display the list of zones in the DB.
(\fIzone_name\fP not needed)
.TP
\fB\-h\fP, \fB\-\-help\fP
Print the program help.
......
......@@ -635,6 +635,8 @@ if a zone doesn\(aqt have another template specified.
template:
\- id: STR
timer\-db: STR
journal: STR
max\-journal\-size: SIZE
global\-module: STR/STR ...
# All zone options (excluding \(aqtemplate\(aq item)
.ft P
......@@ -657,6 +659,38 @@ This option is only available in the \fIdefault\fP template.
.UNINDENT
.sp
\fIDefault:\fP \fI\%storage\fP/timers
.SS journal\-db
.sp
Specifies a path of the persistent journal database. The path can be specified
as a relative path to the \fIdefault\fP template \fI\%storage\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP \fI\%storage\fP/journal
.SS max\-journal\-db\-size
.sp
Hard limit for the common journal DB. 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 lower than actual
DB file size.
.sp
It is recommended to limit \fI\%max\-journal\-usage\fP
per\-zone instead of max\-journal\-size in most cases. Please keep this value
large enough. This value also influences server\(aqs usage of virtual memory.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP 20 GiB
.SS global\-module
.sp
An ordered list of references to query modules in the form of \fImodule_name\fP or
......@@ -683,7 +717,6 @@ zone:
template: template_id
storage: STR
file: STR
journal: STR
master: remote_id ...
ddns\-master: remote_id
notify: remote_id ...
......@@ -692,7 +725,8 @@ zone:
disable\-any: BOOL
zonefile\-sync: TIME
ixfr\-from\-differences: BOOL
max\-journal\-size: SIZE
max\-journal\-usage: SIZE
max\-journal\-depth: SIZE
max\-zone\-size : SIZE
dnssec\-signing: BOOL
dnssec\-policy: STR
......@@ -742,13 +776,6 @@ terminating dot (the result for the root zone is the empty string!).
.UNINDENT
.sp
\fIDefault:\fP \fI\%storage\fP/\fB%s\fP\&.zone
.SS journal
.sp
A path to the zone journal. Non absolute path is relative to
\fI\%storage\fP\&. The same set of formatters as for
\fI\%file\fP is supported.
.sp
\fIDefault:\fP \fI\%storage\fP/\fB%s\fP\&.db
.SS master
.sp
An ordered list of \fI\%references\fP to zone master servers.
......@@ -869,19 +896,24 @@ This option has no effect with enabled
.UNINDENT
.sp
\fIDefault:\fP off
.SS max\-journal\-size
.SS max\-journal\-usage
.sp
Maximum size of the journal DB.
Policy how much space in journal DB will the zone\(aqs journal occupy.
.sp
\fIDefault:\fP 1 GiB
\fIDefault:\fP 100 MiB
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Decreasing this value will lead to discarding
whole journal history of all zones.
Journal DB may grow far above the sum of max\-journal\-usage across
all zones, because of DB free space fragmentation.
.UNINDENT
.UNINDENT
.SS max\-journal\-depth
.sp
Maximum history length of journal.
.sp
\fIDefault:\fP 2^64
.SS max\-zone\-size
.sp
Maximum size of the zone. The size is measured as size of the zone records
......
......@@ -246,6 +246,37 @@ A full example of setting up a completely new zone from scratch::
$ knotc zone-set example.com www 3600 A 192.168.0.100
$ knotc zone-commit example.com
.. _Journal behaviour:
Journal behaviour
=================
Zone journal keeps some history of changes of the zone. It is useful for
responding IXFR queries. Also if zone file flush is disabled,
journal keeps diff between zonefile and zone for the case of server shutdown.
The history is stored by changesets - diffs of zone contents between two
(usually subsequent) zone serials.
Journals for all zones are stored in common LMDB database. Huge changesets are
split into 70 KiB (this constant is hardcoded) blocks to prevent fragmentation of the DB.
Journal does each operation in one transaction to keep consistency of the DB and performance.
The exception is when store transaction exceeds 5% of the whole DB mapsize, it is split into multiple ones
and some dirty-chunks-management involves.
Each zone journal has own
usage limit on how much DB space it may occupy. Before hitting the limit,
changesets are stored one-by-one and whole history is linear. While hitting the limit,
the zone is flushed into zone file, and oldest changesets are deleted as needed to free
some space. Actually, twice (again, hardcoded constant) the needed amount is deleted to
prevent too frequent deletes. Further zone file flush is invoked after the journal runs out of deletable
"flushed changesets".
If zone file flush is disabled, instead of flushing the zone, the journal tries to
save space by merging older changesets into one. It works well if the changes rewrite
each other, e.g. periodically changing few zone records, re-signing whole zone...
The diff between zone file and zone is thus preserved, even if journal deletes some
older changesets.
.. _Controlling running daemon:
Daemon controls
......
......@@ -757,6 +757,8 @@ if a zone doesn't have another template specified.
template:
- id: STR
timer-db: STR
journal-db: STR
max-journal-db-size: SIZE
global-module: STR/STR ...
# All zone options (excluding 'template' item)
......@@ -780,6 +782,38 @@ as a relative path to the *default* template :ref:`storage<zone_storage>`.
*Default:* :ref:`storage<zone_storage>`/timers
.. _template_journal-db:
journal-db
----------
Specifies a path of the persistent journal database. The path can be specified
as a relative path to the *default* template :ref:`storage<zone_storage>`.
.. NOTE::
This option is only available in the *default* template.
*Default:* :ref:`storage<zone_storage>`/journal
.. _template_max-journal-db-size:
max-journal-db-size
-------------------
Hard limit for the common journal DB. 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 lower than actual
DB file size.
It is recommended to limit :ref:`max-journal-usage<zone_max-journal-usage>`
per-zone instead of max-journal-size in most cases. Please keep this value
large enough. This value also influences server's usage of virtual memory.
.. NOTE::
This option is only available in the *default* template.
*Default:* 20 GiB
.. _template_global-module:
global-module
......@@ -807,7 +841,6 @@ Definition of zones served by the server.
template: template_id
storage: STR
file: STR
journal: STR
master: remote_id ...
ddns-master: remote_id
notify: remote_id ...
......@@ -816,7 +849,8 @@ Definition of zones served by the server.
disable-any: BOOL
zonefile-sync: TIME
ixfr-from-differences: BOOL
max-journal-size: SIZE
max-journal-usage: SIZE
max-journal-depth: INT
max-zone-size : SIZE
dnssec-signing: BOOL
dnssec-policy: STR
......@@ -874,17 +908,6 @@ A path to the zone file. Non absolute path is relative to
*Default:* :ref:`storage<zone_storage>`/``%s``\ .zone
.. _zone_journal:
journal
-------
A path to the zone journal. Non absolute path is relative to
:ref:`storage<zone_storage>`. The same set of formatters as for
:ref:`file<zone_file>` is supported.
*Default:* :ref:`storage<zone_storage>`/``%s``\ .db
.. _zone_master:
master
......@@ -1008,18 +1031,27 @@ is a master server for the zone.
*Default:* off
.. _zone_max_journal_size:
.. _zone_max-journal-usage:
max-journal-size
----------------
max-journal-usage
-----------------
Maximum size of the journal DB.
Policy how much space in journal DB will the zone's journal occupy.
*Default:* 1 GiB
*Default:* 100 MiB
.. NOTE::
Decreasing this value will lead to discarding
whole journal history of all zones.
Journal DB may grow far above the sum of max-journal-usage across
all zones, because of DB free space fragmentation.
.. _zone_max_journal_depth:
max-journal-depth
-----------------
Maximum history length of journal.
*Default:* 2^64
.. _zone_max_zone_size:
......
......@@ -20,4 +20,3 @@ the server. This section collects manual pages for all provided binaries:
man_knsec3hash
man_knsupdate
man_kzonecheck
man_kjournalprint
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment