Commit c1171699 authored by Jeremy C. Reed's avatar Jeremy C. Reed
Browse files

Merge remote-tracking branch 'origin/trac1341'

parents f76fdc8d 8f5429e4
......@@ -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>&gt; <userinput>config remove Boss/components b10-xfrout</userinput>
&gt; <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>&gt; <userinput>config add Boss/components b10-resolver</userinput>
&gt; <userinput>config set Boss/components/b10-resolver/special resolver</userinput>
&gt; <userinput>config set Boss/components/b10-resolver/kind needed</userinput>
&gt; <userinput>config set Boss/components/b10-resolver/priority 10</userinput>
&gt; <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>
&gt; <userinput>config set Boss/start_auth false</userinput>
&gt; <userinput>config set Boss/start_resolver true</userinput>
&gt; <userinput>config remove Boss/components b10-xfrout</userinput>
&gt; <userinput>config remove Boss/components b10-xfrin</userinput>
&gt; <userinput>config remove Boss/components b10-auth</userinput>
&gt; <userinput>config add Boss/components b10-resolver</userinput>
&gt; <userinput>config set Boss/components/b10-resolver/special resolver</userinput>
&gt; <userinput>config set Boss/components/b10-resolver/kind needed</userinput>
&gt; <userinput>config set Boss/components/b10-resolver/priority 10</userinput>
&gt; <userinput>config commit</userinput>
</screen>
......
......@@ -20,7 +20,7 @@
<refentry>
<refentryinfo>
<date>August 11, 2011</date>
<date>November 23, 2011</date>
</refentryinfo>
<refmeta>
......@@ -217,6 +217,204 @@ The default is the basename of ARG 0.
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>
......
......@@ -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.
......
......@@ -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
......
......@@ -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:
......
......@@ -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"
......
......@@ -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):
......
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