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.
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 restarted 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, when 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
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
namedwas shutdown abruptly (
kill -TERM) without flushing the in-memory versions of zones to disk first, some zones on disk will not reload when
namedis 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 the Workarounds section below for potential routes for recovery of any zones in this state.
flush-zones-on-shutdownchanges the behaviour of named when receiving SIGTERM
The default is
- On an authoritative server (primary or secondary), where
namedwas shutdown using
rndc stopand all recent changes written to the zone files first, all zones will load when
namedis restarted following the upgrade (the increment headers can be read during the journal file walk-through, and there is no need for
namedto 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
named.conf), during regular pruning, the increments using the old format will be removed.
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.
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
- Before upgrading, ensure that
namedis stopped using
rndc stop. This will ensure that all zones are written to disk during the shutdown processing. After
namedhas stopped, delete or relocate all the associated .jnl files so that they are not accessed when
namedwill generate new .jnl files as needed.
kill -TERMbefore upgrading
rndc halt or
kill -TERM 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; ideally you need to prevent this scenario from occurring).
- 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 this command:
rndc sync -clean
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
namedwas stopped before you upgraded using
rndc stopand 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 updated very infrequently, you may prefer to remove or relocate the .jnl files.
If you are not sure if your zone files on disk were updated when you stopped
namedand you have a large number of zones to recover, then it may be easiest to back-out the update, start
namedto do the roll-forward and load, and then shutdown again (via
rndc stop) before following option 1. above.
For zones that are secondary, you can use the
rndcutility with the
retransfercommand 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.
If you have only a small number of zones to recover, then you may prefer to recover (or build)
named-checkzonefrom 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, you would type:
named-checkzone -jD -o example.com.new example.com example.com
And then you would:
- remove files
BIND supports several formats of zone file - check which format you need first.
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!
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 email@example.com. To report a new issue, please encrypt your message using firstname.lastname@example.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/.
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.
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.