expanded treatment of rndc.key;

mentioned rndc-confgen (briefly) [RT #1520]

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.153 2001/08/06 04:42:24 marka Exp $ -->
+<!-- File: $Id: Bv9ARM-book.xml,v 1.154 2001/08/06 11:50:13 gson Exp $ -->
 
 <book>
 <title>BIND 9 Administrator Reference Manual</title>
@@ -813,7 +813,11 @@ configuration file.  The default location for the
 location can be specified with the <option>-c</option>
 option.  If the configuration file is not found,
 <command>rndc</command> will also look in
-<filename>/etc/rndc.key</filename> to find a key to use
+<filename>/etc/rndc.key</filename> (or whatever
+<varname>sysconfdir</varname> was defined when
+the <acronym>BIND</acronym> build was configured).
+The <filename>rndc.key</filename> file is generated by
+running <command>rndc-confgen -a</command> as described in
 <xref linkend="controls_statement_definition_and_usage"/>.</para>
 
 <para>The format of the configuration file is similar to
@@ -882,11 +886,22 @@ to reload, if a nameserver on the local machine were running with
 following controls statements:</para>
 <programlisting>
 controls {
-                inet 127.0.0.1 allow { localhost; } keys { rndc_key; };
+        inet 127.0.0.1 allow { localhost; } keys { rndc_key; };
 };
 </programlisting>
 <para>and it had an identical key statement for
 <literal>rndc_key</literal>.</para>
+
+<para>Running the <command>rndc-confgen</command> program will
+conveniently create a <filename>rndc.conf</filename>
+file for you, and also display the
+corresponding <command>controls</command> statement that you need to
+add to <filename>named.conf</filename>.  Alternatively,
+you can run <command>rndc-confgen -a</command> to set up
+a <filename>rndc.key</filename> file and not modify 
+<filename>named.conf</filename> at all.
+</para>
+
             </listitem>
           </varlistentry>
         </variablelist>
@@ -2204,26 +2219,43 @@ the system has an interface.</para></entry>
       must be signed by one of its specified keys to
       be honored.</para>
 
-      <para>If <command>keys</command> clause does not exist
-      <command>named</command> will look for
-      <filename>/etc/rndc.key</filename> and use the key found
-      there.
-
-      <para>Similarly, <filename>/etc/rndc.key.key</filename> is used
-      no <command>controls</command> statement is present at all.  In
-      that situation it will configure control channels to run on
-      all interfaces.</para>
+<para>
+If no <command>controls</command> statement is present,
+<command>named</command> will set up a default
+control channel listening on the loopback address 127.0.0.1
+and its IPv6 counterpart ::1.
+
+In this case, and also when the <command>controls</command> statement
+is present but does not have a <command>keys</command> clause,
+<command>named</command> will attempt to load the command channel key
+from the file <filename>rndc.key</filename> in
+<filename>/etc</filename> (or whatever <varname>sysconfdir</varname>
+was specified as when <acronym>BIND</acronym> was built).
+To create a <filename>rndc.key</filename> file, run
+<userinput>rndc-confgen -a</userinput>.
+</para>
 
-      <para>The <filename>/etc/rndc.key</filename> feature was created to
+      <para>The <filename>rndc.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
+      and thus did not have a <command>keys</command> clause.
+
+It makes it possible to use an existing <acronym>BIND</acronym> 8
+configuration file in <acronym>BIND</acronym> 9 unchanged,
+and still have <command>rndc</command> work the same way
+<command>ndc</command> worked in BIND 8, simply by executing the
+command <userinput>rndc-keygen -a</userinput> after BIND 9 is
+installed.
+</para>
+
+      <para>
+      Since the <filename>rndc.key</filename> feature
+      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>/etc/rndc.key</filename> file also has its
+      those things.  The <filename>rndc.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