doc: highlight potential culrpits of zonefile-load and journal-content

diff --git a/doc/man/knot.conf.5in b/doc/man/knot.conf.5in
index 5490c32057add86056a8f3831876e1fad33f4aa1..2f88f28c6f8603f7f0e80e05bacd646813643a92 100644 (file)
--- a/doc/man/knot.conf.5in
+++ b/doc/man/knot.conf.5in
@@ -2389,6 +2389,14 @@ When \fBdifference\fP is configured and there are no zone contents yet (cold sta
 and no zone contents in the journal), it behaves the same way as \fBwhole\fP\&.
 .sp
 \fIDefault:\fP \fBwhole\fP
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+See Handling, zone file, journal, changes, serials for guidance on
+configuring these and related options to ensure reliable operation.
+.UNINDENT
+.UNINDENT
 .SS journal\-content
 .sp
 Selects how the journal shall be used to store zone and its changes.
@@ -2404,6 +2412,18 @@ Possible values:
 .UNINDENT
 .sp
 \fIDefault:\fP \fBchanges\fP
+.sp
+\fBWARNING:\fP
+.INDENT 0.0
+.INDENT 3.5
+When this option is changed, the journal still contains data respective to
+the previous setting. For example, changing it to \fBnone\fP does not purge
+the journal. Also, changing it from \fBall\fP to \fBchanges\fP
+does not cause the deletion of the zone\-in\-journal and the behaviour of the
+zone loading procedure might be different than expected. It is recommended
+to consider purging the journal when this option is changed.
+.UNINDENT
+.UNINDENT
 .SS journal\-max\-usage
 .sp
 Policy how much space in journal DB will the zone\(aqs journal occupy.

diff --git a/doc/operation.rst b/doc/operation.rst
index 4e3e9772bc79b6a36d9c12939e497350a2c4f00b..f05005c34cdcc0c3659cef06cf1623227ba83070 100644 (file)
--- a/doc/operation.rst
+++ b/doc/operation.rst
@@ -398,7 +398,8 @@ zone transfer, or via the control interface. The user might have filled the
 zone contents initially from a zone file by setting :ref:`zone_zonefile-load` to
 `whole` temporarily.
 It's also a good setup for secondary servers. Anyway, it's recommended to carefully tune
-the journal-size-related options to avoid surprises like the journal getting full.
+the journal-size-related options to avoid surprises like the journal getting full
+(see :ref:`Journal behaviour`).
 
 Example 3
 ---------
@@ -413,8 +414,10 @@ The user can make changes to the zone by editing the zone file, and his pretty z
 is never overwritten or filled with DNSSEC-related autogenerated records – they are
 only stored in the journal.
 
-The zone file's SOA serial must be properly set to a number which is higher than the
-current SOA serial in the zone (not in the zone file) if manually updated!
+.. WARNING::
+   The zone file's SOA serial must be properly set to a number which is higher than the
+   current SOA serial in the zone (not in the zone file) if manually updated!
+   This is important to ensure consistency of the journal and outgoing IXFR.
 
 Example 4
 ---------
@@ -430,6 +433,8 @@ automatically. So the user no longer needs to care about it in the zone file.
 
 However, this requires setting :ref:`zone_journal-content` to `all` so that
 the information about the last real SOA serial is preserved in case of server re-start.
+The sizing of journal limits needs to be taken into consideration
+(see :ref:`Journal behaviour`).
 
 .. _Zone bootstrap:
 

diff --git a/doc/reference.rst b/doc/reference.rst
index b8b30c191939c99b4bcd9fdba1eacffbebf25087..6bc70ae9ced836fe275993be1303b4b314375aaa 100644 (file)
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -2597,6 +2597,10 @@ and no zone contents in the journal), it behaves the same way as ``whole``.
 
 *Default:* ``whole``
 
+.. NOTE::
+   See :ref:`Handling, zone file, journal, changes, serials` for guidance on
+   configuring these and related options to ensure reliable operation.
+
 .. _zone_journal-content:
 
 journal-content
@@ -2612,6 +2616,14 @@ Possible values:
 
 *Default:* ``changes``
 
+.. WARNING::
+   When this option is changed, the journal still contains data respective to
+   the previous setting. For example, changing it to ``none`` does not purge
+   the journal. Also, changing it from ``all`` to ``changes``
+   does not cause the deletion of the zone-in-journal and the behaviour of the
+   zone loading procedure might be different than expected. It is recommended
+   to consider purging the journal when this option is changed.
+
 .. _zone_journal-max-usage:
 
 journal-max-usage