Browse Source

[2133] Update the guide about data_sources

Describe the data sources in the guide.
Michal 'vorner' Vaner 12 years ago
parent
commit
f3b0c13a93
1 changed files with 106 additions and 103 deletions
  1. 106 103
      doc/guide/bind10-guide.xml

+ 106 - 103
doc/guide/bind10-guide.xml

@@ -1485,134 +1485,137 @@ can use various data source backends.
 
 
     </section>
     </section>
 
 
-    <section>
+    <section id='datasrc'>
       <title>Data Source Backends</title>
       <title>Data Source Backends</title>
 
 
+      <para>
+        Bind 10 has the concept of data sources. A data source is some place
+        where authoritative zone data reside and where they can be served from.
+        This can be a master file or a database or something completely else.
+      </para>
+
+      <para>
+        Once a query arrives, <command>b10-auth</command> goes through a
+        configured list of data sources and finds the one containing a best
+        matching zone. From the equaly good ones, the first one is taken.
+        This data source is then used to answer the query.
+      </para>
+
       <note><para>
       <note><para>
-        For the development prototype release, <command>b10-auth</command>
+        In the development prototype release, <command>b10-auth</command>
-        supports a SQLite3 data source backend and in-memory data source
+        can serve data from a SQLite3 data source backend and from master
-        backend.
+        files.
         Upcoming versions will be able to use multiple different
         Upcoming versions will be able to use multiple different
         data sources, such as MySQL and Berkeley DB.
         data sources, such as MySQL and Berkeley DB.
       </para></note>
       </para></note>
 
 
-
       <para>
       <para>
-        By default, the SQLite3 backend uses the data file located at
+        The configuration is located in data_sources/classes. Each item there
+        represents one RR class and a list used to answer queries for that
+        class. The default contains two classes. The CH class contains a static
+        data source &mdash; one that serves things like
+        <quote>AUTHORS.BIND.</quote>. The IN class contains single SQLite3
+        data source with database file located at
         <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>.
         <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>.
-        (The full path is what was defined at build configure time for
-        <option>--localstatedir</option>.
-        The default is <filename>/usr/local/var/</filename>.)
-	This data file location may be changed by defining the
-	<quote>database_file</quote> configuration.
       </para>
       </para>
 
 
-      <section id="in-memory-datasource">
+      <para>
-	<title>In-memory Data Source</title>
+        Each data source has several option. The first one is
-
+        <varname>type</varname>, which specifies the type of data source to
-	<para>
+        use. Valid types include the ones listed below, but bind10 uses
-<!--	  How to configure it. -->
+        dynamically loaded modules for them, so there may be more in your
-	  The following commands to <command>bindctl</command>
+        case. This option is mandatory.
-	  provide an example of configuring an in-memory data
+      </para>
-	  source containing the <quote>example.com</quote> zone
-	  with the zone file named <quote>example.com.zone</quote>:
-
-<!--
-	  <screen>&gt; <userinput> config set Auth/datasources/ [{"type": "memory", "zones": [{"origin": "example.com", "file": "example.com.zone"}]}]</userinput></screen>
--->
-
-          <screen>&gt; <userinput>config add Auth/datasources</userinput>
-&gt; <userinput>config set Auth/datasources[0]/type "<option>memory</option>"</userinput>
-&gt; <userinput>config add Auth/datasources[0]/zones</userinput>
-&gt; <userinput>config set Auth/datasources[0]/zones[0]/origin "<option>example.com</option>"</userinput>
-&gt; <userinput>config set Auth/datasources[0]/zones[0]/file "<option>example.com.zone</option>"</userinput>
-&gt; <userinput>config commit</userinput></screen>
-
-	  The authoritative server will begin serving it immediately
-	  after the zone data is loaded from the master text file.
-	</para>
-
-      </section>
-
-      <section id="in-memory-datasource-with-sqlite3-backend">
-	<title>In-memory Data Source with SQLite3 Backend</title>
-
-	<para>
-<!--	  How to configure it. -->
-	  The following commands to <command>bindctl</command>
-	  provide an example of configuring an in-memory data
-	  source containing the <quote>example.org</quote> zone
-	  with a SQLite3 backend file named <quote>example.org.sqlite3</quote>:
-
-<!--
-	  <screen>&gt; <userinput> config set Auth/datasources/ [{"type": "memory", "zones": [{"origin": "example.org", "file": "example.org.sqlite3", "filetype": "sqlite3"}]}]</userinput></screen>
--->
-
-          <screen>&gt; <userinput>config add Auth/datasources</userinput>
-&gt; <userinput>config set Auth/datasources[1]/type "<option>memory</option>"</userinput>
-&gt; <userinput>config add Auth/datasources[1]/zones</userinput>
-&gt; <userinput>config set Auth/datasources[1]/zones[0]/origin "<option>example.org</option>"</userinput>
-&gt; <userinput>config set Auth/datasources[1]/zones[0]/file "<option>example.org.sqlite3</option>"</userinput>
-&gt; <userinput>config set Auth/datasources[1]/zones[0]/filetype "<option>sqlite3</option>"</userinput>
-&gt; <userinput>config commit</userinput></screen>
-
-	  The authoritative server will begin serving it immediately
-	  after the zone data is loaded from the database file.
-	</para>
-
-      </section>
-
-      <section id="in-memory-datasource-loading">
-	<title>Reloading an In-memory Data Source</title>
-
-	<para>
-	  Use the <command>Auth loadzone</command> command in
-	  <command>bindctl</command> to reload a changed master
-	  file into memory; for example:
 
 
-	  <screen>&gt; <userinput>Auth loadzone origin="example.com"</userinput>
+      <para>
-</screen>
+        Another option is <varname>params</varname>. This one is type
+        specific. It means it holds different data depending on the type
+        above. Also, depending on the type, it could be possible to omit it.
+      </para>
 
 
-	</para>
+      <para>
+        Another two options are related to so-called cache. If you enable
+        cache, zone data from the data source are loaded into memory.
+        Then, when answering a query, <command>b10-auth</command> looks
+        into the memory only instead of the data source, which speeds
+        answering up. The first option is <varname>cache-enable</varname>,
+        a boolean value turning the cache on and off (off is default).
+        The second one, <varname>cache-zones</varname>, is a list of zone
+        origins to load into in-memory. Remember that zones in the data source
+        not listed here will not be loaded and will not be available.
+      </para>
 
 
-<!--
+      <section id='datasource-types'>
+        <title>Data source types</title>
         <para>
         <para>
-          The <varname>file</varname> may be an absolute path to the
+          As mentioned, the type used by default is <quote>sqlite3</quote>.
-          master zone file or it is relative to the directory BIND 10 is
+          It has single configuration option inside <varname>params</varname>
-          started from.
+          &mdash; <varname>database_file</varname>, which contains the path
-	</para>
+          to the sqlite3 file containing the data.
--->
+        </para>
 
 
+        <para>
+          Another type is called <quote>MasterFiles</quote>. This one is
+          slightly special. The data are stored in RFC1034 master files.
+          Because answering directly from them would be impractical,
+          this type mandates the cache to be enabled. Also, the list of
+          zones (<varname>cache-zones</varname>) should be omitted. The
+          <varname>params</varname> is a dictionary mapping from zone
+          origins to the files they reside in.
+        </para>
       </section>
       </section>
-      <section id="in-memory-datasource-disabling">
-	<title>Disabling In-memory Data Sources</title>
 
 
+      <section id='datasrc-examples'>
+        <title>Examples</title>
         <para>
         <para>
-	By default, the memory data source is disabled; it must be
+          As this is one of the more complex configurations of Bind10,
-	configured explicitly.  To disable all the in-memory zones,
+          we show some examples. They all assume they start with default
-	specify a null list for <varname>Auth/datasources</varname>:
+          configuration.
+        </para>
 
 
-<!-- TODO: this assumes that Auth/datasources is for memory only -->
+        <para>
+          First, let's disable the static data source
+          (<quote>VERSION.BIND</quote> and friends). As it is the only
+          data source in the CH class, we can remove the whole class.
 
 
-	  <screen>&gt; <userinput>config set Auth/datasources/ []</userinput>
+          <screen>&gt; <userinput>config remove data_sources/classes CH</userinput>
 &gt; <userinput>config commit</userinput></screen>
 &gt; <userinput>config commit</userinput></screen>
-	</para>
+        </para>
 
 
-	<para>
+        <para>
-          The following example stops serving a specific zone:
+          Another one, let's say our default data source contains zones
+          <quote>example.org.</quote> and <quote>example.net.</quote>.
+          We want them to be served from memory to make the answering
+          faster.
 
 
-	  <screen>&gt; <userinput>config remove Auth/datasources[<option>0</option>]/zones[<option>0</option>]</userinput>
+          <screen>&gt; <userinput>config set data_sources/classes/IN[0]/cache-enable true</userinput>
+&gt; <userinput>config add data_sources/classes/IN[0]/cache-zones example.org.</userinput>
+&gt; <userinput>config add data_sources/classes/IN[0]/cache-zones example.net.</userinput>
 &gt; <userinput>config commit</userinput></screen>
 &gt; <userinput>config commit</userinput></screen>
 
 
-	  (Replace the list number(s) in
+          Now every time the zone in the data source is changed by the
-	  <varname>datasources[<replaceable>0</replaceable>]</varname>
+          operator, Bind10 needs to be told to reload it, by
-	  and/or <varname>zones[<replaceable>0</replaceable>]</varname>
+          <screen>&gt; <userinput>Auth loadzone example.org</userinput></screen>
-	  for the relevant zone as needed.)
+          You don't need to do this when the zone is modified by
+          XfrIn, it does so automatically.
+        </para>
 
 
-	</para>
+        <para>
+          Now, the last example is when there are master files we want to
+          serve in addition to whatever is inside the sqlite3 database.
 
 
-      </section>
+          <screen>&gt; <userinput>config add data_sources/classes/IN</userinput>
+&gt; <userinput>config set data_sources/classes/IN[1]/type MasterFiles</userinput>
+&gt; <userinput>config set data_sources/classes/IN[1]/cache-enable true</userinput>
+&gt; <userinput>config set data_sources/classes/IN[1]/params { "example.org": "/path/to/example.org", "example.com": "/path/to/example.com" }</userinput>
+&gt; <userinput>config commit</userinput></screen>
 
 
+          Unfortunately, due to current technical limitations, the params must
+          be set as one JSON blob, it can't be edited in
+          <command>bindctl</command>. To reload a zone, you the same command
+          as above.
+        </para>
+      </section>
     </section>
     </section>
 
 
     <section>
     <section>
@@ -1854,7 +1857,7 @@ http://bind10.isc.org/wiki/ScalableZoneLoadDesign#a7.2UpdatingaZone
 	The administrator doesn't have to do anything for
 	The administrator doesn't have to do anything for
 	<command>b10-auth</command> to serve the new version of the
 	<command>b10-auth</command> to serve the new version of the
 	zone, except for the configuration such as the one described in
 	zone, except for the configuration such as the one described in
-	<xref linkend="in-memory-datasource-with-sqlite3-backend" />.
+	<xref linkend="datasrc" />.
       </para>
       </para>
     </section>
     </section>
 
 
@@ -1965,11 +1968,11 @@ what is XfroutClient xfr_client??
       notify <command>b10-xfrout</command> so that other secondary
       notify <command>b10-xfrout</command> so that other secondary
       servers will be notified via the DNS NOTIFY protocol.
       servers will be notified via the DNS NOTIFY protocol.
       In addition, if <command>b10-auth</command> serves the updated
       In addition, if <command>b10-auth</command> serves the updated
-      zone from its in-memory cache (as described in
+      zone (as described in
-      <xref linkend="in-memory-datasource-with-sqlite3-backend" />),
+      <xref linkend="datasrc" />),
       <command>b10-ddns</command> will also
       <command>b10-ddns</command> will also
       notify <command>b10-auth</command> so that <command>b10-auth</command>
       notify <command>b10-auth</command> so that <command>b10-auth</command>
-      will re-cache the updated zone content.
+      will re-cache the updated zone content if necessary.
     </para>
     </para>
 
 
     <para>
     <para>