From f3b0c13a93d6cf49c42d25f1383ad81317169a0d Mon Sep 17 00:00:00 2001 From: Michal 'vorner' Vaner Date: Wed, 1 Aug 2012 15:09:56 +0200 Subject: [PATCH] [2133] Update the guide about data_sources Describe the data sources in the guide. --- doc/guide/bind10-guide.xml | 229 +++++++++++++++++++------------------ 1 file changed, 116 insertions(+), 113 deletions(-) diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml index 040b109799..e36eb51314 100644 --- a/doc/guide/bind10-guide.xml +++ b/doc/guide/bind10-guide.xml @@ -1485,134 +1485,137 @@ can use various data source backends. -
+
Data Source Backends + + 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. + + + + Once a query arrives, b10-auth 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. + + - For the development prototype release, b10-auth - supports a SQLite3 data source backend and in-memory data source - backend. + In the development prototype release, b10-auth + 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. - - 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 — one that serves things like + AUTHORS.BIND.. The IN class contains single SQLite3 + data source with database file located at /usr/local/var/bind10-devel/zone.sqlite3. - (The full path is what was defined at build configure time for - . - The default is /usr/local/var/.) - This data file location may be changed by defining the - database_file configuration. -
- In-memory Data Source + + Each data source has several option. The first one is + type, 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. + - - - The following commands to bindctl - provide an example of configuring an in-memory data - source containing the example.com zone - with the zone file named example.com.zone: + + Another option is params. 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. + - + + 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, b10-auth looks + into the memory only instead of the data source, which speeds + answering up. The first option is cache-enable, + a boolean value turning the cache on and off (off is default). + The second one, cache-zones, 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. + - > config add Auth/datasources -> config set Auth/datasources[0]/type "" -> config add Auth/datasources[0]/zones -> config set Auth/datasources[0]/zones[0]/origin "" -> config set Auth/datasources[0]/zones[0]/file "" -> config commit - - The authoritative server will begin serving it immediately - after the zone data is loaded from the master text file. - - -
- -
- In-memory Data Source with SQLite3 Backend - - - - The following commands to bindctl - provide an example of configuring an in-memory data - source containing the example.org zone - with a SQLite3 backend file named example.org.sqlite3: - - - - > config add Auth/datasources -> config set Auth/datasources[1]/type "" -> config add Auth/datasources[1]/zones -> config set Auth/datasources[1]/zones[0]/origin "" -> config set Auth/datasources[1]/zones[0]/file "" -> config set Auth/datasources[1]/zones[0]/filetype "" -> config commit - - The authoritative server will begin serving it immediately - after the zone data is loaded from the database file. - - -
- -
- Reloading an In-memory Data Source - - - Use the Auth loadzone command in - bindctl to reload a changed master - file into memory; for example: - - > Auth loadzone origin="example.com" - - - - - - -
-
- Disabling In-memory Data Sources + As mentioned, the type used by default is sqlite3. + It has single configuration option inside params + — database_file, which contains the path + to the sqlite3 file containing the data. + - 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 Auth/datasources: - - - - > config set Auth/datasources/ [] -> config commit - - - - The following example stops serving a specific zone: - - > config remove Auth/datasources[]/zones[] -> config commit - - (Replace the list number(s) in - datasources[0] - and/or zones[0] - for the relevant zone as needed.) - - - + Another type is called MasterFiles. 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 (cache-zones) should be omitted. The + params is a dictionary mapping from zone + origins to the files they reside in. +
+
+ Examples + + As this is one of the more complex configurations of Bind10, + we show some examples. They all assume they start with default + configuration. + + + + First, let's disable the static data source + (VERSION.BIND and friends). As it is the only + data source in the CH class, we can remove the whole class. + + > config remove data_sources/classes CH +> config commit + + + + Another one, let's say our default data source contains zones + example.org. and example.net.. + We want them to be served from memory to make the answering + faster. + + > config set data_sources/classes/IN[0]/cache-enable true +> config add data_sources/classes/IN[0]/cache-zones example.org. +> config add data_sources/classes/IN[0]/cache-zones example.net. +> config commit + + Now every time the zone in the data source is changed by the + operator, Bind10 needs to be told to reload it, by + > Auth loadzone example.org + You don't need to do this when the zone is modified by + XfrIn, it does so automatically. + + + + Now, the last example is when there are master files we want to + serve in addition to whatever is inside the sqlite3 database. + + > config add data_sources/classes/IN +> config set data_sources/classes/IN[1]/type MasterFiles +> config set data_sources/classes/IN[1]/cache-enable true +> config set data_sources/classes/IN[1]/params { "example.org": "/path/to/example.org", "example.com": "/path/to/example.com" } +> config commit + + Unfortunately, due to current technical limitations, the params must + be set as one JSON blob, it can't be edited in + bindctl. To reload a zone, you the same command + as above. + +
@@ -1854,7 +1857,7 @@ http://bind10.isc.org/wiki/ScalableZoneLoadDesign#a7.2UpdatingaZone The administrator doesn't have to do anything for b10-auth to serve the new version of the zone, except for the configuration such as the one described in - . + .
@@ -1965,11 +1968,11 @@ what is XfroutClient xfr_client?? notify b10-xfrout so that other secondary servers will be notified via the DNS NOTIFY protocol. In addition, if b10-auth serves the updated - zone from its in-memory cache (as described in - ), + zone (as described in + ), b10-ddns will also notify b10-auth so that b10-auth - will re-cache the updated zone content. + will re-cache the updated zone content if necessary.