diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 07:24:22 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 07:24:22 +0000 |
commit | 45d6379135504814ab723b57f0eb8be23393a51d (patch) | |
tree | d4f2ec4acca824a8446387a758b0ce4238a4dffa /doc/arm/plugins.rst | |
parent | Initial commit. (diff) | |
download | bind9-45d6379135504814ab723b57f0eb8be23393a51d.tar.xz bind9-45d6379135504814ab723b57f0eb8be23393a51d.zip |
Adding upstream version 1:9.16.44.upstream/1%9.16.44upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/arm/plugins.rst')
-rw-r--r-- | doc/arm/plugins.rst | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/doc/arm/plugins.rst b/doc/arm/plugins.rst new file mode 100644 index 0000000..1939ac7 --- /dev/null +++ b/doc/arm/plugins.rst @@ -0,0 +1,82 @@ +.. 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 ``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 ``filter-aaaa.so``, which +replaces the ``filter-aaaa`` feature that previously existed natively as +part of ``named``. The code for this feature has been removed from +``named`` and can no longer be configured using standard ``named.conf`` +syntax, but linking in the ``filter-aaaa.so`` plugin provides identical +functionality. + +Configuring Plugins +~~~~~~~~~~~~~~~~~~~ + +A plugin is configured with the ``plugin`` statement in ``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 ``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 + ``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 ``named`` source code, there are "hook +points" at which a plugin may register itself. When a hook point is +reached while ``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``. |