mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-31 05:55:28 +00:00
Code Issues Releases Wiki Activity

[2133] Update the guide about data_sources

Browse Source 
Describe the data sources in the guide.
This commit is contained in:
Michal 'vorner' Vaner
2012-08-01 15:09:56 +02:00
parent 8145395b1a
commit f3b0c13a93
1 changed files with 116 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
doc/guide/bind10-guide.xml
View File

@@ -1485,134 +1485,137 @@ can use various data source backends.
</section>
<section>
<section id='datasrc'>
<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>
For the development prototype release, <command>b10-auth</command>
supports a SQLite3 data source backend and in-memory data source
backend.
In the development prototype release, <command>b10-auth</command>
can serve data from a SQLite3 data source backend and from master
files.
Upcoming versions will be able to use multiple different
data sources, such as MySQL and Berkeley DB.
</para></note>
<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>.
(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>
<section id="in-memory-datasource">
<title>In-memory Data Source</title>
<para>
Each data source has several option. The first one is
<varname>type</varname>, which specifies the type of data source to
use. Valid types include the ones listed below, but bind10 uses
dynamically loaded modules for them, so there may be more in your
case. This option is mandatory.
</para>
<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.com</quote> zone
with the zone file named <quote>example.com.zone</quote>:
<para>
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>
<!--
<screen>&gt; <userinput> config set Auth/datasources/ [{"type": "memory", "zones": [{"origin": "example.com", "file": "example.com.zone"}]}]</userinput></screen>
-->
<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>
<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>
</screen>
</para>
<!--
<section id='datasource-types'>
<title>Data source types</title>
<para>
The <varname>file</varname> may be an absolute path to the
master zone file or it is relative to the directory BIND 10 is
started from.
</para>
-->
</section>
<section id="in-memory-datasource-disabling">
<title>Disabling In-memory Data Sources</title>
As mentioned, the type used by default is <quote>sqlite3</quote>.
It has single configuration option inside <varname>params</varname>
&mdash; <varname>database_file</varname>, which contains the path
to the sqlite3 file containing the data.
</para>
<para>
By default, the memory data source is disabled; it must be
configured explicitly. To disable all the in-memory zones,
specify a null list for <varname>Auth/datasources</varname>:
<!-- TODO: this assumes that Auth/datasources is for memory only -->
<screen>&gt; <userinput>config set Auth/datasources/ []</userinput>
&gt; <userinput>config commit</userinput></screen>
</para>
<para>
The following example stops serving a specific zone:
<screen>&gt; <userinput>config remove Auth/datasources[<option>0</option>]/zones[<option>0</option>]</userinput>
&gt; <userinput>config commit</userinput></screen>
(Replace the list number(s) in
<varname>datasources[<replaceable>0</replaceable>]</varname>
and/or <varname>zones[<replaceable>0</replaceable>]</varname>
for the relevant zone as needed.)
</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 id='datasrc-examples'>
<title>Examples</title>
<para>
As this is one of the more complex configurations of Bind10,
we show some examples. They all assume they start with default
configuration.
</para>
<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 remove data_sources/classes CH</userinput>
&gt; <userinput>config commit</userinput></screen>
</para>
<para>
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 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>
Now every time the zone in the data source is changed by the
operator, Bind10 needs to be told to reload it, by
<screen>&gt; <userinput>Auth loadzone example.org</userinput></screen>
You don't need to do this when the zone is modified by
XfrIn, it does so automatically.
</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.
<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>
@@ -1854,7 +1857,7 @@ http://bind10.isc.org/wiki/ScalableZoneLoadDesign#a7.2UpdatingaZone
The administrator doesn't have to do anything for
<command>b10-auth</command> to serve the new version of the
zone, except for the configuration such as the one described in
<xref linkend="in-memory-datasource-with-sqlite3-backend" />.
<xref linkend="datasrc" />.
</para>
</section>
@@ -1965,11 +1968,11 @@ what is XfroutClient xfr_client??
notify <command>b10-xfrout</command> so that other secondary
servers will be notified via the DNS NOTIFY protocol.
In addition, if <command>b10-auth</command> serves the updated
zone from its in-memory cache (as described in
<xref linkend="in-memory-datasource-with-sqlite3-backend" />),
zone (as described in
<xref linkend="datasrc" />),
<command>b10-ddns</command> will also
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>