diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml index 040b109799..c5df326db8 100644 --- a/doc/guide/bind10-guide.xml +++ b/doc/guide/bind10-guide.xml @@ -1485,134 +1485,154 @@ can use various data source backends. -
+
Data Source Backends + + Bind 10 has the concept of data sources. A data source is a place + where authoritative zone data reside and where they can be served + from. This can be a master file, a database or something completely + different. + + + + 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 equally 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 options. 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 option is type + specific; it holds different data depending on the type + above. Also, depending on the type, it could be possible to omit it. + - + + There are two options related to the 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 the 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 at all. + - > 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. + +
+ + + + There's also Auth/database_file configuration + variable, pointing to a sqlite3 database file. This is no longer + used by b10-auth, but it is left in place for + now, since other modules use it. Once b10-xfrin, + b10-xfrout and b10-ddns + are ported to the new configuration, this will disappear. But for + now, make sure that if you use any of these modules, the new + and old configuration correspond. The defaults are consistent, so + unless you tweaked either the new or the old configuration, you're + good. + + +
@@ -1854,7 +1874,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 +1985,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. @@ -2548,7 +2568,7 @@ const std::string HARDCODED_SERVER_ID = "192.0.2.1";
- DHCPv4 Server Limitations + DHCPv4 Server Limitations These are the current limitations of the DHCPv4 server software. Most of them are reflections of the early stage of development and should be treated as not implemented diff --git a/src/bin/cfgmgr/plugins/Makefile.am b/src/bin/cfgmgr/plugins/Makefile.am index eb7809c02a..e6ed1275c8 100644 --- a/src/bin/cfgmgr/plugins/Makefile.am +++ b/src/bin/cfgmgr/plugins/Makefile.am @@ -3,7 +3,7 @@ SUBDIRS = tests EXTRA_DIST = README logging.spec tsig_keys.spec datasrc.spec: datasrc.spec.pre - $(SED) -e "s|@@PKGDATADIR@@|$(pkgdatadir)|" datasrc.spec.pre >$@ + $(SED) -e "s|@@PKGDATADIR@@|$(pkgdatadir)|;s|@@LOCALSTATEDIR@@|$(localstatedir)|" datasrc.spec.pre >$@ config_plugindir = @prefix@/share/@PACKAGE@/config_plugins config_plugin_DATA = logging.spec tsig_keys.spec datasrc.spec diff --git a/src/bin/cfgmgr/plugins/datasrc.spec.pre.in b/src/bin/cfgmgr/plugins/datasrc.spec.pre.in index 5bd20bb559..f2c6a974a2 100644 --- a/src/bin/cfgmgr/plugins/datasrc.spec.pre.in +++ b/src/bin/cfgmgr/plugins/datasrc.spec.pre.in @@ -8,6 +8,14 @@ "item_type": "named_set", "item_optional": false, "item_default": { + "IN": [ + { + "type": "sqlite3", + "params": { + "database_file": "@@LOCALSTATEDIR@@/@PACKAGE@/zone.sqlite3" + } + } + ], "CH": [ { "type": "static", diff --git a/tests/lettuce/configurations/bindctl/bindctl.config.orig b/tests/lettuce/configurations/bindctl/bindctl.config.orig index bf623c5c4e..3530b3e203 100644 --- a/tests/lettuce/configurations/bindctl/bindctl.config.orig +++ b/tests/lettuce/configurations/bindctl/bindctl.config.orig @@ -14,6 +14,9 @@ "address": "127.0.0.1" } ] }, + "data_sources": { + "classes": {} + }, "Boss": { "components": { "b10-cmdctl": { "special": "cmdctl", "kind": "needed" } diff --git a/tests/lettuce/configurations/bindctl_commands.config.orig b/tests/lettuce/configurations/bindctl_commands.config.orig index d74b96e8f8..b60201d7fa 100644 --- a/tests/lettuce/configurations/bindctl_commands.config.orig +++ b/tests/lettuce/configurations/bindctl_commands.config.orig @@ -14,6 +14,9 @@ "address": "127.0.0.1" } ] }, + "data_sources": { + "classes": {} + }, "StatsHttpd": { "listen_on": [ { "port": 47811,