From cd4fd339a084dbfb1e2d35d5c008260de9d48572 Mon Sep 17 00:00:00 2001 From: Michal 'vorner' Vaner Date: Tue, 15 Nov 2011 14:06:07 +0100 Subject: [PATCH] [1341] Added boss components to docbook --- doc/guide/bind10-guide.xml | 156 +++++++++++++++++++++++++++++++++++-- 1 file changed, 148 insertions(+), 8 deletions(-) diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml index 21bb671efb..26fc86ac52 100644 --- a/doc/guide/bind10-guide.xml +++ b/doc/guide/bind10-guide.xml @@ -706,7 +706,7 @@ Debian and Ubuntu: BIND 10 provides the bind10 command which starts up the required processes. bind10 - 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. @@ -718,21 +718,23 @@ Debian and Ubuntu: - The b10-msgq and b10-cfgmgr + The b10-sockcreator, b10-msgq and + b10-cfgmgr services make up the core. The b10-msgq daemon provides the communication channel between every part of the system. The b10-cfgmgr 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 b10-sockcreator will + allocate sockets for the rest of the system. The bind10 master process will also start up b10-cmdctl for admins to communicate with the - system, b10-auth for authoritative DNS service or - b10-resolver for recursive name service, + system, b10-auth for authoritative DNS service, b10-stats for statistics collection, b10-xfrin for inbound DNS zone transfers, b10-xfrout for outbound DNS zone transfers, - and b10-zonemgr for secondary service. + and b10-zonemgr for secondary service in the + default configuration.
@@ -754,6 +756,139 @@ Debian and Ubuntu:
+
+ Configuration of started processes + + The processes to be started can be configured, with the exception + of the b10-sockcreator, b10-msgq + and b10-cfgmgr. + + + + 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): + > config del Boss/components b10-xfrout +> config commit + + + + To add a process to the set, let's say the resolver (which not started + by default), you would do this: + > config add Boss/components b10-resolver +> config set Boss/components/b10-resolver/special resolver +> config set Boss/components/b10-resolver/kind needed +> config set Boss/components/b10-resolver/priority 10 +> config commit + + + 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. + + + + 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: + + + + + + ComponentSpecialDescription + + b10-authauthAuthoritative server + b10-resolverresolverThe resolver + b10-cmdctlcmdctlThe command control (remote control interface) + setuidsetuidVirtual component, see below + + + +
+ + + + 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). + + + + 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. + + + + 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). + + + + 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. + + + + + + + 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. + + + + + + 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. + + + In short, you should think twice before disabling something here. + + + + + Now, to the mysterious setuid virtual component. If you use the -u + option to start the bind10 as root, but change the user later, we need + to start the b10-auth or b10-resolver + 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. + + +
@@ -1442,8 +1577,13 @@ what is XfroutClient xfr_client?? You may change this using bindctl, for example: -> config set Boss/start_auth false -> config set Boss/start_resolver true +> config del Boss/components b10-xfrout +> config del Boss/components b10-xfrin +> config del Boss/components b10-auth +> config add Boss/components b10-resolver +> config set Boss/components/b10-resolver/special resolver +> config set Boss/components/b10-resolver/kind needed +> config set Boss/components/b10-resolver/priority 10 > config commit