Commit cd4fd339 authored by Michal 'vorner' Vaner's avatar Michal 'vorner' Vaner
Browse files

[1341] Added boss components to docbook

parent 936e61c7
......@@ -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,21 +718,23 @@ 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.
about other modules. The <command>b10-sockcreator</command> will
allocate sockets for the rest of the system.
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,
and <command>b10-zonemgr</command> for secondary service.
and <command>b10-zonemgr</command> for secondary service in the
default configuration.
</para>
<section id="start">
......@@ -754,6 +756,139 @@ 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 imediatelly
(and not started on the next startup):
<screen>&gt; <userinput>config del 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 "dispensable" (the default unless you set something
else), it will get started again if it fails. If it is set to
"needed" and it fails at startup, the whole bind10 shuts down and exits
with error exit code. But if it failes some time later, it is just
started again. If you set it to "core", you indicate that the system
is not useable 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
lover ones. If you don't set it, 0 is used as the priority.
</para>
<para>
There are other parameters we didn't use in our example.
One of them is "address". It is the address used by the component
on the b10-msgq message buss. The special components already know
their address, but the usual ones don't. The address is by convention
the thing after b10-, with the first letter capital (eg. b10-stats
would have Stats as its address).
</para>
<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 b10-cmdctl, 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 -- b10-stats-http need
b10-stats, b10-xfrout needs the b10-auth to be running, etc.
</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 bind10 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). So we need to specify
the time when the switch from root do the given user happens and that's
whath 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, b10-auth
has 10 to be started before the switch and everything else is without
priority, so it is started after the switch.
</para>
</section>
</chapter>
......@@ -1442,8 +1577,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 del Boss/components b10-xfrout</userinput>
&gt; <userinput>config del Boss/components b10-xfrin</userinput>
&gt; <userinput>config del 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>
......
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