Commit 8118f8e4 authored by JINMEI Tatuya's avatar JINMEI Tatuya
Browse files

[master] Merge branch 'trac2911'

Fixed Conflicts:
	ChangeLog
parents 7e575b70 1f72551a
......@@ -2725,11 +2725,8 @@ TODO
<para>
The <command>b10-xfrin</command> process supports both AXFR and
IXFR. Due to some implementation limitations of the current
development release, however, it only tries AXFR by default,
and care should be taken to enable IXFR.
IXFR.
</para>
<!-- TODO: http://bind10.isc.org/ticket/1279 -->
<section>
<title>Configuration for Incoming Zone Transfers</title>
......@@ -2763,34 +2760,82 @@ TODO
&gt; <userinput>config set Xfrin/zones[0]/tsig_key "<option>example.key</option>"</userinput>
</section>
<section>
<title>Enabling IXFR</title>
<para>
As noted above, <command>b10-xfrin</command> uses AXFR for
zone transfers by default. To enable IXFR for zone transfers
for a particular zone, set the <varname>use_ixfr</varname>
configuration parameter to <quote>true</quote>.
In the above example of configuration sequence, you'll need
to add the following before performing <userinput>commit</userinput>:
<screen>&gt; <userinput>config set Xfrin/zones[0]/use_ixfr true</userinput></screen>
</para>
<section id="request_ixfr">
<title>Control the use of IXFR</title>
<para>
By default, <command>b10-xfrin</command> uses IXFR for
transferring zones specified in
the <varname>Xfrin/zones</varname> list of the configuration,
unless it doesn't know the current SOA serial of the zone
(including the case where the zone has never transferred or
locally loaded), in which case it automatically uses AXFR.
If the attempt of IXFR fails, <command>b10-xfrin</command>
automatically retries the transfer using AXFR.
In general, this works for any master server implementations
including those that don't support IXFR and in any local state
of the zone. So there should normally be no need to configure
on whether to use IXFR.
</para>
<para>
In some cases, however, it may be desirable to specify how and
whether to use IXFR and AXFR.
The <varname>request_ixfr</varname> configuration item under
<varname>Xfrin/zones</varname> can be used to control such
policies.
It can take the following values.
</para>
<variablelist>
<varlistentry>
<term>yes</term>
<listitem>
<simpara>
This is the default behavior as described above.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>no</term>
<listitem>
<simpara>
Only use AXFR. Note that this value normally shouldn't
be needed thanks to the automatic fallback from IXFR to IXFR.
A possible case where this value needs to be used is
that the master server has a bug and crashes if it
receives an IXFR request.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>only</term>
<listitem>
<simpara>
Only use IXFR except when the current SOA serial is not
known.
This value has a severe drawback, that is, if the master
server does not support IXFR zone transfers never
succeed (except for the very first one, which will use AXFR),
and the zone will eventually expire.
Therefore it should not be used in general.
Still, in some special cases the use of this value may
make sense. For example, if the operator is sure that
the master server supports IXFR and the zone is very
large, they may want to avoid falling back to AXFR as
it can be more expensive.
</simpara>
</listitem>
</varlistentry>
</variablelist>
<note>
<simpara>
There used to be a boolean configuration item named
<varname>use_ixfr</varname>.
It was deprecated for the finer control described above.
The <varname>request_ixfr</varname> item should be used instead.
</simpara>
</note>
<!-- TODO: http://bind10.isc.org/ticket/1279 -->
<note><simpara>
One reason why IXFR is disabled by default in the current
release is because it does not support automatic fallback from IXFR to
AXFR when it encounters a primary server that doesn't support
outbound IXFR (and, not many existing implementations support
it). Another, related reason is that it does not use AXFR even
if it has no knowledge about the zone (like at the very first
time the secondary server is set up). IXFR requires the
"current version" of the zone, so obviously it doesn't work
in this situation and AXFR is the only workable choice.
The current release of <command>b10-xfrin</command> does not
make this selection automatically.
These features will be implemented in a near future
version, at which point we will enable IXFR by default.
</simpara></note>
</section>
<!-- TODO:
......@@ -2854,6 +2899,23 @@ what if a NOTIFY is sent?
<screen>&gt; <userinput>Xfrin retransfer zone_name="<option>foo.example.org</option>" master=<option>192.0.2.99</option></userinput></screen>
</para>
<para>
The <command>retransfer</command> command always uses AXFR.
To use IXFR for a zone that has already been transferred once,
use the <command>refresh</command> command.
It honors the <varname>Xfrin/zones/request_ixfr</varname>
configuration item (see <xref linkend="request_ixfr"/>.), and
if it's configured to use IXFR, it will be used.
</para>
<para>
Both the <command>retransfer</command>
and <command>refresh</command> commands can be used for
an initial transfer before setting up secondary
configurations.
In this case AXFR will be used for the obvious reason.
</para>
</section>
<section>
......@@ -2879,7 +2941,6 @@ http://bind10.isc.org/wiki/ScalableZoneLoadDesign#a7.2UpdatingaZone
</para>
</section>
<!-- TODO: can that retransfer be used to identify a new zone? -->
<!-- TODO: what if doesn't exist at that master IP? -->
</chapter>
......
......@@ -111,7 +111,7 @@ in separate zonemgr process.
<varname>class</varname> (defaults to <quote>IN</quote>),
<varname>master_addr</varname> (the zone master to transfer from),
<varname>master_port</varname> (defaults to 53),
<varname>use_ixfr</varname> (defaults to false), and
<varname>request_ixfr</varname> (defaults to yes), and
<varname>tsig_key</varname> (optional TSIG key name to use).
The <varname>tsig_key</varname> is specified using a name that
corresponds to one of the TSIG keys configured in the global
......
This diff is collapsed.
This diff is collapsed.
......@@ -48,6 +48,11 @@
"item_type": "boolean",
"item_optional": false,
"item_default": false
},
{ "item_name": "request_ixfr",
"item_type": "string",
"item_optional": false,
"item_default": "yes"
}
]
}
......@@ -56,7 +61,36 @@
"commands": [
{
"command_name": "retransfer",
"command_description": "retransfer a single zone without checking zone serial number",
"command_description": "retransfer a single zone without checking zone serial number, always using AXFR",
"command_args": [ {
"item_name": "zone_name",
"item_type": "string",
"item_optional": false,
"item_default": ""
},
{
"item_name": "zone_class",
"item_type": "string",
"item_optional": true,
"item_default": "IN"
},
{
"item_name": "master",
"item_type": "string",
"item_optional": true,
"item_default": ""
},
{
"item_name": "port",
"item_type": "integer",
"item_optional": true,
"item_default": 53
}
]
},
{
"command_name": "refresh",
"command_description": "transfer a single zone with checking zone serial number and honoring the request_ixfr policy",
"command_args": [ {
"item_name": "zone_name",
"item_type": "string",
......@@ -102,16 +136,16 @@
"item_optional": false,
"item_default": {
"_SERVER_" : {
"soaoutv4": 0,
"soaoutv6": 0,
"axfrreqv4": 0,
"axfrreqv6": 0,
"ixfrreqv4": 0,
"ixfrreqv6": 0,
"xfrsuccess": 0,
"xfrfail": 0,
"last_ixfr_duration": 0.0,
"last_axfr_duration": 0.0
"soaoutv4": 0,
"soaoutv6": 0,
"axfrreqv4": 0,
"axfrreqv6": 0,
"ixfrreqv4": 0,
"ixfrreqv6": 0,
"xfrsuccess": 0,
"xfrfail": 0,
"last_ixfr_duration": 0.0,
"last_axfr_duration": 0.0
}
},
"item_title": "Zone names",
......
......@@ -80,6 +80,24 @@ is not equal to the requested SOA serial.
There was an error importing the python DNS module pydnspp. The most
likely cause is a PYTHONPATH problem.
% XFRIN_INITIAL_AXFR no SOA available for %1 yet, requesting AXFR of initial version from %2
On starting the zone transfer, it's detected that there is no SOA
record available for the zone. This is always the case for the very
first transfer or if the administrator has removed the locally copied
data by hand for some reason. In this case trying IXFR does not make
sense for the obvious reason, so AXFR will be used from the beginning,
regardless of the request_ixfr configuration (even if "only" is
specified).
% XFRIN_INITIAL_IXFR requesting IXFR for %1 from %2
IXFR will be used for the initial request type for the specified zone
transfer. It will fall back to AXFR if the initial request fails
(and unless specified not to do so by configuration).
% XFRIN_INITIAL_IXFR_DISABLED IXFR disabled for %1, requesting AXFR from %2
The use of IXFR is disabled by configuration for the specified zone,
so only AXFR will be tried.
% XFRIN_INVALID_ZONE_DATA zone %1 received from %2 is broken and unusable
The zone was received, but it failed sanity validation. The previous version
of zone (if any is available) will be used. Look for previous
......@@ -212,6 +230,17 @@ such that the remote server doesn't support IXFR, we don't have the SOA record
(or the zone at all), we are out of sync, etc. In many of these situations,
AXFR could still work. Therefore we try that one in case it helps.
% XFRIN_XFR_TRANSFER_FALLBACK_DISABLED suppressing fallback from IXFR to AXFR for %1
An IXFR transfer of the given zone failed. By default AXFR will be
tried next, but this fallback is disabled by configuration, so the
whole transfer attempt failed at that point. If the reason for the
failure (which should be logged separately) is temporary, this is
probably harmless or even desired as another IXFR will take place some
time later (without falling back to the possibly expensive AXFR). If
this is a permanent error (e.g., some change at the master server
completely disables IXFR), the secondary zone will eventually expire,
so the configuration should be changed to allow AXFR.
% XFRIN_XFR_TRANSFER_PROTOCOL_VIOLATION %1 transfer of zone %2 with %3 failed: %4
The XFR transfer for the given zone has failed due to a protocol
error, such as an unexpected response from the primary server. The
......@@ -250,9 +279,9 @@ On starting an xfrin session, it is identified that the zone to be
transferred has multiple SOA RRs. Such a zone is broken, but could be
accidentally configured especially in a data source using "non
captive" backend database. The implementation ignores entire SOA RRs
and tries to continue processing as if the zone were empty. This
means subsequent AXFR can succeed and possibly replace the zone with
valid content, but an IXFR attempt will fail.
and tries to continue processing as if the zone were empty. This also
means AXFR will be used unconditionally, regardless of the configured value
for request_ixfr of the zone.
% XFRIN_ZONE_NO_SOA Zone %1 does not have SOA
On starting an xfrin session, it is identified that the zone to be
......
......@@ -2,7 +2,6 @@
"Xfrin": {
"zones": [
{
"use_ixfr": true,
"class": "IN",
"name": "example.com.",
"master_addr": "178.18.82.80"
......
......@@ -18,8 +18,7 @@
"zones": [ {
"name": "example",
"master_addr": "::1",
"master_port": 47807,
"use_ixfr": true
"master_port": 47807
} ]
},
"data_sources": {
......
......@@ -28,7 +28,8 @@
"zones": [ {
"name": "example.org",
"master_addr": "::1",
"master_port": 47807
"master_port": 47807,
"request_ixfr": "no"
} ]
},
"Zonemgr": {
......
......@@ -28,7 +28,8 @@
"zones": [ {
"name": "example.org",
"master_addr": "127.0.0.1",
"master_port": 47809
"master_port": 47809,
"request_ixfr": "no"
} ]
},
"Zonemgr": {
......
......@@ -182,7 +182,8 @@ Feature: Xfrin
example. 3600 IN SOA ns1.example. hostmaster.example. 94 3600 900 7200 300
"""
When I send bind10 the command Xfrin retransfer example. IN ::1 47807
# To invoke IXFR we need to use refresh command
When I send bind10 the command Xfrin refresh example. IN ::1 47807
Then wait for new bind10 stderr message XFRIN_GOT_INCREMENTAL_RESP
Then wait for new bind10 stderr message XFRIN_IXFR_TRANSFER_SUCCESS not XFRIN_XFR_PROCESS_FAILURE
# This can't be 'wait for new'
......
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