diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 15:59:48 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 15:59:48 +0000 |
commit | 3b9b6d0b8e7f798023c9d109c490449d528fde80 (patch) | |
tree | 2e1c188dd7b8d7475cd163de9ae02c428343669b /doc/arm/plugins.inc.rst | |
parent | Initial commit. (diff) | |
download | bind9-upstream.tar.xz bind9-upstream.zip |
Adding upstream version 1:9.18.19.upstream/1%9.18.19upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | doc/arm/plugins.inc.rst | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/doc/arm/plugins.inc.rst b/doc/arm/plugins.inc.rst new file mode 100644 index 0000000..7e63995 --- /dev/null +++ b/doc/arm/plugins.inc.rst @@ -0,0 +1,85 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. 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 https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +.. _module-info: + +Plugins +~~~~~~~ + +Plugins are a mechanism to extend the functionality of :iscman:`named` 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. + +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. + +The only plugin currently included in BIND is :iscman:`filter-aaaa.so <filter-aaaa>`, which +replaces the ``filter-aaaa`` feature that previously existed natively as +part of :iscman:`named`. The code for this feature has been removed from +:iscman:`named` and can no longer be configured using standard :iscman:`named.conf` +syntax, but linking in the :iscman:`filter-aaaa.so <filter-aaaa>` plugin provides identical +functionality. + +Configuring Plugins +~~~~~~~~~~~~~~~~~~~ +.. namedconf:statement:: plugin + :tags: server + :short: Configures plugins in :iscman:`named.conf`. + +A plugin is configured with the :any:`plugin` statement in :iscman:`named.conf`: + +:: + + plugin query "library.so" { + parameters + }; + + +In this example, file ``library.so`` is the plugin library. ``query`` +indicates that this is a query plugin. + +Multiple :any:`plugin` statements can be specified, to load different +plugins or multiple instances of the same plugin. + +``parameters`` are passed as an opaque string to the plugin's initialization +routine. Configuration syntax differs depending on the module. + +Developing Plugins +~~~~~~~~~~~~~~~~~~ + +Each plugin implements four functions: + +- ``plugin_register`` + to allocate memory, configure a plugin instance, and attach to hook + points within + :iscman:`named` + , +- ``plugin_destroy`` + to tear down the plugin instance and free memory, +- ``plugin_version`` + to check that the plugin is compatible with the current version of + the plugin API, +- ``plugin_check`` + to test syntactic correctness of the plugin parameters. + +At various locations within the :iscman:`named` source code, there are "hook +points" at which a plugin may register itself. When a hook point is +reached while :iscman:`named` is running, it is checked to see whether any +plugins have registered themselves there; if so, the associated "hook +action" - a function within the plugin library - is called. 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 +``lib/ns/include/ns/hooks.h``. |