Commit 318f664d authored by Jeremy C. Reed's avatar Jeremy C. Reed

For Trac ticket #341

Begin to document zonemgr secondary manager.
Not complete and needs more review.
Note this includes a various minor cleanup in these documents too.

I will generate the docs and commit them next.


git-svn-id: svn://bind10.isc.org/svn/bind10/trunk@2951 e5f2f494-b856-4b98-b285-d166d9295462
parents c11617b7 eb344309
95. [doc] jreed
Add b10-zonemgr manual page. Update other docs to introduce
this secondary manager. (Trac #341, svn r2951)
95. [bug] jreed
bin/xfrout and bin/zonemgr: Fixed some stderr output.
(Trac #342, svn r2949)
......
......@@ -42,7 +42,7 @@
<note>
<para>
BIND 10, at this time, does not provide an recursive
BIND 10, at this time, does not provide a recursive
DNS server. It does provide a EDNS0- and DNSSEC-capable
authoritative DNS server.
</para>
......@@ -74,9 +74,9 @@
For this development prototype release, the only supported
data source backend is SQLite3. The authoritative server
requires SQLite 3.3.9 or newer.
The <command>b10-xfrin</command> and <command>b10-xfrout</command>
modules require the libpython3 library and the Python
_sqlite3.so module.
The <command>b10-xfrin</command>, <command>b10-xfrout</command>,
and <command>b10-zonemgr</command> modules require the
libpython3 library and the Python _sqlite3.so module.
</para></note>
<!-- TODO: this will change ... -->
......@@ -165,6 +165,15 @@
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-zonemgr</command> &mdash;
Secondary manager.
This process keeps track of timers and other
necessary information for BIND 10 to act as a slave server.
</simpara>
</listitem>
</itemizedlist>
</para>
......@@ -650,8 +659,9 @@ var/
The <command>bind10</command> master process will also start up
<command>b10-cmdctl</command> for admins to communicate with the
system, <command>b10-auth</command> for Authoritative DNS service,
<command>b10-xfrin</command> for inbound DNS zone transfers.
and <command>b10-xfrout</command> for outbound DNS zone transfers.
<command>b10-xfrin</command> for inbound DNS zone transfers,
<command>b10-xfrout</command> for outbound DNS zone transfers,
and <command>b10-zonemgr</command> for secondary service.
</para>
<section id="start">
......@@ -1173,14 +1183,14 @@ TODO
transfer. When received, it is stored in the BIND 10
data store, and its records can be served by
<command>b10-auth</command>.
This allows the BIND 10 server to provide
<quote>secondary</quote> service.
In combination with <command>b10-zonemgr</command> (for
automated SOA checks), this allows the BIND 10 server to
provide <quote>secondary</quote> service.
</para>
<note><simpara>
The current development release of BIND 10 only supports
AXFR. (IXFR is not supported.)
It also does not yet support automated SOA checks.
</simpara></note>
<para>
......@@ -1204,12 +1214,13 @@ TODO
sends the zone.
This is used to provide master DNS service to share zones
to secondary name servers.
The <command>b10-xfrout</command> is also used to send
NOTIFY messages to slaves.
</para>
<note><simpara>
The current development release of BIND 10 only supports
AXFR. (IXFR is not supported.)
It also does not yet support NOTIFY.
Access control is not yet provided.
</simpara></note>
......@@ -1226,6 +1237,31 @@ what is XfroutClient xfr_client??
</chapter>
<chapter id="zonemgr">
<title>Secondary Manager</title>
<para>
The <command>b10-zonemgr</command> process is started by
<command>bind10</command>.
It keeps track of SOA refresh, retry, and expire timers
and other details for BIND 10 to perform as a slave.
When the <command>b10-auth</command> authoritative DNS server
receives a NOTIFY message, <command>b10-zonemgr</command>
may tell <command>b10-xfrin</command> to do a refresh
to start an inbound zone transfer.
The secondary manager resets its counters when a new zone is
transferred in.
</para>
<note><simpara>
Access control (such as allowing notifies) is not yet provided.
The primary/secondary service is not yet complete.
</simpara></note>
<!-- TODO: lots to describe for zonemgr -->
</chapter>
<!-- TODO: how to help: run unit tests, join lists, review trac tickets -->
<!-- <index> <title>Index</title> </index> -->
......
......@@ -200,6 +200,9 @@
<citerefentry>
<refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
......
......@@ -189,6 +189,12 @@
<citerefentry>
<refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>b10-xfrout</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>BIND 10 Guide</citetitle>.
</para>
</refsect1>
......
......@@ -21,7 +21,7 @@
<refentry>
<refentryinfo>
<date>March 17, 2010</date>
<date>September 8, 2010</date>
</refentryinfo>
<refmeta>
......@@ -68,7 +68,6 @@
</simpara></note>
<para>
<!-- TODO: does it really use msgq? what for? -->
This daemon communicates with BIND 10 over a
<citerefentry><refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum></citerefentry>
C-Channel connection. If this connection is not established,
......@@ -85,40 +84,83 @@
<refsect1>
<title>CONFIGURATION AND COMMANDS</title>
<para>
The configurable setting is <varname>transfers-in</varname>
which defines the maximum number of inbound zone transfers
The configurable settings are:
</para>
<para><varname>master_addr</varname>
<!-- TODO: how can there be a single setting for this? -->
The default is 127.0.0.1.
</para>
<para><varname>master_port</varname>
<!-- TODO: what if custom is needed per zone? -->
The default is 53.
</para>
<para><varname>transfers-in</varname>
defines the maximum number of inbound zone transfers
that can run concurrently. The default is 10.
</para>
<!-- TODO: formating -->
<!-- TODO: refresh is code but not in spec -->
<!-- schedule immediate maintenance for a zone(check soa serial ) -->
<para>
The configuration commands are:
</para>
<para>
<command>notify</command> is sent by
<citerefentry><refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>
when a DNS NOTIFY message is received to initiate a zone
transfer.
<!-- TODO: document that zonemgr or xfrin checks if it needs to or not -->
This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
</para>
<para>
<command>shutdown</command> stops all incoming zone transfers
and exits <command>b10-xfrin</command>. (Note that the BIND 10
boss process will restart this service.)
<command>refresh</command> triggers the transfer in for
a single zone.
It is the same as <command>retransfer</command> except it
checks the SOA serial first.
<!-- TODO more detail -->
This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
<!-- TODO: refresh is code but not in spec, see trac ticket #328 -->
</para>
<para>
<command>refresh_from_zonemgr</command> is sent by
<citerefentry><refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>
according to the SOA's REFRESH time
to tell <command>b10-xfrin</command> that the zone needs to do
a zone refresh.
This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
</para>
<para>
<command>retransfer</command> triggers the transfer in for
a single zone without checking the zone's serial number.
It has the following arguments: <varname>zone_name</varname>
to define the zone to request and <varname>master</varname>
to define the IP address of the authoritative server to
transfer from.
to define the zone to request,
<varname>zone_class</varname> to define the class (defaults to
<quote>IN</quote>),
<varname>master</varname> to define the IP address of
the authoritative server to transfer from,
and <varname>port</varname> to define the port number on the
authoritative server (defaults to 53).
<!-- TODO: note: not documenting db_file since that will be removed. -->
</para>
<!-- TODO: later hostname for master? -->
<para>
<command>shutdown</command> stops all incoming zone transfers
and exits <command>b10-xfrin</command>. (Note that the BIND 10
boss process will restart this service.)
</para>
<!-- TODO:
add a usage example of xfrin -->
<!-- TODO:
port (defaults to 53)
db_file (defaults to zone.sqlite3) --> <!-- TODO: fix this -->
<!-- TODO:
later it will can be triggered by :
......@@ -181,6 +223,9 @@ operation
<citerefentry>
<refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
......
......@@ -21,7 +21,7 @@
<refentry>
<refentryinfo>
<date>April 20, 2010</date>
<date>September 8, 2010</date>
</refentryinfo>
<refmeta>
......@@ -54,6 +54,7 @@
<title>DESCRIPTION</title>
<para>The <command>b10-xfrout</command> daemon provides the BIND 10
outgoing DNS zone transfer service.
It is also used to send outgoing NOTIFY messages.
Normally it is started by the
<citerefentry><refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum></citerefentry>
boss process.
......@@ -97,6 +98,7 @@
defines the path to the SQLite3 data store file.
The default is
<filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>.
<!-- TODO: db_file will be removed -->
</para>
<para>
<varname>transfers_out</varname>
......@@ -104,6 +106,9 @@
that can run concurrently. The default is 10.
</para>
<!-- TODO: log configurations not documented yet in here. jreed
has some but waiting on decisions ... -->
<note><simpara>
This prototype version uses SQLite3 as its data source backend.
Future versions will be configurable, supporting multiple
......@@ -112,7 +117,7 @@
<!-- TODO: formating -->
<para>
The configuration command is:
The configuration commands are:
</para>
<para>
<command>shutdown</command> stops all outbound zone transfers
......@@ -120,6 +125,16 @@
boss process will restart this service.)
</para>
<para>
<command>zone_new_data_ready</command> is sent from
<citerefentry><refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum></citerefentry>
to indicate that the zone transferred in successfully.
This triggers <command>b10-xfrout</command> to send NOTIFY
message(s).
This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
</para>
</refsect1>
<!--
......@@ -160,6 +175,9 @@
<citerefentry>
<refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
......@@ -170,8 +188,8 @@
<refsect1>
<title>HISTORY</title>
<para>
The <command>b10-xfrout</command> daemon was implemented in March 2010
by Zhang Likun of CNNIC for the ISC BIND 10 project.
The <command>b10-xfrout</command> daemon was first implemented
in March 2010 by Zhang Likun of CNNIC for the ISC BIND 10 project.
</para>
</refsect1>
</refentry><!--
......
......@@ -9,6 +9,16 @@ b10_zonemgr_DATA = zonemgr.spec
CLEANFILES = b10-zonemgr zonemgr.pyc zonemgr.spec
man_MANS = b10-zonemgr.8
EXTRA_DIST = $(man_MANS) b10-zonemgr.xml
if ENABLE_MAN
b10-zonemgr.8: b10-zonemgr.xml
xsltproc --novalid --xinclude --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $(srcdir)/b10-zonemgr.xml
endif
zonemgr.spec: zonemgr.spec.pre
$(SED) -e "s|@@LOCALSTATEDIR@@|$(localstatedir)|" zonemgr.spec.pre >$@
......
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY mdash "&#8212;">]>
<!--
- Copyright (C) 2010 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
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id$ -->
<refentry>
<refentryinfo>
<date>September 8, 2010</date>
</refentryinfo>
<refmeta>
<refentrytitle>b10-zonemgr</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo>BIND10</refmiscinfo>
</refmeta>
<refnamediv>
<refname>b10-zonemgr</refname>
<refpurpose>BIND 10 Secondary zone manager</refpurpose>
</refnamediv>
<docinfo>
<copyright>
<year>2010</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
</docinfo>
<refsynopsisdiv>
<cmdsynopsis>
<command>b10-zonemgr</command>
<arg><option>-v</option></arg>
<arg><option>--verbose</option></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>The <command>b10-zonemgr</command> daemon, also known
as the BIND 10 secondary manager, keeps track of timers
and other information necessary for BIND 10 to act as a DNS slave.
Normally it is started by the
<citerefentry><refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum></citerefentry>
boss process.
</para>
<para>
This daemon communicates with BIND 10 over a
<citerefentry><refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum></citerefentry>
C-Channel connection. If this connection is not established,
<command>b10-zonemgr</command> will exit.
<!-- TODO what if connection closes later, will b10-zonemgr exit? -->
</para>
<para>
<command>b10-zonemgr</command> receives its configurations from
<citerefentry><refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
<!--
self._send_command(XFRIN_MODULE_NAME, ZONE_NOTIFY_COMMAND, param)
self._clear_zone_notifier_master(zone_name_class)
# Send refresh command to xfrin module
else:
param = {"zone_name" : zone_name_class[0],
"zone_class" : zone_name_class[1]
}
self._send_command(XFRIN_MODULE_NAME, ZONE_REFRESH_COMMAND, param)
-->
</refsect1>
<refsect1>
<title>CONFIGURATION AND COMMANDS</title>
<!--
<para>
The configurable settings are:
</para>
-->
<!-- TODO: formating -->
<para>
The configuration commands are:
</para>
<para>
<command>notify</command> (sent by
<citerefentry><refentrytitle>b10-auth</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
tells <command>b10-zonemgr</command>
the zone name and class, and the IP address for the master
(source of the NOTIFY message).
This will set the zone's refresh time to now.
<!-- TODO reword this -->
This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
</para>
<para>
<command>shutdown</command> exits <command>b10-zonemgr</command>.
(Note that the BIND 10 boss process will restart this service.)
</para>
<para>
<command>zone_new_data_ready</command> is sent from
<citerefentry><refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum></citerefentry>
to indicate that the zone transferred in successfully.
This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
</para>
<para>
<command>zone_xfrin_failed</command> is sent from
<citerefentry><refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum></citerefentry>
to indicate a failure (such as a transfer-in was incomplete).
The refresh timer for the zone is reset.
<!--
"""Set zone next refresh time after zone refresh fail.
now + retry*3/4 <= next_refresh_time <= now + retry
-->
This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
</para>
</refsect1>
<!--
<refsect1>
<title>OPTIONS</title>
<para>The arguments are as follows:</para>
<variablelist>
<varlistentry>
<term><option></option></term>
<listitem><para>
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
-->
<!--
<refsect1>
<title>FILES</title>
<para>
<filename>/tmp/auth_xfrout_conn</filename>
</para>
</refsect1>
-->
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>b10-auth</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>b10-xfrout</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citetitle>BIND 10 Guide</citetitle>.
</para>
</refsect1>
<refsect1>
<title>HISTORY</title>
<para>
The <command>b10-zonemgr</command> daemon was designed in July 2010
by CNNIC for the ISC BIND 10 project.
</para>
</refsect1>
</refentry><!--
- Local variables:
- mode: sgml
- End:
-->
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