BIND 10 master, updated. 6b937eae7c5681857e0ce74bfee392f19890001b [master] few minor formatting changes
BIND 10 source code commits
bind10-changes at lists.isc.org
Wed Nov 14 15:14:57 UTC 2012
The branch, master has been updated
via 6b937eae7c5681857e0ce74bfee392f19890001b (commit)
via d42376ab7473a4af01c74db5f5a4ad35c66f8d52 (commit)
via 71eee20bd4e2688770303a8c51ea895916f49c75 (commit)
from e4fe372ea63d2115ca2e15866f0ef032fb05e0ca (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 6b937eae7c5681857e0ce74bfee392f19890001b
Author: Jeremy C. Reed <jreed at isc.org>
Date: Wed Nov 14 09:14:18 2012 -0600
[master] few minor formatting changes
not reviewed, very minor
change some docbook tags
move some example prompts for formatting
commit d42376ab7473a4af01c74db5f5a4ad35c66f8d52
Author: Jeremy C. Reed <jreed at isc.org>
Date: Wed Nov 14 08:54:39 2012 -0600
[master] split the starting bind10 chapter into two chapters
This split is done so the bindctl chapter comes before
the chapter on using bindctl to configure Boss/components.
Discussed via jabber and in ticket #2305.
Also added some brief content on how to stop bind10 and how to list
processes.
commit 71eee20bd4e2688770303a8c51ea895916f49c75
Author: Jeremy C. Reed <jreed at isc.org>
Date: Wed Nov 14 08:27:06 2012 -0600
[master] split quick start section into its own chapter
It adds a step to enable the auth server. Some other minor changes too.
This was not reviewed, but has very little content changes.
-----------------------------------------------------------------------
Summary of changes:
doc/guide/bind10-guide.xml | 535 ++++++++++++++++++++++++--------------------
1 file changed, 294 insertions(+), 241 deletions(-)
-----------------------------------------------------------------------
diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index e0266e1..675414f 100644
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -367,6 +367,105 @@ var/
</chapter>
+ <chapter id="quickstart">
+ <title>Quick start</title>
+
+ <para>
+ This quickly covers the standard steps for installing
+ and deploying BIND 10.
+ For further details, full customizations, and troubleshooting,
+ see the respective chapters in the BIND 10 guide.
+ </para>
+
+ <section id="quick-start-auth-dns">
+ <title>Quick start guide for authoritative DNS service</title>
+
+ <orderedlist>
+
+ <listitem>
+ <simpara>
+ Install required run-time and build dependencies.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ Download the BIND 10 source tar file from
+ <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <para>Extract the tar file:
+ <screen>$ <userinput>gzcat bind10-<replaceable>VERSION</replaceable>.tar.gz | tar -xvf -</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Go into the source and run configure:
+ <screen>$ <userinput>cd bind10-<replaceable>VERSION</replaceable></userinput>
+ $ <userinput>./configure</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Build it:
+ <screen>$ <userinput>make</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Install it as root (to default /usr/local):
+ <screen>$ <userinput>make install</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Start the server (as root):
+ <screen>$ <userinput>/usr/local/sbin/bind10</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>In another console, enable the authoritative DNS service
+ (by using the <command>bindctl</command> utility to configure
+ the <command>b10-auth</command> component to run):
+ <screen>$ <userinput>bindctl</userinput></screen>
+ (Login with the provided default username and password.)
+ <screen>
+> <userinput>config add Boss/components b10-auth</userinput>
+> <userinput>config set Boss/components/b10-auth/special auth</userinput>
+> <userinput>config set Boss/components/b10-auth/kind needed</userinput>
+> <userinput>config commit</userinput>
+> <userinput>quit</userinput>
+ </screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Test it; for example:
+ <screen>$ <userinput>dig @127.0.0.1 -c CH -t TXT version.bind</userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Load desired zone file(s), for example:
+ <screen>$ <userinput>b10-loadzone <replaceable>your.zone.example.org</replaceable></userinput></screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ Test the new zone.
+ </simpara>
+ </listitem>
+
+ </orderedlist>
+
+ </section>
+
+ </chapter>
+
<chapter id="installation">
<title>Installation</title>
@@ -514,90 +613,6 @@ as a dependency earlier -->
</section>
- <section id="quickstart">
- <title>Quick start</title>
- <note>
- <simpara>
- This quickly covers the standard steps for installing
- and deploying BIND 10 as an authoritative name server using
- its defaults. For troubleshooting, full customizations and further
- details, see the respective chapters in the BIND 10 guide.
- </simpara>
- </note>
-
- <para>
- To quickly get started with BIND 10, follow these steps.
- </para>
-
- <orderedlist>
-
- <listitem>
- <simpara>
- Install required run-time and build dependencies.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- Download the BIND 10 source tar file from
- <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
- </simpara>
- </listitem>
-
- <listitem>
- <para>Extract the tar file:
- <screen>$ <userinput>gzcat bind10-<replaceable>VERSION</replaceable>.tar.gz | tar -xvf -</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <para>Go into the source and run configure:
- <screen>$ <userinput>cd bind10-<replaceable>VERSION</replaceable></userinput>
- $ <userinput>./configure</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <para>Build it:
- <screen>$ <userinput>make</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <para>Install it (to default /usr/local):
- <screen>$ <userinput>make install</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <para>Start the server:
- <screen>$ <userinput>/usr/local/sbin/bind10</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
-<!-- TODO: this is wrong; b10-auth is not started by default any more -->
- <para>Test it; for example:
- <screen>$ <userinput>dig @127.0.0.1 -c CH -t TXT authors.bind</userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <para>Load desired zone file(s), for example:
- <screen>$ <userinput>b10-loadzone <replaceable>your.zone.example.org</replaceable></userinput></screen>
- </para>
- </listitem>
-
- <listitem>
- <simpara>
- Test the new zone.
- </simpara>
- </listitem>
-
- </orderedlist>
-
- </section>
-
<section id="install">
<title>Installation from source</title>
<para>
@@ -820,16 +835,25 @@ as a dependency earlier -->
<command>b10-cmdctl</command> for administration tools to
communicate with the system, and
<command>b10-stats</command> for statistics collection.
+ The configuration of components to start is covered in
+ <xref linkend="bind10.components"/>.
</para>
<section id="start">
<title>Starting BIND 10</title>
<para>
- To start the BIND 10 service, simply run <command>bind10</command>.
+ To start the BIND 10 service, simply run <command>bind10</command>
+ as root.
+ It will run in the foreground and your shell prompt will not
+ be available. It will output various log messages as it starts up
+ and is used.
Run it with the <option>--verbose</option> switch to
get additional debugging or diagnostic output.
</para>
-<!-- TODO: note it doesn't go into background -->
+
+<!-- TODO: user switch -->
+
+<!-- TODO: example: nohup /usr/local/sbin/bind10 1>bind10.log 2>&1 -->
<note>
<para>
@@ -841,156 +865,6 @@ as a dependency earlier -->
</note>
</section>
- <section id="bind10.config">
- <title>Configuration to start processes</title>
-
- <para>
- The processes to be used can be configured for
- <command>bind10</command> to start, with the exception
- of the required <command>b10-sockcreator</command>,
- <command>b10-msgq</command> and <command>b10-cfgmgr</command>
- components.
- The configuration is in the <varname>Boss/components</varname>
- section. Each element represents one component, which is
- an abstraction of a process.
- </para>
-
- <para>
- To add a process to the set, let's say the resolver (which
- is not started by default), you would do this:
- <screen>> <userinput>config add Boss/components b10-resolver</userinput>
-> <userinput>config set Boss/components/b10-resolver/special resolver</userinput>
-> <userinput>config set Boss/components/b10-resolver/kind needed</userinput>
-> <userinput>config set Boss/components/b10-resolver/priority 10</userinput>
-> <userinput>config commit</userinput></screen></para>
-
- <para>
- Now, what it means. We add an entry called
- <quote>b10-resolver</quote>. 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 <varname>special</varname> setting is for components
- that need some kind of special care during startup or
- shutdown. Unless specified, the component is started in a
- 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:
-<!-- TODO: this still doesn't explain why they are special -->
- <table>
- <title>Special startup components</title>
- <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 DNS server</entry></row>
- <row><entry>b10-resolver</entry><entry>resolver</entry><entry>DNS resolver</entry></row>
- <row><entry>b10-cmdctl</entry><entry>cmdctl</entry><entry>Command control (remote control interface)</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 <varname>kind</varname> 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 an 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 <varname>priority</varname> defines order in which the
- components should start. The ones with higher numbers are
- started sooner than the ones with lower ones. If you don't
- set it, 0 (zero) is used as the priority. Usually, leaving
- it at the default is enough.
- </para>
-
- <para>
- There are other parameters we didn't use in our example.
- One of them is <varname>address</varname>. 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 capitalized (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 <varname>process</varname>. 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. (The special components also already know their
- executable name.)
- </para>
-
- <!-- TODO Add parameters when they work, not implemented yet-->
-
- <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> needs
- <command>b10-stats</command>, <command>b10-xfrout</command>
- needs <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>
- It is possible to start some components multiple times (currently
- <command>b10-auth</command> and <command>b10-resolver</command>).
- You might want to do that to gain more performance (each one uses only
- single core). Just put multiple entries under different names, like
- this, with the same config:
- <screen>> <userinput>config add Boss/components b10-resolver-2</userinput>
-> <userinput>config set Boss/components/b10-resolver-2/special resolver</userinput>
-> <userinput>config set Boss/components/b10-resolver-2/kind needed</userinput>
-> <userinput>config commit</userinput></screen>
- </para>
- <para>
- However, this is work in progress and the support is not yet complete.
- For example, each resolver will have its own cache, each authoritative
- server will keep its own copy of in-memory data and there could be
- problems with locking the sqlite database, if used. The configuration
- might be changed to something more convenient in future.
- Other components don't expect such a situation, so it would
- probably not do what you want. Such support is yet to be
- implemented.
- </para>
- </section>
</chapter>
@@ -1374,7 +1248,7 @@ TODO
For example, the Boss module has a 'shutdown' command to shut down
BIND 10, with an optional argument 'help':
- <screen><userinput>> Boss shutdown help</userinput>
+ <screen>> <userinput>Boss shutdown help</userinput>
Command shutdown (Shut down BIND 10)
help (Get help for command)
This command has no parameters
@@ -1827,7 +1701,7 @@ config set /Boss/components/b10-zonemgr/kind dispensable
The optional <command>show</command> argument may also be used when
executing a script from a file; for example:
- <screen><userinput>> execute file /tmp/example_commands show</userinput></screen>
+ <screen>> <userinput>execute file /tmp/example_commands show</userinput></screen>
<section id="bindctl_execute_directives">
<title>Execute directives</title>
@@ -2175,6 +2049,185 @@ AND_MATCH := "ALL": [ RULE_RAW, RULE_RAW, ... ]
</section>
</chapter>
+ <chapter id="bind10.config">
+ <title>bind10 Control and Configuration</title>
+
+ <para>
+ This chapter explains how to control and configure the
+ <command>bind10</command> parent.
+ The startup of this resident process that runs the BIND 10
+ daemons is covered in <xref linkend="bind10"/>.
+ </para>
+
+ <section id="bind10.shutdown">
+ <title>Stopping bind10</title>
+ <para>
+ The BIND 10 suite may be shut down by stopping the
+ parent <command>bind10</command> process. This may be done
+ by running the <userinput>Boss shutdown</userinput> command
+ at the <command>bindctl</command> prompt.
+ </para>
+ </section>
+
+ <section id="bind10.components">
+ <title>Configuration to start processes</title>
+
+ <para>
+ The processes to be used can be configured for
+ <command>bind10</command> to start, with the exception
+ of the required <command>b10-sockcreator</command>,
+ <command>b10-msgq</command> and <command>b10-cfgmgr</command>
+ components.
+ The configuration is in the <varname>Boss/components</varname>
+ section. Each element represents one component, which is
+ an abstraction of a process.
+ </para>
+
+ <para>
+ To add a process to the set, let's say the resolver (which
+ is not started by default), you would do this:
+ <screen>> <userinput>config add Boss/components b10-resolver</userinput>
+> <userinput>config set Boss/components/b10-resolver/special resolver</userinput>
+> <userinput>config set Boss/components/b10-resolver/kind needed</userinput>
+> <userinput>config set Boss/components/b10-resolver/priority 10</userinput>
+> <userinput>config commit</userinput></screen></para>
+
+ <para>
+ Now, what it means. We add an entry called
+ <quote>b10-resolver</quote>. 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 <varname>special</varname> setting is for components
+ that need some kind of special care during startup or
+ shutdown. Unless specified, the component is started in a
+ 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:
+<!-- TODO: this still doesn't explain why they are special -->
+ <table>
+ <title>Special startup components</title>
+ <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 DNS server</entry></row>
+ <row><entry>b10-resolver</entry><entry>resolver</entry><entry>DNS resolver</entry></row>
+ <row><entry>b10-cmdctl</entry><entry>cmdctl</entry><entry>Command control (remote control interface)</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 <varname>kind</varname> 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 an 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 <varname>priority</varname> defines order in which the
+ components should start. The ones with higher numbers are
+ started sooner than the ones with lower ones. If you don't
+ set it, 0 (zero) is used as the priority. Usually, leaving
+ it at the default is enough.
+ </para>
+
+ <para>
+ There are other parameters we didn't use in our example.
+ One of them is <varname>address</varname>. 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 capitalized (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 <varname>process</varname>. 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. (The special components also already know their
+ executable name.)
+ </para>
+
+ <!-- TODO Add parameters when they work, not implemented yet-->
+
+ <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> needs
+ <command>b10-stats</command>, <command>b10-xfrout</command>
+ needs <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>
+ It is possible to start some components multiple times (currently
+ <command>b10-auth</command> and <command>b10-resolver</command>).
+ You might want to do that to gain more performance (each one uses only
+ single core). Just put multiple entries under different names, like
+ this, with the same config:
+ <screen>> <userinput>config add Boss/components b10-resolver-2</userinput>
+> <userinput>config set Boss/components/b10-resolver-2/special resolver</userinput>
+> <userinput>config set Boss/components/b10-resolver-2/kind needed</userinput>
+> <userinput>config commit</userinput></screen>
+ </para>
+ <para>
+ However, this is work in progress and the support is not yet complete.
+ For example, each resolver will have its own cache, each authoritative
+ server will keep its own copy of in-memory data and there could be
+ problems with locking the sqlite database, if used. The configuration
+ might be changed to something more convenient in future.
+ Other components don't expect such a situation, so it would
+ probably not do what you want. Such support is yet to be
+ implemented.
+ </para>
+
+ <para>
+ The running processes started by <command>bind10</command>
+ may be listed by running <userinput>Boss show_processes</userinput>
+ using <command>bindctl</command>.
+ </para>
+
+ </section>
+ </chapter>
+
<chapter id="authserver">
<title>Authoritative Server</title>
@@ -2654,8 +2707,8 @@ TODO
<para>
As noted above, <command>b10-xfrin</command> uses AXFR for
zone transfers by default. To enable IXFR for zone transfers
- for a particular zone, set the <userinput>use_ixfr</userinput>
- configuration parameter to <userinput>true</userinput>.
+ for a particular zone, set the <varname>use_ixfr</varname>
+ configuration parameter to <quote>true</quote>.
In the above example of configuration sequence, you'll need
to add the following before performing <userinput>commit</userinput>:
<screen>> <userinput>config set Xfrin/zones[0]/use_ixfr true</userinput></screen>
@@ -4246,7 +4299,7 @@ Logging/loggers [] list
<!-- TODO: adding the empty loggers makes no sense -->
<para>
- <screen><userinput>> config add Logging/loggers</userinput>
+ <screen>> <userinput>config add Logging/loggers</userinput>
> <userinput>config show Logging</userinput>
Logging/loggers/ list (modified)
</screen>
More information about the bind10-changes
mailing list