Browse Source

[1341] Added boss components to docbook

Michal 'vorner' Vaner 13 years ago
parent
commit
cd4fd339a0
1 changed files with 148 additions and 8 deletions
  1. 148 8
      doc/guide/bind10-guide.xml

+ 148 - 8
doc/guide/bind10-guide.xml

@@ -706,7 +706,7 @@ Debian and Ubuntu:
       BIND 10 provides the <command>bind10</command> command which
       BIND 10 provides the <command>bind10</command> command which
       starts up the required processes.
       starts up the required processes.
       <command>bind10</command>
       <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.
       This is the only command needed to start the BIND 10 system.
     </para>
     </para>
 
 
@@ -718,21 +718,23 @@ Debian and Ubuntu:
     </para>
     </para>
 
 
     <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
       services make up the core. The <command>b10-msgq</command> daemon
       provides the communication channel between every part of the system.
       provides the communication channel between every part of the system.
       The <command>b10-cfgmgr</command> daemon is always needed by every
       The <command>b10-cfgmgr</command> daemon is always needed by every
       module, if only to send information about themselves somewhere,
       module, if only to send information about themselves somewhere,
       but more importantly to ask about their own settings, and
       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
       The <command>bind10</command> master process will also start up
       <command>b10-cmdctl</command> for admins to communicate with the
       <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-stats</command> for statistics collection,
       <command>b10-xfrin</command> for inbound DNS zone transfers,
       <command>b10-xfrin</command> for inbound DNS zone transfers,
       <command>b10-xfrout</command> for outbound 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>
     </para>
 
 
     <section id="start">
     <section id="start">
@@ -754,6 +756,139 @@ Debian and Ubuntu:
       </note>
       </note>
 
 
     </section>
     </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>
   </chapter>
 
 
@@ -1442,8 +1577,13 @@ what is XfroutClient xfr_client??
       You may change this using <command>bindctl</command>, for example:
       You may change this using <command>bindctl</command>, for example:
 
 
       <screen>
       <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>
 &gt; <userinput>config commit</userinput>
 </screen>
 </screen>