From 4a68c7be225ddc3443d647bb8257278c1fdb4da8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 19 Aug 2021 19:54:44 +0200 Subject: [PATCH 1/3] increase MAPAPI bump the map zonefile version number to avoid an assertion failure when loading map files from versions of BIND prior to the most recent change to the in-memory structure of zone databases. --- configure.ac | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configure.ac b/configure.ac index 777a879237..39168fc072 100644 --- a/configure.ac +++ b/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]) From 4b61e744708de8ccf683b141d0b747833872eb3f Mon Sep 17 00:00:00 2001 From: Evan Hunt Date: Thu, 26 Aug 2021 11:57:51 -0700 Subject: [PATCH 2/3] expand map file documentation discuss map file compatibility issues in more detail. --- doc/arm/reference.rst | 106 ++++++++++++++++++++++++++---------------- 1 file changed, 65 insertions(+), 41 deletions(-) diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 258a175f54..10420d4a48 100644 --- a/doc/arm/reference.rst +++ b/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 zonefile.map + [edit zonefile.text] + named-compilezone -f text -F map -o zonefile.map 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: From 351ed777c252c845b63ab36027c5f1ceadff65f4 Mon Sep 17 00:00:00 2001 From: Evan Hunt Date: Thu, 26 Aug 2021 11:22:44 -0700 Subject: [PATCH 3/3] CHANGES, release note --- CHANGES | 6 ++++++ doc/notes/notes-current.rst | 7 +++++++ 2 files changed, 13 insertions(+) diff --git a/CHANGES b/CHANGES index ad9297a034..45f5588b25 100644 --- a/CHANGES +++ b/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] diff --git a/doc/notes/notes-current.rst b/doc/notes/notes-current.rst index 6900b3b1da..9543909b7c 100644 --- a/doc/notes/notes-current.rst +++ b/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`