Commit 935c9185 authored by JINMEI Tatuya's avatar JINMEI Tatuya
Browse files

[2380] updated man page.

parent 0785c84f
......@@ -2,7 +2,7 @@
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2010 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC")
-
- Permission to use, copy, modify, and/or distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
......@@ -20,7 +20,7 @@
<refentry>
<refentryinfo>
<date>March 26, 2012</date>
<date>December 15, 2012</date>
</refentryinfo>
<refmeta>
......@@ -36,7 +36,7 @@
<docinfo>
<copyright>
<year>2010</year>
<year>2012</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
</docinfo>
......@@ -44,9 +44,13 @@
<refsynopsisdiv>
<cmdsynopsis>
<command>b10-loadzone</command>
<arg><option>-d <replaceable class="parameter">database</replaceable></option></arg>
<arg><option>-o <replaceable class="parameter">origin</replaceable></option></arg>
<arg choice="req">filename</arg>
<arg><option>-d <replaceable class="parameter">debug_level</replaceable></option></arg>
<arg><option>-i <replaceable class="parameter">report_interval</replaceable></option></arg>
<arg><option>-t <replaceable class="parameter">datasrc_type</replaceable></option></arg>
<arg><option>-C <replaceable class="parameter">zone_class</replaceable></option></arg>
<arg choice="req">-c <replaceable class="parameter">datasrc_config</replaceable></arg>
<arg choice="req">zone name</arg>
<arg choice="req">zone file</arg>
</cmdsynopsis>
</refsynopsisdiv>
......@@ -66,20 +70,38 @@
$ORIGIN is followed by a domain name, and sets the the origin
that will be used for relative domain names in subsequent records.
$INCLUDE is followed by a filename to load.
<!-- TODO: and optionally a
domain name used to set the relative domain name origin. -->
The previous origin is restored after the file is included.
<!-- the current domain name is also restored -->
$TTL is followed by a time-to-live value which is used
by any following records that don't specify a TTL.
</para>
<para>
If the specified zone does not exist in the specified data
source, <command>b10-loadzone</command> will first create a
new empty zone in the data source, then fill it with the RRs
given in the specified master zone file. In this case, if
loading fails for some reason, the creation of the new zone
is also canceled.
<note><simpara>
Due to an implementation limitation, the current version
does not make the zone creation and subsequent loading an
atomic operation; an empty zone will be visible and used by
other application (e.g., the <command>b10-auth</command>
authoritative server) while loading. If this is an issue,
make sure the initial loading of a new zone is done before
starting other BIND 10 applications.
</simpara></note>
</para>
<para>
When re-loading an existing zone, the prior version is completely
removed. While the new version of the zone is being loaded, the old
version remains accessible to queries. After the new version is
completely loaded, the old version is swapped out and replaced
with the new one in a single operation.
with the new one in a single operation. If loading fails for
some reason, the loaded RRs will be effectively deleted, and the
old version will still remain accessible for other applications.
</para>
</refsect1>
......@@ -90,19 +112,77 @@
<variablelist>
<varlistentry>
<term>-d <replaceable class="parameter">database</replaceable> </term>
<term>-d <replaceable class="parameter">debug_level</replaceable> </term>
<listitem><para>
Defines the filename for the database.
The default is
<filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>.
<!-- TODO: fix filename -->
Enable dumping debug level logging with the specified
level. By default, only log messages at the severity of
informational or higher levels will be produced.
</para></listitem>
</varlistentry>
<varlistentry>
<term>-o <replaceable class="parameter">origin</replaceable></term>
<term>-i <replaceable class="parameter">report_interval</replaceable></term>
<listitem><para>
Defines the default origin for the zone file records.
Specifies the interval of status update by the number of RRs
loaded in the interval.
The <command>b10-loadzone</command> tool periodically
reports the progress of loading with the total number of
loaded RRs and elapsed time. This option specifies the
interval of the reports. If set to 0, status reports will
be suppressed. The default is 10,000.
</para></listitem>
</varlistentry>
<varlistentry>
<term>-t <replaceable class="parameter">datasrc_type</replaceable></term>
<listitem><para>
Specifies the type of data source to store the zone.
Currently, only the "sqlite3" type is supported (which is
the default of this option), which means the SQLite3 data
source.
</para></listitem>
</varlistentry>
<varlistentry>
<term>-C <replaceable class="parameter">zone_class</replaceable></term>
<listitem><para>
Specifies the RR class of the zone.
Currently, only class IN is supported (which is the default
of this option) due to limitation of the underlying data
source implementation.
</para></listitem>
</varlistentry>
<varlistentry>
<term>-c <replaceable class="parameter">datasrc_config</replaceable></term>
<listitem><para>
Specifies configuration of the data source in the JSON
format. The configuration contents depend on the type of
the data source, and that's the same as what would be
specified for the BIND 10 servers (see the data source
configuration section of the BIND 10 guide). For example,
for an SQLite3 data source, it would look like
'{"database_file": "path-to-sqlite3-db-file"}'.
<note>
<simpara>This option currently cannot be omitted. In a future
version it will be possible to retrieve the configuration from
the BIND 10 server configuration (if it exists).
</simpara></note>
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">zone name</replaceable></term>
<listitem><para>
The name of the zone to create or update. This must be a valid DNS
domain name.
</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">zone file</replaceable></term>
<listitem><para>
A path to the master zone file to be loaded.
</para></listitem>
</varlistentry>
......@@ -131,8 +211,30 @@
<refsect1>
<title>AUTHORS</title>
<para>
The <command>b10-loadzone</command> tool was initial written
by Evan Hunt of ISC.
A prior version of the <command>b10-loadzone</command> tool was
written by Evan Hunt of ISC.
The new version that this manual refers to was rewritten from
the scratch by the BIND 10 development team in around December 2012.
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
As of the initial implementation, the underlying library that
this tool uses does not fully validate the loaded zone; for
example, loading will succeed even if it doesn't have the SOA or
NS record at its origin name. Such checks will be implemented
in a near future version, but until then, the
<command>b10-loadzone</command> performs the existence of the
SOA and NS records by itself. However, <command>b10-loadzone</command>
only warns about it, and does not cancel the load itself.
If this warning message is produced, it's the user's
responsibility to fix the errors and reload it. When the
library is updated with the post load checks, it will be more
sophisticated and the such zone won't be successfully loaded.
There are some other issues noted in the DESCRIPTION section.
</para>
</refsect1>
</refentry><!--
......
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