BIND Operational Notification: Zone journal (.jnl) file incompatibility,after upgrading to BIND 9.16.12 and 9.17

ISC Security Officer security-officer at isc.org
Mon Feb 22 19:44:25 UTC 2021


To our users --

Following further research, we have revised the Operational Notification
published at the end of last week as we now have an improved
understanding of its likely impact on authoritative BIND servers.
The situation is not quite as serious as originally announced for those
whose server shutdown process ensures that any pending zone file writes
to disk are completed, (that is, the zone files on disk after the name
server has stopped are a full copy of the zones in memory when it was
running).

Cleanly-shutdown servers, when started again following the upgrade,
should have no need to perform a zone roll-forward from the old journal
files.  On restart, named should load all of the zones and start serving
them without error.

Although named will have started and correctly loaded its zone files,
the older incremental transactions in the journal files that were
written prior to the upgrade will still be unusable.  This means that
any zone updates made prior to the upgrade will not be accessible to
named for providing incremental updates (IXFRs).  If requested named
will instead respond with AXFR.

Primary authoritative zone administrators may therefore see no problems
other than an unexpected but short term increase in AXFRs in place of
IXFRs.

New incremental updates, added after restarting and in the new format,
will all be accessible for IXFR and zone recovery.  Over a period of
time and with periodic journal file pruning (per named.conf option
max-journal-size) all incremental updates using the old format will be
removed from the journal files.

Please see the revised Operational Notification below for more detail.

Kind regards

Cathy Almond
ISC Support

-----

Operational Notification: Zone journal (.jnl) file incompatibility
after upgrading to BIND 9.16.12 and 9.17

Posting date:        19 February 2021; updated 22 February 2021
Program impacted:    BIND
Versions affected:   BIND 9.16.12, BIND 9.16.12-S1 (Supported Preview
                     Edition) and versions 9.17.0 -> 9.17.10 of the 9.17
                     development branch.

Description:

   All changes made to a zone using dynamic updates or inbound
   incremental zone update (IXFR) are stored in the zone's journal file.
   This journal (.jnl) file is automatically created and maintained by
   named, and will be used when named is re-started after a shutdown or
   crash to roll-forward (replay) any zone updates that were not yet in
   the version of the zone on disk when named stopped. A zone's journal
   file is also used to provide incremental updates (IXFRs) to other
   servers. DNSSEC-signed zones using inline-signing will also have
   journal files associated with the signed version of the zone.

   In BIND 9.17.0, we introduced the max-ixfr-ratio option, which is a
   percentage representing the ratio of IXFR size to the size of the
   entire zone. This sets the size threshold (expressed as a percentage
   of the size of the full zone) beyond which named chooses to use an
   AXFR response rather than IXFR when answering zone transfer requests.
   This feature has now been back-ported to BIND 9.16, making its debut
   in the 9.16.12 releases.

   Unfortunately, one feature of this change escaped our notice, both
   when writing the release documentation for BIND 9.17.0, and then
   later on, adding the max-ixfr-ratio option to BIND 9.16.12. A small
   change was required to the journal (.jnl) file format in order to
   support the calculation of an IXFR size during its preparation. The
   old format .jnl file is incompatible with the versions of BIND that
   support the new max-ixfr-ratio option.

   When BIND is upgraded to 9.16.12, 9.16.12-S1 or 9.17 (any version)
   and then started with journal (.jnl) files present that were created
   by earlier versions, there may be some problems encountered due to
   the incompatibility.  Several scenarios exist, here are the two that
   we believe are most likely to be encountered:

   - On an authoritative server (primary or secondary), where named was
     shutdown abruptly ('rndc halt' or 'kill -TERM') without flushing
     the in-memory versions of zones to disk first, some zones on disk
     will not reload when named is started after upgrading because their
     .jnl files are incompatible and the latest zone changes cannot be
     applied to bring the zone up to date. See Workarounds below for
     potential routes for recovery of any zones in this state.

     Note:
     --
     The named.conf option 'flush-zones-on-shutdown' changes the
     behaviour of named when receiving SIGTERM.  The default is:
       flush-zones-on-shutdown no;
     --

   - On an authoritative server (primary or secondary), where named was
     shutdown using 'rndc stop' and all recent changes written to the
     zone files first, all zones will load when named is restarted
     following the upgrade (the increment headers can be read during
     the journal file walk-through, and there is no need for named
     to examine the individual change records in the file).  However,
     this server will not be able to respond to IXFR requests for
     changes that were made to its zones prior to the upgrade and will
     send AXFR instead. Eventually (depending on the value of
     'max-journal-size' in 'named.conf'), during regular pruning, the
     increments using the old format will be removed.

Impact:

   This problem can affect BIND servers whose authoritative zones are
   maintained via dynamic updates, or by editing the zone file and
   reloading on a server with option 'ixfr-from-differences' enabled.
   Secondary zones that are maintained using incremental updates (IXFR)
   are similarly at risk. The 'ixfr-from-differences' option may also be
   used in some environments to generate journal files following an
   inbound AXFR.  Use of DNSSEC inline-signing zones adds a further
   layer of complexity to the above scenarios, as both the signed and
   the unsigned versions of the zone have their own journal files.

Workarounds:

   We do not have a tool available to convert the journal files to the
   new format, therefore on upgrading, it is advisable (but depending
   on your circumstances, not absolutely necessary) to start named
   with the old format journal files removed.

   (Options if you have not yet upgraded:)

   1.  Before upgrading, ensure that named is stopped using rndc stop.
   This will ensure that all zones are written to disk during the
   shutdown processing. After named has stopped, delete or relocate all
   the associated .jnl files so that they are not accessed when named is
   restarted. named will generate new .jnl files as needed.

   Warning: Do not stop named using rndc halt before upgrading
   --
     Using rndc halt instead of rndc stop will stop the server
     immediately.  Recent changes made through dynamic update or
     IXFR are not saved to the zone files on disk first (and will
     need to be rolled-forward from the journal files when named is
     restarted; this is what you need to prevent so that you can
     delete them before upgrading).
   --

   2.  For a provisioning/primary authoritative server, you have another
   option for ensuring that the zones are written to disk and that the
   journal files are removed. First, ensure that all dynamic updates are
   paused, then issue command:

      rndc sync -clean

   Then stop named as normal (you should not need to remove the .jnl
   files manually as the 'rndc sync -clean' will have taken care of this
   step).

   (Options if you have already upgraded:)

   3.  If named was stopped before you upgraded using 'rndc stop' and
   you know that this completed successfully, then you may wish to do
   nothing, and wait for the older increments to be removed from your
   .jnl files via periodic pruning.  Alternatively, and for zones that
   update very infrequently, you may prefer to remove or relocate the
   .jnl files.

   4.  If you are not sure if your zone files on disk were updated when
   you stopped named and you have a large number of zones to recover,
   then it may be easiest to back-out the update, start named to do the
   roll-forward and load, and then shutdown again (rndc stop) before
   following option 1. above.

   5.  For zones that are secondary, you can use the rndc utility with
   the retransfer command to obtain a fresh AXFR of the zone from
   another server. This will result in its old journal files being
   deleted and then recreated using the new format following the next
   inbound IXFR.

   6.  If you have only a small number of zones to recover, then you may
   prefer to recover (or build) named-checkzone from your pre-upgrade
   version of BIND and use that to regenerate the zone files from
   the .jnl files.

   For example, to create a new zone file 'example.com.new' for zone
   'example.com' by rolling forward from 'example.com.jnl' and
   'example.com', you would type:

      named-checkzone -jD -o example.com.new example.com example.com

   And then you would:

   - remove files 'example.com.jnl' and 'example.com'
   - rename 'example.com.new' to 'example.com'.

   Note: Use -f and -F options if your zone files are not in text
   format. BIND supports several formats of zone file - check which
   format you need first.

   Hint: Make backup copies of the zone and .jnl files before you run
   named-checkzone.  The named-checkzone utility, when run with the
   -jD  options, will apply the journal file changes to the zone and
   then delete it afterwards. If you make a mistake with the options,
   you may want to start again; having a backup copy in that situation
   is essential!

Solution:

   Code changes to support roll-forward from the older format of .jnl
   files are planned for the March 2021 maintenance releases (due
   17 March 2021) but until then the measures suggested in the
   "Workarounds" section should prevent or resolve post-upgrade zone
   loading problems for Authoritative BIND server operators.

Do you still have questions?
Questions regarding this notification should go to security-
officer at isc.org. To report a new issue, please encrypt your message
using security-officer at isc.org's PGP key which can be found here:
https://www.isc.org/pgpkey/. If you are unable to use encrypted email,
you may also report new issues at: https://www.isc.org/reportbug/.

Note:

   ISC patches only currently supported versions. When possible we
   indicate EOL versions affected. (For current information on which
   versions are actively supported, please see:
   https://www.isc.org/download/.)

ISC Security Vulnerability Disclosure Policy:

   Details of our current security advisory policy and practice can be
   found in the ISC Software Defect and Security Vulnerability
   Disclosure Policy at https://kb.isc.org/docs/aa-00861.

This Knowledgebase article, found at
https://kb.isc.org/v1/docs/operational-notification-zone-journal-jnl-file-incompatibility-after-upgrading-to-bind-91612-and-917
is the complete and official
operational notification document.

Legal Disclaimer:

   Internet Systems Consortium (ISC) is providing this notice on an "AS
   IS" basis. No warranty or guarantee of any kind is expressed in this
   notice and none should be implied. ISC expressly excludes and
   disclaims any warranties regarding this notice or materials referred
   to in this notice, including, without limitation, any implied
   warranty of merchantability, fitness for a particular purpose,
   absence of hidden defects, or of non-infringement. Your use or
   reliance on this notice or materials referred to in this notice is at
   your own risk. ISC may change this notice at any time. A stand-alone
   copy or paraphrase of the text of this document that omits the
   document URL is an uncontrolled copy. Uncontrolled copies may lack
   important information, be out of date, or contain factual errors.


More information about the bind-announce mailing list