mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-31 05:55:28 +00:00
Code Issues Releases Wiki Activity

[master] Merge branch 'trac2005' with fixing conflicts in bind10-guide.xml.

Browse Source
This commit is contained in:
JINMEI Tatuya
2012-06-18 18:07:40 -07:00
parent 782670fae6 6bfaf8bdba
commit b1d760f18c
4 changed files with 452 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

345
doc/guide/bind10-guide.xml
View File

@@ -87,9 +87,10 @@
<section>
<title>Supported Platforms</title>
<para>
BIND 10 builds have been tested on Debian GNU/Linux 5 and unstable,
Ubuntu 9.10, NetBSD 5, Solaris 10, FreeBSD 7 and 8, CentOS
Linux 5.3, and MacOS 10.6.
BIND 10 builds have been tested on (in no particular order)
Debian GNU/Linux 5 and unstable, Ubuntu 9.10, NetBSD 5,
Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3,
MacOS 10.6 and 10.7, and OpenBSD 5.1.
It has been tested on Sparc, i386, and amd64 hardware
platforms.
@@ -127,10 +128,10 @@
</para>
<para>
The <command>b10-xfrin</command>, <command>b10-xfrout</command>,
and <command>b10-zonemgr</command> components require the
libpython3 library and the Python _sqlite3.so module
(which is included with Python).
The <command>b10-ddns</command>, <command>b10-xfrin</command>,
<command>b10-xfrout</command>, and <command>b10-zonemgr</command>
components require the libpython3 library and the Python
_sqlite3.so module (which is included with Python).
The <command>b10-stats-httpd</command> component uses the
Python pyexpat.so module.
The Python modules need to be built for the corresponding Python 3.
@@ -196,6 +197,16 @@
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-ddns</command> &mdash;
Dynamic DNS update service.
This process is used to handle incoming DNS update
requests to allow granted clients to update zones
for which BIND 10 is serving as a primary server.
</simpara>
</listitem>
<listitem>
<simpara>
<command>b10-msgq</command> &mdash;
@@ -1833,7 +1844,6 @@ what if a NOTIFY is sent?
<chapter id="xfrout">
<title>Outbound Zone Transfers</title>
<para>
The <command>b10-xfrout</command> process is started by
<command>bind10</command>.
@@ -1909,6 +1919,325 @@ what is XfroutClient xfr_client??
</chapter>
<chapter id="ddns">
<title>Dynamic DNS Update</title>
<para>
BIND 10 supports the server side of the Dynamic DNS Update
(DDNS) protocol as defined in RFC 2136.
This service is provided by the <command>b10-ddns</command>
component, which is started by the <command>bind10</command>
process if configured so.
</para>
<para>
When the <command>b10-auth</command> authoritative DNS server
receives an UPDATE request, it internally forwards the request
to <command>b10-ddns</command>, which handles the rest of
request processing.
When the processing is completed <command>b10-ddns</command>
will send a response to the client with the RCODE set to the
value as specified in RFC 2136 (NOERROR for successful update,
REFUSED if rejected due to ACL check, etc).
If the zone has been changed as a result, it will internally
notify <command>b10-xfrout</command> so that other secondary
servers will be notified via the DNS notify protocol.
In addition, if <command>b10-auth</command> serves the updated
zone from its in-memory cache (as described in
<xref linkend="in-memory-datasource-with-sqlite3-backend" />),
<command>b10-ddns</command> will also
notify <command>b10-auth</command> so that <command>b10-auth</command>
will re-cache the updated zone content.
</para>
<para>
The <command>b10-ddns</command> component supports requests over
both UDP and TCP, and both IPv6 and IPv4; for TCP requests,
however, it terminates the TCP connection immediately after
each single request has been processed. Clients cannot reuse the
same TCP connection for multiple requests. (This is a current
implementation limitation of <command>b10-ddns</command>.
While RFC 2136 doesn't specify anything about such reuse of TCP
connection, there is no reason for disallowing it as RFC 1035
generally allows multiple requests sent over a single TCP
connection. BIND 9 supports such reuse.)
</para>
<para>
As of this writing <command>b10-ddns</command> does not support
update forwarding for secondary zones.
If it receives an update request for a secondary zone, it will
immediately return a response with an RCODE of NOTIMP.
<note><simpara>
For feature completeness update forwarding should be
eventually supported. But right now it's considered a lower
priority task and there is no specific plan of implementing
this feature.
<!-- See Trac #2063 -->
</simpara></note>
</para>
<section>
<title>Enabling Dynamic Update</title>
<para>
First off, it must be made sure that a few components on which
<command>b10-ddns</command> depends are configured to run,
which are <command>b10-auth</command>
and <command>b10-zonemgr</command>.
In addition, <command>b10-xfrout</command> should also be
configured to run; otherwise the notification after an update
(see above) will fail with a timeout, suspending the DDNS
service while <command>b10-ddns</command> waits for the
response (see the description of the <ulink
url="bind10-messages.html#DDNS_UPDATE_NOTIFY_FAIL">DDNS_UPDATE_NOTIFY_FAIL</ulink>
log message for further details).
If BIND 10 is already configured to provide authoritative DNS
service they should normally be configured to run already.
</para>
<para>
Second, for the obvious reason dynamic update requires that the
underlying data source storing the zone data be writable.
In the current implementation this means the zone must be stored
in an SQLite3-based data source.
Also, right now, the <command>b10-ddns</command> component
configures itself with the data source referring to the
<quote>database_file</quote> configuration parameter of
<command>b10-auth</command>.
So this information must be configured correctly before starting
<command>b10-ddns</command>.
<note><simpara>
The way to configure data sources is now being revised.
Configuration on the data source for DDNS will be very
likely to be changed in a backward incompatible manner in
a near future version.
</simpara></note>
</para>
<para>
In general, if something goes wrong regarding the dependency
described above, <command>b10-ddns</command> will log the
related event at the warning or error level.
It's advisable to check the log message when you first enable
DDNS or if it doesn't work as you expect to see if there's any
warning or error log message.
</para>
<para>
Next, to enable the DDNS service, <command>b10-ddns</command>
needs to be explicitly configured to run.
It can be done by using the <command>bindctl</command>
utility. For example:
<screen>
&gt; <userinput>config add Boss/components b10-ddns</userinput>
&gt; <userinput>config set Boss/components/b10-ddns/address DDNS</userinput>
&gt; <userinput>config set Boss/components/b10-ddns/kind dispensable</userinput>
&gt; <userinput>config commit</userinput>
</screen>
<note><simpara>
In theory "kind" could be omitted because "dispensable" is its
default. But there's some peculiar behavior (which should
be a bug and should be fixed eventually; see Trac ticket
#2064) with bindctl and you'll still need to specify that explicitly.
Likewise, "address" may look unnecessary because
<command>b10-ddns</command> would start and work without
specifying it. But for it to shutdown gracefully this
parameter should also be specified.
</simpara></note>
</para>
</section>
<section>
<title>Access Control</title>
<para>
By default <command>b10-ddns</command> rejects any update
requests from any clients by returning a response with an RCODE
of REFUSED.
To allow updates to take effect, an access control rule
(called update ACL) with a policy allowing updates must explicitly be
configured.
Update ACL must be configured per zone basis in the
<quote>zones</quote> configuration parameter of
<command>b10-ddns</command>.
This is a list of per-zone configuration regarding DDNS.
Each list element consists of the following parameters:
<variablelist>
<varlistentry>
<term>origin</term>
<listitem>
<simpara>The zone's origin name</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>class</term>
<listitem>
<simpara>The RR class of the zone
(normally <quote>IN</quote>, and in that case
can be omitted in configuration)</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>update_acl</term>
<listitem>
<simpara>List of access control rules (ACL) for the zone</simpara>
</listitem>
</varlistentry>
</variablelist>
The syntax of the ACL is the same as ACLs for other
components.
Specific examples are given below.
</para>
<para>
In general, an update ACL rule that allows an update request
should be configured with a TSIG key.
This is an example update ACL that allows updates to the zone
named <quote>example.org</quote> of RR class <quote>IN</quote>
from clients that send requests signed with a TSIG whose
key name is "key.example.org" (and refuses all others):
<screen>
&gt; <userinput>config add DDNS/zones</userinput>
&gt; <userinput>config set DDNS/zones[0]/origin example.org</userinput>
&gt; <userinput>config set DDNS/zones[0]/class IN</userinput>
(Note: "class" can be omitted)
&gt; <userinput>config add DDNS/zones[0]/update_acl {"action": "ACCEPT", "key": "key.example.org"}</userinput>
&gt; <userinput>config commit</userinput>
</screen>
The TSIG key must be configured system wide
(see <xref linkend="xfrout"/>.)
</para>
<para>
Multiple rules can be specified in the ACL, and an ACL rule
can consist of multiple constraints, such as a combination of
IP address and TSIG.
The following configuration sequence will add a new rule to
the ACL created in the above example. This additional rule
allows update requests sent from a client
using TSIG key name of "key.example" (different from the
key used in the previous example) and has an IPv6 address of ::1.
<screen>
&gt; <userinput>config add DDNS/zones[0]/update_acl {"action": "ACCEPT", "from": "::1", "key": "key.example"}</userinput>
&gt; <userinput>config show DDNS/zones[0]/update_acl</userinput>
DDNS/zones[0]/update_acl[0] {"action": "ACCEPT", "key": "key.example.org"} any (modified)
DDNS/zones[0]/update_acl[1] {"action": "ACCEPT", "from": "::1", "key": "key.example"} any (modified)
&gt; <userinput>config commit</userinput>
</screen>
(Note the "add" in the first line. Before this sequence, we
have had only entry in zones[0]/update_acl. The "add" command
with a value (rule) adds a new entry and sets it to the given rule.
Due to a limitation of the current implementation, it doesn't
work if you first try to just add a new entry and then set it to
a given rule).
</para>
<note><simpara>
The <command>b10-ddns</command> component accepts an ACL
rule that just allows updates from a specific IP address
(i.e., without requiring TSIG), but this is highly
discouraged (remember that requests can be made over UDP and
spoofing the source address of a UDP packet is often pretty
easy).
Unless you know what you are doing and that you can accept
its consequence, any update ACL rule that allows updates
should have a TSIG key in its constraints.
</simpara></note>
<para>
The ACL rules will be checked in the listed order, and the
first matching one will apply.
If none of the rules matches, the default rule will apply,
which is rejecting any requests in the case of
<command>b10-ddns</command>.
</para>
<para>
Other actions than "ACCEPT", namely "REJECT" and "DROP", can be
used, too.
See <xref linkend="resolverserver"/> about their effects.
</para>
<para>
Currently update ACL can only control updates per zone basis;
it's not possible to specify access control with higher
granularity such as for particular domain names or specific
types of RRs.
<!-- See Trac ticket #2065 -->
</para>
<note><simpara>
Contrary to what RFC 2136 (literally) specifies,
<command>b10-ddns</command> checks the update ACL before
checking the prerequisites of the update request.
This is a deliberate implementation decision.
This counter intuitive specification has been repeatedly
discussed among implementers and in the IETF, and it is now
widely agreed that it does not make sense to strictly follow
that part of RFC.
One known specific bad result of following the RFC is that it
could leak information about which name or record exists or does not
exist in the zone as a result of prerequisite checks even if a
zone is somehow configured to reject normal queries from
arbitrary clients.
There have been other troubles that could have been avoided if
the ACL could be checked before the prerequisite check.
</simpara></note>
</section>
<section>
<title>Miscellaneous Operational Issues</title>
<para>
Unlike BIND 9, BIND 10 currently does not support automatic
resigning of DNSSEC-signed zone when it's updated via DDNS.
It could be possible to resign the updated zone afterwards
or make sure the update request also updates related DNSSEC
records, but that will be pretty error-prone operation.
In general, it's not advisable to allow DDNS for a signed zone
at this moment.
</para>
<para>
Also unlike BIND 9, it's currently not possible
to <quote>freeze</quote> a zone temporarily in order to
suspend DDNS while you manually update the zone.
If you need to make manual updates to a dynamic zone,
you'll need to temporarily reject any updates to the zone via
the update ACLs.
</para>
<para>
Dynamic updates are only applicable to primary zones.
In order to avoid updating secondary zones via DDNS requests,
<command>b10-ddns</command> refers to the
<quote>secondary_zones</quote> configuration of
<command>b10-zonemgr</command>. Zones listed in
<quote>secondary_zones</quote> will never be updated via DDNS
regardless of the update ACL configuration;
<command>b10-ddns</command> will return a response with an
RCODE of NOTAUTH as specified in RFC 2136.
If you have a "conceptual" secondary zone whose content is a
copy of some external source but is not updated via the
standard zone transfers and therefore not listed in
<quote>secondary_zones</quote>, be careful not to allow DDNS
for the zone; it would be quite likely to lead to inconsistent
state between different servers.
Normally this should not be a problem because the default
update ACL rejects any update requests, but you may want to
take an extra care about the configuration if you have such
type of secondary zones.
</para>
<para>
The difference of two versions of a zone, before and after a
DDNS transaction, is automatically recorded in the underlying
data source, and can be retrieved in the form of outbound
IXFR.
This is done automatically; it does not require specific
configuration to make this possible.
</para>
</section>
</chapter>
<chapter id="resolverserver">
<title>Recursive Name Server</title>

55
src/bin/ddns/b10-ddns.8
View File

@@ -1,7 +1,7 @@
'\" t
.\" Title: b10-ddns
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\" Date: February 28, 2012
.\" Manual: BIND10
.\" Source: BIND10
@@ -9,6 +9,15 @@
.\"
.TH "B10\-DDNS" "8" "February 28, 2012" "BIND10" "BIND10"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
@@ -33,29 +42,29 @@ boss process\&. When the
\fBb10\-auth\fR
DNS server receives a DDNS update,
\fBb10\-ddns\fR
updates the zone in the BIND 10 zone data store\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
updates the zone in the BIND 10 zone data source\&.
.PP
Currently installed is a dummy component\&. It does not provide any functionality\&. It is a skeleton implementation that will be expanded later\&.
.sp .5v
.RE
When the
\fBb10\-auth\fR
authoritative DNS server receives an UPDATE request, it internally forwards the request to
\fBb10\-ddns\fR, which handles the rest of request processing\&. When the process is completed
\fBb10\-ddns\fR
will send a response to the client with the processing result\&. If the zone has been changed as a result, it will internally notify
\fBb10\-auth\fR
and
\fBb10\-xfrout\fR
so the new version of zone will be served, and other secondary servers will be notified via the DNS notify protocol\&.
.PP
This daemon communicates with BIND 10 over a
\fBb10-msgq\fR(8)
C\-Channel connection\&. If this connection is not established,
\fBb10\-ddns\fR
will exit\&.
will exit\&. The
\fBb10\-ddns\fR
daemon depends on some other BIND 10 components:
\fBb10-auth\fR(8)
and
\fBb10-zonemgr\fR(8)\&.
.PP
\fBb10\-ddns\fR
@@ -75,7 +84,13 @@ The configurable settings are:
.PP
\fIzones\fR
The zones option is a named set of zones that can be updated with DDNS\&. Each entry has one element called update_acl, which is a list of access control rules that define update permissions\&. By default this is empty; DDNS must be explicitely enabled per zone\&.
The zones option is a list of configuration items for specific zones that can be updated with DDNS\&. Each entry is a map that can contain the following items:
\fIorigin\fR
is a textual domain name of the zone;
\fIclass\fR
(text) is the RR class of the zone;
\fIupdate_acl\fR
is a list of ACL that controls permission for updates\&. See the BIND 10 Guide for configuration details\&. Note that not listing a zone in this list does not directly mean update requests for the zone are rejected, but the end result is the same because the default ACL for updates is to deny all requests\&.
.PP
The module commands are:
.PP
@@ -91,6 +106,8 @@ argument to select the process ID to stop\&. (Note that the BIND 10 boss process
\fBb10-auth\fR(8),
\fBb10-cfgmgr\fR(8),
\fBb10-msgq\fR(8),
\fBb10-xfrout\fR(8),
\fBb10-zonemgr\fR(8),
\fBbind10\fR(8),
BIND 10 Guide\&.
.SH "HISTORY"

66
src/bin/ddns/b10-ddns.xml
View File

@@ -20,7 +20,7 @@
<refentry>
<refentryinfo>
<date>February 28, 2012</date>
<date>June 18, 2012</date>
</refentryinfo>
<refmeta>
@@ -58,23 +58,33 @@
Normally it is started by the
<citerefentry><refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum></citerefentry>
boss process.
When the <command>b10-auth</command> DNS server receives
a DDNS update, <command>b10-ddns</command> updates the zone
in the BIND 10 zone data store.
</para>
<note><para>
Currently installed is a dummy component. It does not provide
any functionality. It is a skeleton implementation that
will be expanded later.
<!-- TODO: #1458 -->
</para></note>
<para>
When the <command>b10-auth</command> authoritative DNS server
receives an UPDATE request, it internally forwards the request
to <command>b10-ddns</command>, which handles the rest of
request processing.
When the processing is completed <command>b10-ddns</command>
will send a response to the client with the RCODE set to the
value as specified in RFC 2136.
If the zone has been changed as a result, it will internally
notify <command>b10-auth</command> and
<command>b10-xfrout</command> so the new version of the zone will
be served, and other secondary servers will be notified via the
DNS notify protocol.
</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-ddns</command> will exit.
The <command>b10-ddns</command> daemon also depends on some other
BIND 10 components (either directly or indirectly):
<citerefentry><refentrytitle>b10-auth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>b10-xfrout</refentrytitle><manvolnum>8</manvolnum></citerefentry>, and
<citerefentry><refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
<para>
@@ -90,6 +100,17 @@
<variablelist>
<varlistentry>
<term>
<option>-h</option>,
<option>--help</option>
</term>
<listitem>
<para>
Print the command line arguments and exit.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>-v</option>,
@@ -98,7 +119,7 @@
<listitem>
<para>
This value is ignored at this moment, but is provided for
compatibility with the bind10 Boss process
compatibility with the bind10 Boss process.
</para>
</listitem>
</varlistentry>
@@ -112,10 +133,18 @@
</para>
<para>
<varname>zones</varname>
The zones option is a named set of zones that can be updated with
DDNS. Each entry has one element called update_acl, which is
a list of access control rules that define update permissions.
By default this is empty; DDNS must be explicitely enabled per zone.
The zones option is a list of configuration items for specific
zones that can be updated with DDNS. Each entry is a map that
can contain the following items:
<varname>origin</varname> is a textual domain name of the zone;
<varname>class</varname> (text) is the RR class of the zone;
<varname>update_acl</varname> is an ACL that controls
permission for updates.
See the BIND 10 Guide for configuration details.
Note that not listing a zone in this list does not directly
mean update requests for the zone are rejected, but the end
result is the same because the default ACL for updates is to
deny all requests.
</para>
<para>
@@ -144,6 +173,12 @@
<citerefentry>
<refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>b10-xfrout</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
@@ -156,6 +191,7 @@
<para>
The <command>b10-ddns</command> daemon was first implemented
in December 2011 for the ISC BIND 10 project.
The first functional version was released in June 2012.
</para>
</refsect1>
</refentry><!--

41
src/bin/ddns/ddns_messages.mes
View File

@@ -214,16 +214,31 @@ notify messages to secondary servers.
% DDNS_UPDATE_NOTIFY_FAIL failed to notify %1 of updates to %2: %3
b10-ddns has made updates to a zone based on an update request and
tried to notify an external module of the updates, but the
notification fails. Severity of this effect depends on the type of
the module. If it's b10-xfrout, this means DNS notify messages won't
be sent to secondary servers of the zone. It's suboptimal, but not
necessarily critical as the secondary servers will try to check the
zone's status periodically. If it's b10-auth and the notification was
needed to have it reload the corresponding zone, it's more serious
because b10-auth won't be able to serve the new version of the zone
unless some explicit recovery action is taken. So the administrator
needs to examine this message and takes an appropriate action. In
either case, this notification is generally expected to succeed; so
the fact it fails itself means there's something wrong in the BIND 10
system, and it would be advisable to check other log messages.
tried to notify an external component of the updates, but the
notification fails. One possible cause of this is that the external
component is not really running and it times out in waiting for the
response, although it will be less likely to happen in practice
because these components will normally be configured to run when the
server provides the authoritative DNS service; ddns is rather optional
among them. If this happens, however, it will suspend b10-ddns for a
few seconds during which it cannot handle new requests (some may be
delayed, some may be dropped, depending on the volume of the incoming
requests). This is obviously bad, and if this error happens due to
this reason, the administrator should make sure the component in
question should be configured to run. For a longer term, b10-ddns
should be more robust about this case such as by making this
notification asynchronously and/or detecting the existence of the
external components to avoid hopeless notification in the first place.
Severity of this error for the receiving components depends on the
type of the component. If it's b10-xfrout, this means DNS notify
messages won't be sent to secondary servers of the zone. It's
suboptimal, but not necessarily critical as the secondary servers will
try to check the zone's status periodically. If it's b10-auth and the
notification was needed to have it reload the corresponding zone, it's
more serious because b10-auth won't be able to serve the new version
of the zone unless some explicit recovery action is taken. So the
administrator needs to examine this message and takes an appropriate
action. In either case, this notification is generally expected to
succeed; so the fact it fails itself means there's something wrong in
the BIND 10 system, and it would be advisable to check other log
messages.