add basic plugins documentation

diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index b81f8384e34f8467e8883c7b336d83133e86918a..3c90ae39585e0ea78ce44169fa3e1a97473b9a38 100644 (file)
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -1325,6 +1325,9 @@ controls {
        </informaltable>
       </section>
     </section>
+
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="plugins.xml"/>
+
   </chapter>
 
   <chapter xml:id="Bv9ARM.ch04"><info><title>Advanced DNS Features</title></info>

diff --git a/doc/arm/plugins.xml b/doc/arm/plugins.xml
new file mode 100644 (file)
index 0000000..507970b
--- /dev/null
+++ b/doc/arm/plugins.xml
@@ -0,0 +1,95 @@
+<!--
+ - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ -
+ - See the COPYRIGHT file distributed with this work for additional
+ - information regarding copyright ownership.
+-->
+
+<!-- Converted by db4-upgrade version 1.0 -->
+<section xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:id="module-info"><info><title>Plugins</title></info>
+
+  <para>
+    Plugins are a mechanism to extend the functionality of
+    <command>named</command> using dynamically loadable libraries.
+    By using plugins, core server functionality can be kept simple
+    for the majority of users; more complex code implementing optional
+    features need only be installed by users that need those features.
+  </para>
+  <para>
+    The plugin interface is a work in progress, and is expected to evolve
+    as more plugins are added. Currently, only "query plugins" are supported;
+    these modify the name server query logic. Other plugin types may be added
+    in the future.
+  </para>
+  <para>
+    The only plugin currently included in BIND is
+    <filename>filter-aaaa.so</filename>, which replaces the
+    <command>filter-aaaa</command> feature that previously existed natively
+    as part of <command>named</command>.
+    The code for this feature has been removed from <command>named</command>,
+    and can no longer be configured using standard
+    <filename>named.conf</filename> syntax, but linking in the
+    <filename>filter-aaaa.so</filename> plugin provides identical
+    functionality.
+  </para>
+
+  <section><info><title>Configuring Plugins</title></info>
+    <para>
+      A plugin is configured with the <command>plugin</command>
+      statement in <filename>named.conf</filename>:
+    </para>
+    <screen>
+    plugin query "library.so" {
+        <replaceable>parameters</replaceable>
+    };
+    </screen>
+    <para>
+      In this example, file <filename>library.so</filename> is the plugin
+      library.  <literal>query</literal> indicates that this is a query
+      plugin.
+    <para>
+    </para>
+      Multiple <command>plugin</command> statements can be specified, to load
+      different plugins or multiple instances of the same plugin.
+    </para>
+    <para>
+      <replaceable>parameters</replaceable> are passed as an opaque
+      string to the plugin's initialization routine. Configuration
+      syntax will differ depending on the module.
+    </para>
+  </section>
+
+  <section><info><title>Developing Plugins</title></info>
+    <para>
+      Each plugin implements four functions:
+      <itemizedlist>
+        <listitem><command>plugin_register</command> to allocate memory,
+        configure a plugin instance, and attach to hook points within
+        <command>named</command>,</listitem>
+        <listitem><command>plugin_destroy</command> to tear down the plugin
+        instance and free memory,</listitem>
+        <listitem><command>plugin_version</command> to check that the plugin
+        is compatible with the current version of the plugin API,</listitem>
+        <listitem><command>plugin_check</command> to test syntactic
+        correctness of the plugin parameters.</listitem>
+      </itemizedlist>
+    </para>
+    <para>
+      At various locations within the <command>named</command> source code,
+      there are "hook points" at which a plugin may register itself.
+      When a hook point is reached while <command>named</command> is
+      running, it is checked to see whether any plugins have registered
+      themselves there; if so, the associated "hook action" is called -
+      this is a function within the plugin library. Hook actions may
+      examine the runtime state and make changes - for example, modifying
+      the answers to be sent back to a client or forcing a query to be
+      aborted. More details can be found in the file
+      <filename>lib/ns/include/ns/hooks.h</filename>.
+    </para>
+  </section>
+
+</section>

diff --git a/util/copyrights b/util/copyrights
index 648b7dd2aa70c1fcdfcee5219af408770af23a9c..45bf7c0e998b2b69f597c8206fb9eb405d981295 100644 (file)
--- a/util/copyrights
+++ b/util/copyrights
@@ -1510,6 +1510,7 @@
 ./doc/arm/options.grammar.xml                  SGML    2018
 ./doc/arm/pkcs11.xml                           SGML    2010,2012,2013,2014,2015,2016,2018
 ./doc/arm/pkgversion.xml.in                    SGML    2015,2016,2018
+./doc/arm/plugins.xml                          SGML    2018
 ./doc/arm/redirect.zoneopt.xml                 SGML    2018
 ./doc/arm/releaseinfo.xml.in                   SGML    2015,2016,2018
 ./doc/arm/server.grammar.xml                   SGML    2018