From: Evan Hunt Date: Thu, 26 Aug 2021 18:57:51 +0000 (-0700) Subject: expand map file documentation X-Git-Tag: v9.17.18~15^2~1 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=4b61e744708de8ccf683b141d0b747833872eb3f;p=thirdparty%2Fbind9.git expand map file documentation discuss map file compatibility issues in more detail. --- diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 258a175f548..10420d4a48b 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``. - - 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. - - 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. + 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. 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. + + ``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. - -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. - -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. - -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. +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 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 ``text`` format by the ``named-compilezone`` command, +then converted back after editing. For example: + +:: + 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: