[1341] Added boss components to docbook

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,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
+      system, <command>b10-auth</command> for authoritative DNS service,
-      <command>b10-resolver</command> for recursive name 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 del Boss/components b10-xfrout</userinput>
-&gt; <userinput>config set Boss/start_resolver true</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>