1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2.. 3.. SPDX-License-Identifier: MPL-2.0 4.. 5.. This Source Code Form is subject to the terms of the Mozilla Public 6.. License, v. 2.0. If a copy of the MPL was not distributed with this 7.. file, you can obtain one at https://mozilla.org/MPL/2.0/. 8.. 9.. See the COPYRIGHT file distributed with this work for additional 10.. information regarding copyright ownership. 11 12.. _module-info: 13 14Plugins 15~~~~~~~ 16 17Plugins are a mechanism to extend the functionality of :iscman:`named` using 18dynamically loadable libraries. By using plugins, core server 19functionality can be kept simple for the majority of users; more complex 20code implementing optional features need only be installed by users that 21need those features. 22 23The plugin interface is a work in progress, and is expected to evolve as 24more plugins are added. Currently, only "query plugins" are supported; 25these modify the name server query logic. Other plugin types may be 26added in the future. 27 28The only plugin currently included in BIND is :iscman:`filter-aaaa.so <filter-aaaa>`, which 29replaces the ``filter-aaaa`` feature that previously existed natively as 30part of :iscman:`named`. The code for this feature has been removed from 31:iscman:`named` and can no longer be configured using standard :iscman:`named.conf` 32syntax, but linking in the :iscman:`filter-aaaa.so <filter-aaaa>` plugin provides identical 33functionality. 34 35Configuring Plugins 36~~~~~~~~~~~~~~~~~~~ 37.. namedconf:statement:: plugin 38 :tags: server 39 :short: Configures plugins in :iscman:`named.conf`. 40 41A plugin is configured with the :any:`plugin` statement in :iscman:`named.conf`: 42 43:: 44 45 plugin query "library.so" { 46 parameters 47 }; 48 49 50In this example, file ``library.so`` is the plugin library. ``query`` 51indicates that this is a query plugin. 52 53Multiple :any:`plugin` statements can be specified, to load different 54plugins or multiple instances of the same plugin. 55 56``parameters`` are passed as an opaque string to the plugin's initialization 57routine. Configuration syntax differs depending on the module. 58 59Developing Plugins 60~~~~~~~~~~~~~~~~~~ 61 62Each plugin implements four functions: 63 64- ``plugin_register`` 65 to allocate memory, configure a plugin instance, and attach to hook 66 points within 67 :iscman:`named` 68 , 69- ``plugin_destroy`` 70 to tear down the plugin instance and free memory, 71- ``plugin_version`` 72 to check that the plugin is compatible with the current version of 73 the plugin API, 74- ``plugin_check`` 75 to test syntactic correctness of the plugin parameters. 76 77At various locations within the :iscman:`named` source code, there are "hook 78points" at which a plugin may register itself. When a hook point is 79reached while :iscman:`named` is running, it is checked to see whether any 80plugins have registered themselves there; if so, the associated "hook 81action" - a function within the plugin library - is called. Hook 82actions may examine the runtime state and make changes: for example, 83modifying the answers to be sent back to a client or forcing a query to 84be aborted. More details can be found in the file 85``lib/ns/include/ns/hooks.h``. 86