describe how command channel autoconfiguration works

diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index bde6477f4e2edad07e7b2b3fc3008a94ec85ed84..fe60134d14cbe00485643a47bc699f4d25227f4e 100644 (file)
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
                "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
 
-<!-- File: $Id: Bv9ARM-book.xml,v 1.136 2001/05/28 05:17:05 marka Exp $ -->
+<!-- File: $Id: Bv9ARM-book.xml,v 1.137 2001/05/31 11:01:29 tale Exp $ -->
 
 <book>
 <title>BIND 9 Administrator Reference Manual</title>
@@ -806,7 +806,14 @@ of a server.</para>
               <command>rndc</command> configuration file is
               <filename>/etc/rndc.conf</filename>, but an alternate
               location can be specified with the <option>-c</option>
-              option.</para>
+              option.  If the configuration file is not found,
+              <command>rndc</command> will also look in
+              <filename>/var/run/named.key</filename> (or wherever
+              <varname>localstatedir</varname> was defined when
+              the <acronym>BIND</acroynm> build was configured).
+              The <filename>named.key</filename> file is generated by
+              <command>named</command> as described in
+              <xref linkend="controls_statement_definition_and_usage">.</para>
 
               <para>The format of the configuration file is similar to
               that of <filename>named.conf</filename>, but limited to
@@ -979,7 +986,7 @@ reload the database. </para></entry>
     <para>The incremental zone transfer (IXFR) protocol is a way for
     slave servers to transfer only changed data, instead of having to
     transfer the entire zone. The IXFR protocol is documented in RFC
-    1995. See <xref linkend="proposed_standards"/></para>
+    1995. See <xref linkend="proposed_standards"/>.</para>
 
 <para>When acting as a master, <acronym>BIND</acronym> 9 supports IXFR for those zones
 where the necessary change history information is available. These
@@ -2147,7 +2154,7 @@ the system has an interface.</para></entry>
 };
 </programlisting>
     </sect2>
-    <sect2>
+    <sect2 id="controls_statement_definition_and_usage">
       <title><command>controls</command> Statement Definition and
 Usage</title>
 
@@ -2180,6 +2187,45 @@ Usage</title>
       must be signed by one of its specified keys to
       be honored.</para>
 
+      <para>The <command>keys</command> clause is not strictly required.
+      If it is not present, then a random key will be generated automatically
+      and placed in a file named <filename>named.key</filename>, which is
+      usually in <filename>/var/run</filename> but will be wherever
+      <varname>localstatedir</varname> was specified as when
+      <acronym>BIND</acronym> was built.  <filename>named.key</filename>
+      contains a complete <filename>rndc.conf</filename>-compatible
+      configuration and is used by <command>rndc</command> when it
+      cannot find its primary configuration file.</para>
+
+      <para>Similarly, <filename>named.key</filename> is generated when
+      no <command>controls</command> statement is present at all.  In
+      that situation it will configure a control channel to run on
+      127.0.0.1.</para>
+
+      <para>There are two ways to disable the creation of
+      <filename>named.key</filename>.  One is to ensure that all of your
+      <command>inet</command> control channels have a <command>keys</command>
+      clause.  The other is to have a <command>controls</command> statement
+      with no <command>inet</command> phrases it all.  The latter will
+      prevent the creation of any control channel</para>.
+
+      <para>The <filename>named.key</filename> feature was created to
+      ease the transition of systems from <acronym>BIND</acronym> 8,
+      which did not have digital signatures on its command channel messages
+      and thus did not have a <command>keys</command> clause.  Since
+      it is only intended to allow the backward-compatible usage of
+      <acronym>BIND</acronym> 8 configuration files, this feature does not
+      have a high degree of configurability.  You cannot easily change
+      the key name or the size of the secret, so you should make a
+      <filename>rndc.conf</filename> with your own key if you wish to change
+      those things.  The <filename>named.key</filename> file also has its
+      permissions set such that only the owner of the file (the user that
+      <command>named</command> is running as) can access it.  If you
+      desire greater flexibility in allowing other users to access
+      <command>rndc</command> commands then you need to create an
+      <filename>rndc.conf</filename> and make it group readable by a group
+      that contains the users who should have access.</para>
+
       <para>The UNIX control channel type of <acronym>BIND</acronym> 8 is not supported
       in <acronym>BIND</acronym> 9.0.0, and is not expected to be added in future
       releases.  If it is present in the controls statement from a