Merge branch '2872-fix-map-zonefile-version-number' into 'main'

Fix crash while loading map zone files generated by BIND >= 9.17.0 && <= 9.17.16

Closes #2872

See merge request isc-projects/bind9!5345

CHANGES

@@ -1,3 +1,9 @@
+5705.	[bug]		Change #5686 altered the internal memory structure
+			of zone databases, but neglected to update the
+			MAPAPI value for map-format zone files. This caused
+			named to attempt to load incompatible map files,
+			triggering an assertion failure on startup. [GL #2872]
+
 5704.	[bug]		TCP keepalive settings were not being applied
 			correctly. [GL #1927]
 

configure.ac

@@ -48,7 +48,7 @@ AC_DEFINE([PACKAGE_SRCID], ["][bind_SRCID]["], [A short hash from git])
 # Whenever releasing a new major release of BIND9, set this value
 # back to 1.0 when releasing the first alpha.  Map files are *never*
 # compatible across major releases.
-AC_DEFINE([MAPAPI], ["2.0"], [BIND 9 MAPAPI Version])
+AC_DEFINE([MAPAPI], ["3.0"], [BIND 9 MAPAPI Version])
 
 bind_CONFIGARGS="${ac_configure_args:-default}"
 AC_DEFINE_UNQUOTED([PACKAGE_CONFIGARGS], ["$bind_CONFIGARGS"], [Either 'defaults' or used ./configure options])

doc/arm/reference.rst

@@ -3561,26 +3561,31 @@ Tuning
    the name server.
 
 ``masterfile-format``
-   This specifies the file format of zone files (see :ref:`zonefile_format`).
-   The default value is ``text``, which
-   is the standard textual representation, except for secondary zones, in
-   which the default value is ``raw``. Files in formats other than
-   ``text`` are typically expected to be generated by the
-   ``named-compilezone`` tool, or dumped by ``named``.
+   This specifies the file format of zone files (see :ref:`zonefile_format`
+   for details).  The default value is ``text``, which is the standard
+   textual representation, except for secondary zones, in which the default
+   value is ``raw``. Files in formats other than ``text`` are typically
+   expected to be generated by the ``named-compilezone`` tool, or dumped by
+   ``named``.
 
-   Note that when a zone file in a format other than ``text`` is
-   loaded, ``named`` may omit some of the checks which are
-   performed for a file in ``text`` format. In particular,
-   ``check-names`` checks do not apply for the ``raw`` format. This
-   means a zone file in the ``raw`` format must be generated with the
-   same check level as that specified in the ``named`` configuration
-   file. Also, ``map`` format files are loaded directly into memory via
-   memory mapping, with only minimal checking.
+   Note that when a zone file in a format other than ``text`` is loaded,
+   ``named`` may omit some of the checks which are performed for a file in
+   ``text`` format. For example, ``check-names`` only applies when loading
+   zones in ``text`` format, and ``max-zone-ttl`` only applies to ``text``
+   and ``raw``.  Zone files in binary formats should be generated with the
+   same check level as that specified in the ``named`` configuration file.
 
-   This statement sets the ``masterfile-format`` for all zones, but can
-   be overridden on a per-zone or per-view basis by including a
-   ``masterfile-format`` statement within the ``zone`` or ``view`` block
-   in the configuration file.
+   ``map`` format files are loaded directly into memory via memory mapping,
+   with only minimal validity checking. Because they are not guaranteed to
+   be compatible from one version of BIND 9 to another, and are not
+   compatible from one system architecture to another, they should be used
+   with caution. See :ref:`zonefile_format` for further discussion.
+
+   When configured in ``options``, this statement sets the
+   ``masterfile-format`` for all zones, but it can be overridden on a
+   per-zone or per-view basis by including a ``masterfile-format``
+   statement within the ``zone`` or ``view`` block in the configuration
+   file.
 
 ``masterfile-style``
    This specifies the formatting of zone files during dump, when the
@@ -6564,32 +6569,51 @@ similar to that used in zone transfers. Since it does not require
 parsing text, load time is significantly reduced.
 
 An even faster alternative is the ``map`` format, which is an image of a
-BIND 9 in-memory zone database; it can be loaded directly
-into memory via the ``mmap()`` function and the zone can begin serving
-queries almost immediately.
+BIND 9 in-memory zone database; it can be loaded directly into memory via
+the ``mmap()`` function and the zone can begin serving queries almost
+immediately.  Because records are not indivdually processed when loading a
+``map`` file, zones using this format cannot be used in ``response-policy``
+statements.
 
-For a primary server, a zone file in ``raw`` or ``map`` format is
-expected to be generated from a textual zone file by the
-``named-compilezone`` command. For a secondary server or a dynamic
-zone, the zone file is automatically generated when ``named`` dumps the zone contents
-after zone transfer or when applying prior updates, if one of these
-formats is specified by the ``masterfile-format`` option.
+For a primary server, a zone file in ``raw`` or ``map`` format is expected
+to be generated from a text zone file by the ``named-compilezone`` command.
+For a secondary server or a dynamic zone, the zone file is automatically
+generated when ``named`` dumps the zone contents after zone transfer or
+when applying prior updates, if one of these formats is specified by the
+``masterfile-format`` option.
 
-If a zone file in a binary format needs manual modification, it first
-must be converted to a textual form by the ``named-compilezone``
-command. Make any necessary modifications to the text file, and
-then convert it to the binary form via the ``named-compilezone``
-command again.
+If a zone file in a binary format needs manual modification, it first must
+be converted to ``text`` format by the ``named-compilezone`` command,
+then converted back after editing.  For example:
 
-Note that ``map`` format is extremely architecture-specific. A ``map``
-file *cannot* be used on a system with different pointer size,
-endianness, or data alignment than the system on which it was generated,
-and should in general be used only inside a single system. While ``raw``
-format uses network byte order and avoids architecture-dependent data
-alignment so that it is as portable as possible, it is also primarily
-expected to be used inside the same single system. To export a zone file
-in either ``raw`` or ``map`` format, or make a portable backup of such a
-file, conversion to ``text`` format is recommended.
+::
+    named-compilezone -f map -F text -o zonefile.text <origin> zonefile.map
+    [edit zonefile.text]
+    named-compilezone -f text -F map -o zonefile.map <origin> zonefile.text
+
+Note that the ``map`` format is highly architecture-specific. A ``map``
+file *cannot* be used on a system with different pointer size, endianness,
+or data alignment than the system on which it was generated, and should in
+general be used only inside a single system.
+
+The ``map`` format is also dependent on the internal memory representation
+of a zone database, which may change from one release of BIND 9 to another.
+``map`` files are never compatible across major releases, and may not be
+compatible across minor releases; any upgrade to BIND 9 may cause ``map``
+files to be rejected when loading. If a ``map`` file is being used for a
+primary zone, it will need to be regenerated from text before restarting
+the server.  If it used for a secondary zone, this is unnecessary; the
+rejection of the file will trigger a retransfer of the zone from the
+primary. (To avoid a spike in traffic upon restart, it may be desirable in
+some cases to convert ``map`` files to ``text`` format using
+``named-compilezone`` before an upgrade, then back to ``map`` format with
+the new version of ``named-compilezone`` afterward.)
+
+``raw`` format uses network byte order and avoids architecture-
+dependent data alignment so that it is as portable as possible, but it is
+still primarily expected to be used inside the same single system. To
+export a zone file in either ``raw`` or ``map`` format, or make a portable
+backup of such a file, conversion to ``text`` format is recommended.
 
 .. _statistics:
 

doc/notes/notes-current.rst

@@ -51,3 +51,10 @@ Bug Fixes
 
 - Migrate a single key to CSK when reconfiguring a zone to make use of
   'dnssec-policy' :gl:`#2857`
+
+- A recent change to the internal memory structure of zone databases
+  inadvertently neglected to update the MAPAPI value for ``map``-format
+  zone files. This caused ``named`` to attempt to load files into memory
+  that were no longer compatible, triggering an assertion failure on
+  startup. The MAPAPI value has now been updated, so ``named`` will
+  reject outdated files when encountering them. :gl:`#2872`