[master]Merge branch 'jreed-docs-2'

manually edited conflicts in doc/guide/bind10-guide.xml

doc/guide/bind10-guide.xml

@@ -241,7 +241,7 @@
 
     <section id="managing_once_running">
       <title>Managing BIND 10</title>
-      
+
       <para>
 	Once BIND 10 is running, a few commands are used to interact
 	directly with the system:
@@ -280,7 +280,7 @@
 <!-- TODO point to these -->
       In addition, manual pages are also provided in the default installation.
     </para>
-      
+
 <!--
 bin/
   bindctl*
@@ -387,7 +387,7 @@ Debian and Ubuntu:
       </para>
 
       <orderedlist>
-    
+
         <listitem>
           <simpara>
             Install required build dependencies.
@@ -471,7 +471,7 @@ Debian and Ubuntu:
           Downloading a release tar file is the recommended method to
           obtain the source code.
         </para>
-        
+
         <para>
           The BIND 10 releases are available as tar file downloads from
           <ulink url="ftp://ftp.isc.org/isc/bind10/"/>.
@@ -550,34 +550,34 @@ Debian and Ubuntu:
               <simpara>Define the installation location (the
                 default is <filename>/usr/local/</filename>).
               </simpara>
-            </listitem> 
+            </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>--with-boost-include</term>
-            <listitem> 
+            <listitem>
               <simpara>Define the path to find the Boost headers.
               </simpara>
-            </listitem> 
+            </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>--with-pythonpath</term>
-            <listitem> 
+            <listitem>
               <simpara>Define the path to Python 3.1 if it is not in the
                 standard execution path.
               </simpara>
-            </listitem> 
+            </listitem>
           </varlistentry>
 
           <varlistentry>
             <term>--with-gtest</term>
-            <listitem> 
+            <listitem>
               <simpara>Enable building the C++ Unit Tests using the
                 Google Tests framework. Optionally this can define the
                 path to the gtest header files and library.
               </simpara>
-            </listitem> 
+            </listitem>
           </varlistentry>
 
           </variablelist>
@@ -696,13 +696,13 @@ Debian and Ubuntu:
         </para>
       </section>
   -->
-  
+
   </chapter>
 
   <chapter id="bind10">
     <title>Starting BIND10 with <command>bind10</command></title>
     <para>
-      BIND 10 provides the <command>bind10</command> command which 
+      BIND 10 provides the <command>bind10</command> command which
       starts up the required processes.
       <command>bind10</command>
       will also restart processes that exit unexpectedly.
@@ -711,7 +711,7 @@ Debian and Ubuntu:
 
     <para>
       After starting the <command>b10-msgq</command> communications channel,
-      <command>bind10</command> connects to it, 
+      <command>bind10</command> connects to it,
       runs the configuration manager, and reads its own configuration.
       Then it starts the other modules.
     </para>
@@ -779,7 +779,7 @@ Debian and Ubuntu:
         <command>b10-msgq</command> service.
         It listens on 127.0.0.1.
       </para>
-      
+
 <!-- TODO: this is broken, see Trac #111
       <para>
         To select an alternate port for the <command>b10-msgq</command> to
@@ -1105,10 +1105,10 @@ since we used bind10 -->
         The configuration data item is:
 
         <variablelist>
-    
+
           <varlistentry>
             <term>database_file</term>
-            <listitem> 
+            <listitem>
               <simpara>This is an optional string to define the path to find
                  the SQLite3 database file.
 <!-- TODO: -->
@@ -1130,7 +1130,7 @@ This may be a temporary setting until then.
 
           <varlistentry>
             <term>shutdown</term>
-            <listitem> 
+            <listitem>
               <simpara>Stop the authoritative DNS server.
               </simpara>
 <!-- TODO: what happens when this is sent, will bind10 restart? -->
@@ -1186,7 +1186,7 @@ This may be a temporary setting until then.
 
           <varlistentry>
             <term>$INCLUDE</term>
-            <listitem> 
+            <listitem>
               <simpara>Loads an additional zone file. This may be recursive.
               </simpara>
             </listitem>
@@ -1194,7 +1194,7 @@ This may be a temporary setting until then.
 
           <varlistentry>
             <term>$ORIGIN</term>
-            <listitem> 
+            <listitem>
               <simpara>Defines the relative domain name.
               </simpara>
             </listitem>
@@ -1202,7 +1202,7 @@ This may be a temporary setting until then.
 
           <varlistentry>
             <term>$TTL</term>
-            <listitem> 
+            <listitem>
               <simpara>Defines the time-to-live value used for following
                 records that don't include a TTL.
               </simpara>
@@ -1267,7 +1267,7 @@ TODO
 
     <note><simpara>
      The current development release of BIND 10 only supports
-     AXFR. (IXFR is not supported.) 
+     AXFR. (IXFR is not supported.)
 
 <!-- TODO: sqlite3 data source only? -->
 
@@ -1314,7 +1314,7 @@ what if a NOTIFY is sent?
 
     <note><simpara>
      The current development release of BIND 10 only supports
-     AXFR. (IXFR is not supported.) 
+     AXFR. (IXFR is not supported.)
      Access control is not yet provided.
     </simpara></note>
 
@@ -1402,6 +1402,67 @@ what is XfroutClient xfr_client??
 <!-- TODO: later the above will have some defaults -->
 
     <section>
+      <title>Access Control</title>
+
+      <para>
+        The <command>b10-resolver</command> daemon only accepts
+        DNS queries from the localhost (127.0.0.1 and ::1).
+        The <option>Resolver/query_acl</option> configuration may
+	be used to reject, drop, or allow specific IPs or networks.
+        This configuration list is first match.
+      </para>
+
+      <para>
+	The configuration's <option>action</option> item may be
+	set to <quote>ACCEPT</quote> to allow the incoming query,
+	<quote>REJECT</quote> to respond with a DNS REFUSED return
+	code, or <quote>DROP</quote> to ignore the query without
+	any response (such as a blackhole).  For more information,
+	see the respective debugging messages:  <ulink
+	url="bind10-messages.html#RESOLVER_QUERY_ACCEPTED">RESOLVER_QUERY_ACCEPTED</ulink>,
+	<ulink
+	url="bind10-messages.html#RESOLVER_QUERY_REJECTED">RESOLVER_QUERY_REJECTED</ulink>,
+	and <ulink
+url="bind10-messages.html#RESOLVER_QUERY_DROPPED">RESOLVER_QUERY_DROPPED</ulink>.
+      </para>
+
+      <para>
+	The required configuration's <option>from</option> item is set
+        to an IPv4 or IPv6 address, addresses with an network mask, or to
+	the special lowercase keywords <quote>any6</quote> (for
+	any IPv6 address) or <quote>any4</quote> (for any IPv4
+	address).
+      </para>
+
+<!-- TODO:
+/0 is for any address in that address family
+does that need any address too?
+-->
+
+      <para>
+	For example to allow the <replaceable>192.168.1.0/24</replaceable>
+	network to use your recursive name server, at the
+	<command>bindctl</command> prompt run:
+      </para>
+
+      <screen>
+&gt; <userinput>config add Resolver/query_acl</userinput>
+&gt; <userinput>config set Resolver/query_acl[<replaceable>2</replaceable>]/action "ACCEPT"</userinput>
+&gt; <userinput>config set Resolver/query_acl[<replaceable>2</replaceable>]/from "<replaceable>192.168.1.0/24</replaceable>"</userinput>
+&gt; <userinput>config commit</userinput>
+</screen>
+
+     <simpara>(Replace the <quote><replaceable>2</replaceable></quote>
+       as needed; run <quote><userinput>config show
+       Resolver/query_acl</userinput></quote> if needed.)</simpara>
+
+<!-- TODO: check this -->
+      <note><simpara>This prototype access control configuration
+      syntax may be changed.</simpara></note>
+
+    </section>
+
+    <section>
       <title>Forwarding</title>
 
       <para>

src/bin/auth/b10-auth.xml

@@ -20,7 +20,7 @@
 <refentry>
 
   <refentryinfo>
-    <date>March 8, 2011</date>
+    <date>August 11, 2011</date>
   </refentryinfo>
 
   <refmeta>
@@ -209,6 +209,34 @@
   </refsect1>
 
   <refsect1>
+    <title>STATISTICS DATA</title>
+
+    <para>
+      The statistics data collected by the <command>b10-stats</command>
+      daemon include:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>auth.queries.tcp</term>
+        <listitem><simpara>Total count of queries received by the
+          <command>b10-auth</command> server over TCP since startup.
+        </simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>auth.queries.udp</term>
+        <listitem><simpara>Total count of queries received by the
+          <command>b10-auth</command> server over UDP since startup.
+        </simpara></listitem>
+      </varlistentry>
+
+    </variablelist>
+
+  </refsect1>
+
+  <refsect1>
     <title>FILES</title>
     <para>
       <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>

src/bin/bind10/bind10.xml

@@ -2,7 +2,7 @@
                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 	       [<!ENTITY mdash "&#8212;">]>
 <!--
- - Copyright (C) 2010  Internet Systems Consortium, Inc. ("ISC")
+ - Copyright (C) 2010-2011  Internet Systems Consortium, Inc. ("ISC")
  -
  - Permission to use, copy, modify, and/or distribute this software for any
  - purpose with or without fee is hereby granted, provided that the above
@@ -20,7 +20,7 @@
 <refentry>
 
   <refentryinfo>
-    <date>March 31, 2011</date>
+    <date>August 11, 2011</date>
   </refentryinfo>
 
   <refmeta>
@@ -217,6 +217,30 @@ The default is the basename of ARG 0.
 <!--
 TODO: configuration section
 -->
+
+  <refsect1>
+    <title>STATISTICS DATA</title>
+
+    <para>
+      The statistics data collected by the <command>b10-stats</command>
+      daemon include:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>bind10.boot_time</term>
+        <listitem><para>
+          The date and time that the <command>bind10</command>
+          process started.
+          This is represented in ISO 8601 format.
+        </para></listitem>
+      </varlistentry>
+
+    </variablelist>
+
+  </refsect1>
+
 <!--
   <refsect1>
     <title>FILES</title>

src/bin/stats/b10-stats.xml

@@ -20,7 +20,7 @@
 <refentry>
 
   <refentryinfo>
-    <date>Oct 15, 2010</date>
+    <date>August 11, 2011</date>
   </refentryinfo>
 
   <refmeta>
@@ -67,6 +67,7 @@
       it. <command>b10-stats</command> invokes "sendstats" command
       for <command>bind10</command> after its initial starting because it's
       sure to collect statistics data from <command>bind10</command>.
+<!-- TODO: reword that last sentence? -->
     </para>
   </refsect1>
 
@@ -87,6 +88,94 @@
   </refsect1>
 
   <refsect1>
+    <title>DEFAULT STATISTICS</title>
+
+    <para>
+      The <command>b10-stats</command> daemon contains
+      built-in statistics:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>report_time</term>
+<!-- TODO: why not named stats.report_time? -->
+        <listitem><simpara>The latest report date and time in
+          ISO 8601 format.</simpara></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>stats.timestamp</term>
+        <listitem><simpara>The current date and time represented in
+          seconds since UNIX epoch (1970-01-01T0 0:00:00Z) with
+          precision (delimited with a period) up to
+          one hundred thousandth of second.</simpara></listitem>
+      </varlistentry>
+
+<!-- TODO: document
+    "stats.boot_time": "2011-08-11T15:23:56Z",
+when started
+    "stats.last_update_time": "2011-08-11T15:23:56Z",
+when stats module last received data from other component
+    "stats.lname": "4e43f40c_15@t1.m.reedmedia.net",
+name used for msgq command-control channel
+    "stats.start_time": "2011-08-11T15:23:56Z",
+when starts collecting data
+-->
+
+<!-- TODO: document auth.foo and bind10.foo in their corresponding manuals -->
+
+    </variablelist>
+
+  </refsect1>
+
+  <refsect1>
+    <title>CONFIGURATION AND COMMANDS</title>
+
+    <para>
+      The <command>b10-stats</command> command does not have any
+      configurable settings.
+    </para>
+
+<!-- TODO: formating -->
+    <para>
+      The configuration commands are:
+    </para>
+
+    <para>
+      <command>remove</command> removes the named statistics data.
+    </para>
+
+    <para>
+      <command>reset</command>
+    </para>
+
+    <para>
+      <command>set</command>
+    </para>
+
+    <para>
+      <command>show</command> will send the statistics data
+      in JSON format.
+      By default, it outputs all the statistics data it has collected.
+      An optional item name may be specified to receive individual output.
+    </para>
+
+    <para>
+      <command>shutdown</command> will shutdown the
+      <command>b10-stats</command> process.
+      (Note that the <command>bind10</command> parent may restart it.)
+    </para>
+
+    <para>
+      <command>status</command> simply indicates that the daemon is
+      running.
+    </para>
+
+  </refsect1>
+
+
+  <refsect1>
     <title>FILES</title>
     <para><filename>/usr/local/share/bind10-devel/stats.spec</filename>
       <!--TODO: The filename should be computed from prefix-->
@@ -126,7 +215,7 @@
     <title>HISTORY</title>
     <para>
       The <command>b10-stats</command> daemon was initially designed
-      and implemented by Naoki Kambe of JPRS in Oct 2010.
+      and implemented by Naoki Kambe of JPRS in October 2010.
     </para>
   </refsect1>
 </refentry><!--

src/bin/xfrin/b10-xfrin.xml

@@ -103,6 +103,7 @@ in separate zonemgr process.
       <command>b10-xfrin</command> daemon.
       The list items are:
       <varname>name</varname> (the zone name),
+<!-- TODO: class string -->
       <varname>master_addr</varname> (the zone master to transfer from),
       <varname>master_port</varname> (defaults to 53), and
       <varname>tsig_key</varname> (optional TSIG key to use).

src/bin/xfrout/b10-xfrout.xml

@@ -134,6 +134,14 @@
       data storage types.
     </simpara></note>
 
+
+<!--
+
+tsig_key_ring list of
+tsig_key string
+
+-->
+
 <!-- TODO: formating -->
     <para>
       The configuration commands are: