BIND 10 master, updated. c1171699a2b501321ab54207ad26e5da2b092d63 Merge remote-tracking branch 'origin/trac1341'
BIND 10 source code commits
bind10-changes at lists.isc.org
Wed Nov 23 22:58:46 UTC 2011
The branch, master has been updated
via c1171699a2b501321ab54207ad26e5da2b092d63 (commit)
via 8f5429e41cb99c615abc1de0ee549702ca638217 (commit)
via 52fa244c12eb6d708b0260b5554396df5d00b079 (commit)
via ce54ff203a48042d3fa085037a23b315ccc2ecca (commit)
via 8fe1dbdadf8ce7aa288ae08320f315ab56433cb6 (commit)
via a9dc55c6cc18e2ed28f79cfbbdf7408a64a04ca4 (commit)
via 151a4b05228e38b2031d095e438b63ae75dc0b76 (commit)
via 3924f73fed9f8158918713b09672175f09a973e4 (commit)
via e12070c73b529d348f64f8f6e24d75ce710a8a12 (commit)
via 35b1914ce6ab5481ce40f584729d0949746c2219 (commit)
via 1c9f121360e6e612d02d365d70bd0843f8f93457 (commit)
via d142274062ed21d53f9e0b2a85531c935580013c (commit)
via 5de9e8a440b6b4ed8c6bbce156d75b740ec4c1b5 (commit)
via cd4fd339a084dbfb1e2d35d5c008260de9d48572 (commit)
from f76fdc8db2c0c9eba1603af7fa0272e7955e20d8 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit c1171699a2b501321ab54207ad26e5da2b092d63
Merge: f76fdc8db2c0c9eba1603af7fa0272e7955e20d8 8f5429e41cb99c615abc1de0ee549702ca638217
Author: Jeremy C. Reed <jreed at ISC.org>
Date: Wed Nov 23 16:58:38 2011 -0600
Merge remote-tracking branch 'origin/trac1341'
-----------------------------------------------------------------------
Summary of changes:
doc/guide/bind10-guide.xml | 179 ++++++++++++++++++-
src/bin/bind10/bind10.xml | 200 ++++++++++++++++++++-
src/bin/bind10/bind10_src.py.in | 2 +-
src/bin/bind10/tests/bind10_test.py.in | 6 +-
src/lib/python/isc/bind10/component.py | 8 +-
src/lib/python/isc/bind10/special_component.py | 6 +-
src/lib/python/isc/bind10/tests/component_test.py | 2 +-
7 files changed, 382 insertions(+), 21 deletions(-)
-----------------------------------------------------------------------
diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index 711b144..e61725f 100644
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -706,7 +706,7 @@ Debian and Ubuntu:
BIND 10 provides the <command>bind10</command> command which
starts up the required processes.
<command>bind10</command>
- will also restart processes that exit unexpectedly.
+ will also restart some processes that exit unexpectedly.
This is the only command needed to start the BIND 10 system.
</para>
@@ -718,17 +718,22 @@ Debian and Ubuntu:
</para>
<para>
- The <command>b10-msgq</command> and <command>b10-cfgmgr</command>
+ The <command>b10-sockcreator</command>, <command>b10-msgq</command> and
+ <command>b10-cfgmgr</command>
services make up the core. The <command>b10-msgq</command> daemon
provides the communication channel between every part of the system.
The <command>b10-cfgmgr</command> daemon is always needed by every
module, if only to send information about themselves somewhere,
but more importantly to ask about their own settings, and
- about other modules.
- The <command>bind10</command> master process will also start up
+ about other modules. The <command>b10-sockcreator</command> will
+ allocate sockets for the rest of the system.
+ </para>
+
+ <para>
+ In its default configuration, 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 or
- <command>b10-resolver</command> for recursive name service,
+ system, <command>b10-auth</command> for authoritative DNS service,
<command>b10-stats</command> for statistics collection,
<command>b10-xfrin</command> for inbound DNS zone transfers,
<command>b10-xfrout</command> for outbound DNS zone transfers,
@@ -754,6 +759,159 @@ Debian and Ubuntu:
</note>
</section>
+ <section id="bind10.config">
+ <title>Configuration of started processes</title>
+ <para>
+ The processes to be started can be configured, with the exception
+ of the <command>b10-sockcreator</command>, <command>b10-msgq</command>
+ and <command>b10-cfgmgr</command>.
+ </para>
+
+ <para>
+ The configuration is in the Boss/components section. Each element
+ represents one component, which is an abstraction of a process
+ (currently there's also one component which doesn't represent
+ a process). If you didn't want to transfer out at all (your server
+ is a slave only), you would just remove the corresponding component
+ from the set, like this and the process would be stopped immediately
+ (and not started on the next startup):
+ <screen>> <userinput>config remove Boss/components b10-xfrout</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+
+ <para>
+ To add a process to the set, let's say the resolver (which not started
+ by default), you would do this:
+ <screen>> <userinput>config add Boss/components b10-resolver</userinput>
+> <userinput>config set Boss/components/b10-resolver/special resolver</userinput>
+> <userinput>config set Boss/components/b10-resolver/kind needed</userinput>
+> <userinput>config set Boss/components/b10-resolver/priority 10</userinput>
+> <userinput>config commit</userinput></screen></para>
+
+ <para>
+ Now, what it means. We add an entry called b10-resolver. It is both a
+ name used to reference this component in the configuration and the
+ name of the process to start. Then we set some parameters on how to
+ start it.
+ </para>
+
+ <para>
+ The special one is for components that need some kind of special care
+ during startup or shutdown. Unless specified, the component is started
+ in usual way. This is the list of components that need to be started
+ in a special way, with the value of special used for them:
+ <table>
+ <tgroup cols='3' align='left'>
+ <colspec colname='component'/>
+ <colspec colname='special'/>
+ <colspec colname='description'/>
+ <thead><row><entry>Component</entry><entry>Special</entry><entry>Description</entry></row></thead>
+ <tbody>
+ <row><entry>b10-auth</entry><entry>auth</entry><entry>Authoritative server</entry></row>
+ <row><entry>b10-resolver</entry><entry>resolver</entry><entry>The resolver</entry></row>
+ <row><entry>b10-cmdctl</entry><entry>cmdctl</entry><entry>The command control (remote control interface)</entry></row>
+ <row><entry>setuid</entry><entry>setuid</entry><entry>Virtual component, see below</entry></row>
+ <!-- TODO Either add xfrin and xfrout as well or clean up the workarounds in boss before the release -->
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <para>
+ The kind specifies how a failure of the component should
+ be handled. If it is set to <quote>dispensable</quote>
+ (the default unless you set something else), it will get
+ started again if it fails. If it is set to <quote>needed</quote>
+ and it fails at startup, the whole <command>bind10</command>
+ shuts down and exits with error exit code. But if it fails
+ some time later, it is just started again. If you set it
+ to <quote>core</quote>, you indicate that the system is
+ not usable without the component and if such component
+ fails, the system shuts down no matter when the failure
+ happened. This is the behaviour of the core components
+ (the ones you can't turn off), but you can declare any
+ other components as core as well if you wish (but you can
+ turn these off, they just can't fail).
+ </para>
+
+ <para>
+ The priority defines order in which the components should start.
+ The ones with higher number are started sooner than the ones with
+ lower ones. If you don't set it, 0 (zero) is used as the priority.
+ </para>
+
+ <para>
+ There are other parameters we didn't use in our example.
+ One of them is <quote>address</quote>. It is the address
+ used by the component on the <command>b10-msgq</command>
+ message bus. The special components already know their
+ address, but the usual ones don't. The address is by
+ convention the thing after <emphasis>b10-</emphasis>, with
+ the first letter capital (eg. <command>b10-stats</command>
+ would have <quote>Stats</quote> as its address).
+<!-- TODO: this should be simplified so we don't even have to document it -->
+ </para>
+
+<!-- TODO: what does "The special components already know their
+address, but the usual ones don't." mean? -->
+
+<!-- TODO: document params when is enabled -->
+
+ <para>
+ The last one is process. It is the name of the process to be started.
+ It defaults to the name of the component if not set, but you can use
+ this to override it.
+ </para>
+
+ <!-- TODO Add parameters when they work, not implemented yet-->
+
+ <note>
+ <para>
+ This system allows you to start the same component multiple times
+ (by including it in the configuration with different names, but the
+ same process setting). However, the rest of the system doesn't expect
+ such situation, so it would probably not do what you want. Such
+ support is yet to be implemented.
+ </para>
+ </note>
+
+ <note>
+ <para>
+ The configuration is quite powerful, but that includes
+ a lot of space for mistakes. You could turn off the
+ <command>b10-cmdctl</command>, but then you couldn't
+ change it back the usual way, as it would require it to
+ be running (you would have to find and edit the configuration
+ directly). Also, some modules might have dependencies
+ -- <command>b10-stats-httpd</command> need
+ <command>b10-stats</command>, <command>b10-xfrout</command>
+ needs the <command>b10-auth</command> to be running, etc.
+
+<!-- TODO: should we define dependencies? -->
+
+ </para>
+ <para>
+ In short, you should think twice before disabling something here.
+ </para>
+ </note>
+
+ <para>
+ Now, to the mysterious setuid virtual component. If you
+ use the <command>-u</command> option to start the
+ <command>bind10</command> as root, but change the user
+ later, we need to start the <command>b10-auth</command> or
+ <command>b10-resolver</command> as root (until the socket
+ creator is finished).<!-- TODO --> So we need to specify
+ the time when the switch from root do the given user happens
+ and that's what the setuid component is for. The switch is
+ done at the time the setuid component would be started, if
+ it was a process. The default configuration contains the
+ setuid component with priority 5, <command>b10-auth</command>
+ has 10 to be started before the switch and everything else
+ is without priority, so it is started after the switch.
+ </para>
+
+ </section>
</chapter>
@@ -1494,8 +1652,13 @@ what is XfroutClient xfr_client??
You may change this using <command>bindctl</command>, for example:
<screen>
-> <userinput>config set Boss/start_auth false</userinput>
-> <userinput>config set Boss/start_resolver true</userinput>
+> <userinput>config remove Boss/components b10-xfrout</userinput>
+> <userinput>config remove Boss/components b10-xfrin</userinput>
+> <userinput>config remove Boss/components b10-auth</userinput>
+> <userinput>config add Boss/components b10-resolver</userinput>
+> <userinput>config set Boss/components/b10-resolver/special resolver</userinput>
+> <userinput>config set Boss/components/b10-resolver/kind needed</userinput>
+> <userinput>config set Boss/components/b10-resolver/priority 10</userinput>
> <userinput>config commit</userinput>
</screen>
diff --git a/src/bin/bind10/bind10.xml b/src/bin/bind10/bind10.xml
index 340a2bb..6705760 100644
--- a/src/bin/bind10/bind10.xml
+++ b/src/bin/bind10/bind10.xml
@@ -20,7 +20,7 @@
<refentry>
<refentryinfo>
- <date>August 11, 2011</date>
+ <date>November 23, 2011</date>
</refentryinfo>
<refmeta>
@@ -218,6 +218,204 @@ TODO: configuration section
-->
<refsect1>
+ <title>CONFIGURATION AND COMMANDS</title>
+
+ <para>
+ The configuration provides settings for components for
+ <command>bind10</command> to manage under
+ <varname>/Boss/components/</varname>.
+ The default elements are:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para> <varname>/Boss/components/b10-auth</varname> </para>
+ </listitem>
+
+ <listitem>
+ <para> <varname>/Boss/components/b10-cmdctl</varname> </para>
+ </listitem>
+
+ <listitem>
+ <para> <varname>/Boss/components/setuid</varname> </para>
+ </listitem>
+
+ <listitem>
+ <para> <varname>/Boss/components/b10-stats</varname> </para>
+ </listitem>
+
+ <listitem>
+ <para> <varname>/Boss/components/b10-stats-httpd</varname> </para>
+ </listitem>
+
+ <listitem>
+ <para> <varname>/Boss/components/b10-xfrin</varname> </para>
+ </listitem>
+
+ <listitem>
+ <para> <varname>/Boss/components/b10-xfrout</varname> </para>
+ </listitem>
+
+ <listitem>
+ <para> <varname>/Boss/components/b10-zonemgr</varname> </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ (Note that the startup of <command>b10-sockcreator</command>,
+ <command>b10-cfgmgr</command>, and <command>b10-msgq</command>
+ is not configurable. It is hardcoded and <command>bind10</command>
+ will not run without them.)
+ </para>
+
+ <para>
+ These named sets (listed above) contain the following settings:
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><varname>address</varname></term>
+ <listitem>
+ <para>The name used for communicating to it on the message
+ bus.</para>
+<!-- NOTE: vorner said:
+These can be null, because the components are special ones, and
+the special class there already knows the address. It is (I hope)
+explained in the guide. I'd like to get rid of the special components
+sometime and I'd like it to teach to guess the address.
+-->
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kind</varname></term>
+ <listitem>
+ <para>
+ This defines how required a component is.
+ The possible settings for <varname>kind</varname> are:
+ <varname>core</varname> (system won't start if it won't
+ start and <command>bind10</command> will shutdown if
+ a <quote>core</quote> component crashes),
+ <varname>dispensable</varname> (<command>bind10</command>
+ will restart failing component),
+ and
+ <varname>needed</varname> (<command>bind10</command>
+ will shutdown if component won't initially start, but
+ if crashes later, it will attempt to restart).
+ This setting is required.
+<!-- TODO: formatting -->
+ </para>
+ </listitem>
+ </varlistentry>
+
+<!--
+TODO: currently not used
+ <varlistentry>
+ <term> <varname>params</varname> </term>
+ <listitem>
+ <para>
+list
+</para>
+ </listitem>
+ </varlistentry>
+-->
+
+ <varlistentry>
+ <term> <varname>priority</varname> </term>
+ <listitem>
+ <para>This is an integer. <command>bind10</command>
+ will start the components with largest priority numbers first.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <varname>process</varname> </term>
+ <listitem>
+ <para>This is the filename of the executable to be started.
+ If not defined, then <command>bind10</command> will
+ use the component name instead.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <varname>special</varname> </term>
+ <listitem>
+ <para>
+ This defines if the component is started a special
+ way.
+<!--
+TODO: document this ... but maybe some of these will be removed
+once we get rid of some using switches for components?
+
+auth
+cfgmgr
+cmdctl
+msgq
+resolver
+setuid
+sockcreator
+xfrin
+-->
+
+</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+<!-- TODO: formating -->
+ <para>
+ The <varname>Boss</varname> configuration commands are:
+ </para>
+<!-- TODO: let's just let bind10 be known as bind10 and not Boss -->
+
+ <para>
+ <command>getstats</command> tells <command>bind10</command>
+ to send its statistics data to the <command>b10-stats</command>
+ daemon.
+ This is an internal command and not exposed to the administrator.
+<!-- not defined in spec -->
+<!-- TODO: explain difference with sendstat -->
+ </para>
+
+ <para>
+ <command>ping</command> is used to check the connection with the
+ <command>bind10</command> daemon.
+ It returns the text <quote>pong</quote>.
+ </para>
+
+ <para>
+ <command>sendstats</command> tells <command>bind10</command>
+ to send its statistics data to the <command>b10-stats</command>
+ daemon immediately.
+<!-- TODO: compare with internal command getstats? -->
+ </para>
+
+ <para>
+ <command>show_processes</command> lists the current processes
+ managed by <command>bind10</command>.
+ The output is an array in JSON format containing the process
+ ID and the name for each.
+<!-- TODO: what is name? -->
+<!-- TODO: change to JSON object format? -->
+<!-- TODO: ticket #1406 -->
+ </para>
+
+ <para>
+ <command>shutdown</command> tells <command>bind10</command>
+ to shutdown the BIND 10 servers.
+ It will tell each process it manages to shutdown and, when
+ complete, <command>bind10</command> will exit.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
<title>STATISTICS DATA</title>
<para>
diff --git a/src/bin/bind10/bind10_src.py.in b/src/bin/bind10/bind10_src.py.in
index bf6079e..13cd3e3 100755
--- a/src/bin/bind10/bind10_src.py.in
+++ b/src/bin/bind10/bind10_src.py.in
@@ -700,7 +700,7 @@ class BoB:
If we did not start yet, it raises an exception, which is meant
to propagate through the component and configurator to the startup
- routine and abort the startup imediatelly. If it is started up already,
+ routine and abort the startup immediately. If it is started up already,
we just mark it so we terminate soon.
It does set the exit code in both cases.
diff --git a/src/bin/bind10/tests/bind10_test.py.in b/src/bin/bind10/tests/bind10_test.py.in
index db68b35..b7b741c 100644
--- a/src/bin/bind10/tests/bind10_test.py.in
+++ b/src/bin/bind10/tests/bind10_test.py.in
@@ -876,9 +876,9 @@ class TestBossComponents(unittest.TestCase):
(anyway it is not told so). It does not die if it is killed
the first time. It dies only when killed forcefully.
"""
- def kill(self, forcefull=False):
- killed.append(forcefull)
- if forcefull:
+ def kill(self, forceful=False):
+ killed.append(forceful)
+ if forceful:
bob.components = {}
def pid(self):
return 1
diff --git a/src/lib/python/isc/bind10/component.py b/src/lib/python/isc/bind10/component.py
index e4fb3ec..91b7064 100644
--- a/src/lib/python/isc/bind10/component.py
+++ b/src/lib/python/isc/bind10/component.py
@@ -119,7 +119,7 @@ class BaseComponent:
The extra parameters are:
- `process` - which program should be started.
- - `address` - the address on message buss, used to talk to the
+ - `address` - the address on message bus, used to talk to the
component.
- `params` - parameters to the program.
@@ -333,7 +333,7 @@ class BaseComponent:
"""
pass
- def kill(self, forcefull=False):
+ def kill(self, forceful=False):
"""
Kills the component.
@@ -453,7 +453,7 @@ class Configurator:
* `special` - Some components are started in a special way. If it is
present, it specifies which class from the specials parameter should
be used to create the component. In that case, some of the following
- items might be irrelevant, depending on the special component choosen.
+ items might be irrelevant, depending on the special component chosen.
If it is not there, the basic Component class is used.
* `process` - Name of the executable to start. If it is not present,
it defaults to the identifier of the component.
@@ -510,7 +510,7 @@ class Configurator:
It is not expected that anyone would want to shutdown and then start
the configurator again, so we don't explicitly make sure that would
- work. However, we are not avare of anything that would make it not
+ work. However, we are not aware of anything that would make it not
work either.
"""
if not self._running:
diff --git a/src/lib/python/isc/bind10/special_component.py b/src/lib/python/isc/bind10/special_component.py
index 1c8bc64..9972200 100644
--- a/src/lib/python/isc/bind10/special_component.py
+++ b/src/lib/python/isc/bind10/special_component.py
@@ -57,8 +57,8 @@ class SockCreator(BaseComponent):
"""
return self.__creator.pid() if self.__creator else None
- def kill(self, forcefull=False):
- # We don't really care about forcefull here
+ def kill(self, forceful=False):
+ # We don't really care about forceful here
if self.__creator:
self.__creator.kill()
@@ -135,7 +135,7 @@ class SetUID(BaseComponent):
posix.setuid(self.uid)
def _stop_internal(self): pass
- def kill(self, forcefull=False): pass
+ def kill(self, forceful=False): pass
def name(self):
return "Set UID"
diff --git a/src/lib/python/isc/bind10/tests/component_test.py b/src/lib/python/isc/bind10/tests/component_test.py
index 6bf9e58..7e18e60 100644
--- a/src/lib/python/isc/bind10/tests/component_test.py
+++ b/src/lib/python/isc/bind10/tests/component_test.py
@@ -673,7 +673,7 @@ class TestComponent(BaseComponent):
def _failed_internal(self):
self.log('failed')
- def kill(self, forcefull=False):
+ def kill(self, forceful=False):
self.log('killed')
class FailComponent(BaseComponent):
More information about the bind10-changes
mailing list