diff --git a/doc/man/knot.conf.5in b/doc/man/knot.conf.5in index 5490c3205..2f88f28c6 100644 --- 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 4e3e9772b..f05005c34 100644 --- 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 b8b30c191..6bc70ae9c 100644 --- 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