Commit 6844e3f0 authored by Evan Hunt's avatar Evan Hunt

Add documentation for 'fast' format

parent a732033b
......@@ -239,8 +239,8 @@
<listitem>
<para>
Specify the format of the zone file.
Possible formats are <command>"text"</command> (default)
and <command>"raw"</command>.
Possible formats are <command>"text"</command> (default),
<command>"raw"</command>, and <command>"fast"</command>.
</para>
</listitem>
</varlistentry>
......@@ -255,14 +255,15 @@
contents.
</para>
<para>
Possible formats are <command>"text"</command> (default)
and <command>"raw"</command> or <command>"raw=N"</command>,
which store the zone in a binary format for rapid loading
by <command>named</command>. <command>"raw=N"</command>
specifies the format version of the raw zone file: if N
is 0, the raw file can be read by any version of
<command>named</command>; if N is 1, the file can be read
by release 9.9.0 or higher. The default is 1.
Possible formats are <command>"text"</command> (default),
which is the standard textual representation of the zone,
and <command>"fast"</command>, <command>"raw"</command>,
and <command>"raw=N"</command>, which store the zone in a
binary format for rapid loading by <command>named</command>.
<command>"raw=N"</command> specifies the format version of
the raw zone file: if N is 0, the raw file can be read by
any version of <command>named</command>; if N is 1, the file
can be read by release 9.9.0 or higher; the default is 1.
</para>
</listitem>
</varlistentry>
......@@ -286,9 +287,10 @@
<term>-L <replaceable class="parameter">serial</replaceable></term>
<listitem>
<para>
When compiling a zone to 'raw' format, set the "source serial"
value in the header to the specified serial number. (This is
expected to be used primarily for testing purposes.)
When compiling a zone to "raw" or "fast" format, set the
"source serial" value in the header to the specified serial
number. (This is expected to be used primarily for testing
purposes.)
</para>
</listitem>
</varlistentry>
......
......@@ -166,8 +166,8 @@
(<option>-S</option>) is used, DNSKEY records are also
included. The resulting file can be included in the original
zone file with <command>$INCLUDE</command>. This option
cannot be combined with <option>-O raw</option> or serial
number updating.
cannot be combined with <option>-O raw</option>,
<option>-O fast</option>, or serial number updating.
</para>
</listitem>
</varlistentry>
......@@ -337,8 +337,8 @@
<listitem>
<para>
The format of the input zone file.
Possible formats are <command>"text"</command> (default)
and <command>"raw"</command>.
Possible formats are <command>"text"</command> (default),
<command>"raw"</command>, and <command>"fast"</command>.
This option is primarily intended to be used for dynamic
signed zones so that the dumped zone file in a non-text
format containing updates can be signed directly.
......@@ -376,9 +376,10 @@
<term>-L <replaceable class="parameter">serial</replaceable></term>
<listitem>
<para>
When writing a signed zone to 'raw' format, set the "source serial"
value in the header to the specified serial number. (This is
expected to be used primarily for testing purposes.)
When writing a signed zone to "raw" or "fast" format, set the
"source serial" value in the header to the specified serial
number. (This is expected to be used primarily for testing
purposes.)
</para>
</listitem>
</varlistentry>
......@@ -446,16 +447,17 @@
<listitem>
<para>
The format of the output file containing the signed zone.
Possible formats are <command>"text"</command> (default)
Possible formats are <command>"text"</command> (default),
which is the standard textual representation of the zone;
<command>"full"</command>, which is text output in a
format suitable for processing by external scripts,
and <command>"raw"</command> or <command>"raw=N"</command>,
which store the zone in a binary format for rapid loading
by <command>named</command>. <command>"raw=N"</command>
specifies the format version of the raw zone file: if N
is 0, the raw file can be read by any version of
<command>named</command>; if N is 1, the file can be
read by release 9.9.0 or higher. The default is 1.
format suitable for processing by external scripts;
and <command>"fast"</command>, <command>"raw"</command>,
and <command>"raw=N"</command>, which store the zone in
binary formats for rapid loading by <command>named</command>.
<command>"raw=N"</command> specifies the format version of
the raw zone file: if N is 0, the raw file can be read by
any version of <command>named</command>; if N is 1, the file
can be read by release 9.9.0 or higher; the default is 1.
</para>
</listitem>
</varlistentry>
......
......@@ -318,7 +318,7 @@ options {
update-check-ksk <replaceable>boolean</replaceable>;
dnssec-dnskey-kskonly <replaceable>boolean</replaceable>;
masterfile-format ( text | raw );
masterfile-format ( text | raw | fast );
notify <replaceable>notifytype</replaceable>;
notify-source ( <replaceable>ipv4_address</replaceable> | * ) <optional> port ( <replaceable>integer</replaceable> | * ) </optional>;
notify-source-v6 ( <replaceable>ipv6_address</replaceable> | * ) <optional> port ( <replaceable>integer</replaceable> | * ) </optional>;
......@@ -506,7 +506,7 @@ view <replaceable>string</replaceable> <replaceable>optional_class</replaceable>
update-check-ksk <replaceable>boolean</replaceable>;
dnssec-dnskey-kskonly <replaceable>boolean</replaceable>;
masterfile-format ( text | raw );
masterfile-format ( text | raw | fast );
notify <replaceable>notifytype</replaceable>;
notify-source ( <replaceable>ipv4_address</replaceable> | * ) <optional> port ( <replaceable>integer</replaceable> | * ) </optional>;
notify-source-v6 ( <replaceable>ipv6_address</replaceable> | * ) <optional> port ( <replaceable>integer</replaceable> | * ) </optional>;
......@@ -603,7 +603,7 @@ zone <replaceable>string</replaceable> <replaceable>optional_class</replaceable>
update-check-ksk <replaceable>boolean</replaceable>;
dnssec-dnskey-kskonly <replaceable>boolean</replaceable>;
masterfile-format ( text | raw );
masterfile-format ( text | raw | fast );
notify <replaceable>notifytype</replaceable>;
notify-source ( <replaceable>ipv4_address</replaceable> | * ) <optional> port ( <replaceable>integer</replaceable> | * ) </optional>;
notify-source-v6 ( <replaceable>ipv6_address</replaceable> | * ) <optional> port ( <replaceable>integer</replaceable> | * ) </optional>;
......
......@@ -5325,7 +5325,8 @@ badresp:1,adberr:0,findfail:0,valfail:0]
<optional> max-acache-size <replaceable>size_spec</replaceable> ; </optional>
<optional> clients-per-query <replaceable>number</replaceable> ; </optional>
<optional> max-clients-per-query <replaceable>number</replaceable> ; </optional>
<optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>) ; </optional>
<optional> masterfile-format
(<constant>text</constant>|<constant>raw</constant>|<constant>fast</constant>) ; </optional>
<optional> empty-server <replaceable>name</replaceable> ; </optional>
<optional> empty-contact <replaceable>name</replaceable> ; </optional>
<optional> empty-zones-enable <replaceable>yes_or_no</replaceable> ; </optional>
......@@ -8958,7 +8959,12 @@ avoid-v6-udp-ports { 40000; range 50000 60000; };
a zone file in the <constant>raw</constant> format
must be generated with the same check level as that
specified in the <command>named</command> configuration
file. This statement sets the
file. Also, <constant>fast</constant> format files are
loaded directly into memory via memory mapping, with only
minimal checking.
</para>
<para>
This statement sets the
<command>masterfile-format</command> for all zones,
but can be overridden on a per-zone or per-view basis
by including a <command>masterfile-format</command>
......@@ -10371,7 +10377,7 @@ view "external" {
<optional> check-integrity <replaceable>yes_or_no</replaceable> ; </optional>
<optional> dialup <replaceable>dialup_option</replaceable> ; </optional>
<optional> file <replaceable>string</replaceable> ; </optional>
<optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>) ; </optional>
<optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>|<constant>fast</constant>) ; </optional>
<optional> journal <replaceable>string</replaceable> ; </optional>
<optional> max-journal-size <replaceable>size_spec</replaceable>; </optional>
<optional> forward (<constant>only</constant>|<constant>first</constant>) ; </optional>
......@@ -10426,7 +10432,7 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea
<optional> check-names (<constant>warn</constant>|<constant>fail</constant>|<constant>ignore</constant>) ; </optional>
<optional> dialup <replaceable>dialup_option</replaceable> ; </optional>
<optional> file <replaceable>string</replaceable> ; </optional>
<optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>) ; </optional>
<optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>|<constant>fast</constant>) ; </optional>
<optional> journal <replaceable>string</replaceable> ; </optional>
<optional> max-journal-size <replaceable>size_spec</replaceable>; </optional>
<optional> forward (<constant>only</constant>|<constant>first</constant>) ; </optional>
......@@ -10480,7 +10486,7 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea
<optional> dialup <replaceable>dialup_option</replaceable> ; </optional>
<optional> delegation-only <replaceable>yes_or_no</replaceable> ; </optional>
<optional> file <replaceable>string</replaceable> ; </optional>
<optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>) ; </optional>
<optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>|<constant>fast</constant>) ; </optional>
<optional> forward (<constant>only</constant>|<constant>first</constant>) ; </optional>
<optional> forwarders { <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional>
<optional> masters <optional>port <replaceable>ip_port</replaceable></optional> { ( <replaceable>masters_list</replaceable> | <replaceable>ip_addr</replaceable>
......@@ -10523,7 +10529,7 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea
zone <replaceable>"."</replaceable> <optional><replaceable>class</replaceable></optional> {
type redirect;
file <replaceable>string</replaceable> ;
<optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>) ; </optional>
<optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>|<constant>fast</constant>) ; </optional>
<optional> allow-query { <replaceable>address_match_list</replaceable> }; </optional>
};
......@@ -13601,18 +13607,28 @@ HOST-127.EXAMPLE. MX 0 .
<para>
In addition to the standard textual format, BIND 9
supports the ability to read or dump to zone files in
other formats. The <constant>raw</constant> format is
currently available as an additional format. It is a
binary format representing BIND 9's internal data
structure directly, thereby remarkably improving the
loading time.
other formats.
</para>
<para>
The <constant>raw</constant> format is
a binary representation of zone data in a manner similar
to that used in zone transfers. Since it does not require
parsing text, load time is significantly reduced.
</para>
<para>
An even faster alternative is the <constant>fast</constant>
format, which is an image of a <acronym>BIND</acronym> 9
in-memory zone database; it is capable of being loaded
directly into memory via the <command>mmap()</command>
function; the zone can begin serving queries almost
immediately.
</para>
<para>
For a primary server, a zone file in the
<constant>raw</constant> format is expected to be
generated from a textual zone file by the
<command>named-compilezone</command> command. For a
secondary server or for a dynamic zone, it is automatically
For a primary server, a zone file in
<constant>raw</constant> or <constant>fast</constant>
format is expected to be generated from a textual zone
file by the <command>named-compilezone</command> command.
For a secondary server or for a dynamic zone, it is automatically
generated (if this format is specified by the
<command>masterfile-format</command> option) when
<command>named</command> dumps the zone contents after
......@@ -13627,14 +13643,21 @@ HOST-127.EXAMPLE. MX 0 .
<command>named-compilezone</command> command again.
</para>
<para>
Although the <constant>raw</constant> format uses the
network byte order and avoids architecture-dependent
data alignment so that it is as much portable as
possible, it is primarily expected to be used inside
the same single system. In order to export a zone
file in the <constant>raw</constant> format or make a
portable backup of the file, it is recommended to
convert the file to the standard textual representation.
Note that <command>fast</command> format is extremely
architecture-specific. A <constant>fast</constant>
file <emphasis>cannot</emphasis> 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 <constant>raw</constant> 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 <constant>raw</constant> or
<constant>fast</constant> format, or make a
portable backup of such a file, conversion to
<constant>text</constant> format is recommended.
</para>
</sect2>
</sect1>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment