mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-23 10:39:16 +00:00
Code Issues Releases Wiki Activity
bind/doc/arm/plugins.inc.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

88 lines
3.2 KiB
ReStructuredText
Raw Permalink Normal View History

Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
Update the copyright information in all files in the repository This commit converts the license handling to adhere to the REUSE specification. It specifically: 1. Adds used licnses to LICENSES/ directory 2. Add "isc" template for adding the copyright boilerplate 3. Changes all source files to include copyright and SPDX license header, this includes all the C sources, documentation, zone files, configuration files. There are notes in the doc/dev/copyrights file on how to add correct headers to the new files. 4. Handle the rest that can't be modified via .reuse/dep5 file. The binary (or otherwise unmodifiable) files could have license places next to them in <foo>.license file, but this would lead to cluttered repository and most of the files handled in the .reuse/dep5 file are system test files.
2021-06-03 08:37:05 +02:00
..
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
.. SPDX-License-Identifier: MPL-2.0
Update the copyright information in all files in the repository This commit converts the license handling to adhere to the REUSE specification. It specifically: 1. Adds used licnses to LICENSES/ directory 2. Add "isc" template for adding the copyright boilerplate 3. Changes all source files to include copyright and SPDX license header, this includes all the C sources, documentation, zone files, configuration files. There are notes in the doc/dev/copyrights file on how to add correct headers to the new files. 4. Handle the rest that can't be modified via .reuse/dep5 file. The binary (or otherwise unmodifiable) files could have license places next to them in <foo>.license file, but this would lead to cluttered repository and most of the files handled in the .reuse/dep5 file are system test files.
2021-06-03 08:37:05 +02:00
..
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
.. 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
Fix typos and change http to https Fixed minor typographical errors and changed URLs from "http" to "https" where appropriate.
2020-09-14 21:04:19 +00:00
.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
Update the copyright information in all files in the repository This commit converts the license handling to adhere to the REUSE specification. It specifically: 1. Adds used licnses to LICENSES/ directory 2. Add "isc" template for adding the copyright boilerplate 3. Changes all source files to include copyright and SPDX license header, this includes all the C sources, documentation, zone files, configuration files. There are notes in the doc/dev/copyrights file on how to add correct headers to the new files. 4. Handle the rest that can't be modified via .reuse/dep5 file. The binary (or otherwise unmodifiable) files could have license places next to them in <foo>.license file, but this would lead to cluttered repository and most of the files handled in the .reuse/dep5 file are system test files.
2021-06-03 08:37:05 +02:00
..
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
.. See the COPYRIGHT file distributed with this work for additional
.. information regarding copyright ownership.
.. _module-info:
Plugins
Split Configuration chapter in the ARM into chapters 3 and 4
2022-03-21 22:13:29 +00:00
~~~~~~~
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
Hyperlink program names to their manual pages Use the new role :iscman: to replace all occurences or ``binary`` with :iscman:`binary`, creating a hyperlink to the manual page. Generated using: find bin -name *.rst | xargs fgrep --files-with-matches '.. iscman' | xargs -I{} -n1 basename {} .rst > /tmp/progs for PROG in $(cat /tmp/progs); do find -name '*.rst' | xargs sed -i -e "s/\`\`$PROG\`\`/:iscman:\`$PROG\`/g"; done Additional hand-edits were done mainly around filter-aaaa and filter-a which are program names and and option names at the same time. Couple more edits was neede to fix .rst syntax broken by automatic replacement.
2022-03-03 22:17:04 +01:00
Plugins are a mechanism to extend the functionality of :iscman:`named` using
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
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.
Hyperlink program names to their manual pages Use the new role :iscman: to replace all occurences or ``binary`` with :iscman:`binary`, creating a hyperlink to the manual page. Generated using: find bin -name *.rst | xargs fgrep --files-with-matches '.. iscman' | xargs -I{} -n1 basename {} .rst > /tmp/progs for PROG in $(cat /tmp/progs); do find -name '*.rst' | xargs sed -i -e "s/\`\`$PROG\`\`/:iscman:\`$PROG\`/g"; done Additional hand-edits were done mainly around filter-aaaa and filter-a which are program names and and option names at the same time. Couple more edits was neede to fix .rst syntax broken by automatic replacement.
2022-03-03 22:17:04 +01:00
The only plugin currently included in BIND is :iscman:`filter-aaaa.so <filter-aaaa>`, which
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
replaces the ``filter-aaaa`` feature that previously existed natively as
Hyperlink program names to their manual pages Use the new role :iscman: to replace all occurences or ``binary`` with :iscman:`binary`, creating a hyperlink to the manual page. Generated using: find bin -name *.rst | xargs fgrep --files-with-matches '.. iscman' | xargs -I{} -n1 basename {} .rst > /tmp/progs for PROG in $(cat /tmp/progs); do find -name '*.rst' | xargs sed -i -e "s/\`\`$PROG\`\`/:iscman:\`$PROG\`/g"; done Additional hand-edits were done mainly around filter-aaaa and filter-a which are program names and and option names at the same time. Couple more edits was neede to fix .rst syntax broken by automatic replacement.
2022-03-03 22:17:04 +01:00
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
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
functionality.
Configuring Plugins
~~~~~~~~~~~~~~~~~~~
Add link anchors to statements and blocks in the ARM All statements now use .. namedconf:statement:: or .. rndcconf:statement:: syntax provided by our Sphinx extension. This has several consequences: - It changes how statement headings are rendered - Statements are indexed and show up as separate items in doc search results (in the HTML version) - Statements can be linked to using either :any:`statement` or :namedconf:ref:`statement` syntax (not used in this commit) - Statements can be categorized and printed using .. namedconf:statatementlist:: syntax (not used in this commit)
2022-05-11 15:45:57 +02:00
.. namedconf:statement:: plugin
Add short description for plugin statement
2022-07-13 19:07:47 +00:00
:tags: server
:short: Configures plugins in :iscman:`named.conf`.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
Add hyperlinks to all unique statement names This shell script added hyperlinks to all unique statement names: UNIQSTATEMENTS=$(\ sort \ <(git grep '.. namedconf:statement::' '*.rst' | sed -e 's/^.*:: //') \ <(git grep '.. rndcconf:statement::' '*.rst' | sed -e 's/^.*:: //') \ | uniq --unique) ARMFILES=$(git ls-files 'doc/*.rst' | grep -v 'doc/man') for STATEMENT in $UNIQSTATEMENTS; \ do sed -i -e "s/\`\`$STATEMENT\`\`/:any:\`$STATEMENT\`/g" $ARMFILES; \ done This needs manual cleanup (see next commit) to fix syntax errors.
2022-07-01 12:29:18 +02:00
A plugin is configured with the :any:`plugin` statement in :iscman:`named.conf`:
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
::
plugin query "library.so" {
parameters
};
update ARM plugin documentation Update the ARM documentation of plugin usage as the extension in the plugin library path is now optional.
2025-07-24 10:51:32 +02:00
In this example, ``query`` indicates that this is a query plugin,
and ``library.so`` is the name of the plugin library. Note that the
library file extension (in this case, ``.so``) is optional, and can
be omitted.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
Add hyperlinks to all unique statement names This shell script added hyperlinks to all unique statement names: UNIQSTATEMENTS=$(\ sort \ <(git grep '.. namedconf:statement::' '*.rst' | sed -e 's/^.*:: //') \ <(git grep '.. rndcconf:statement::' '*.rst' | sed -e 's/^.*:: //') \ | uniq --unique) ARMFILES=$(git ls-files 'doc/*.rst' | grep -v 'doc/man') for STATEMENT in $UNIQSTATEMENTS; \ do sed -i -e "s/\`\`$STATEMENT\`\`/:any:\`$STATEMENT\`/g" $ARMFILES; \ done This needs manual cleanup (see next commit) to fix syntax errors.
2022-07-01 12:29:18 +02:00
Multiple :any:`plugin` statements can be specified, to load different
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
plugins or multiple instances of the same plugin.
Text, grammar, typo, and clarity edits in multiple ARM chapters Files requirements.rst, configuration.rs, plugins.rst, and partially reference.rst has been edited.
2020-05-13 21:22:34 +00:00
``parameters`` are passed as an opaque string to the plugin's initialization
Various text edits and fixes to the documentation
2020-06-08 15:33:45 +00:00
routine. Configuration syntax differs depending on the module.
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
Developing Plugins
~~~~~~~~~~~~~~~~~~
Each plugin implements four functions:
Various text edits and fixes to the documentation
2020-06-08 15:33:45 +00:00
- ``plugin_register``
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
to allocate memory, configure a plugin instance, and attach to hook
points within
Hyperlink program names to their manual pages Use the new role :iscman: to replace all occurences or ``binary`` with :iscman:`binary`, creating a hyperlink to the manual page. Generated using: find bin -name *.rst | xargs fgrep --files-with-matches '.. iscman' | xargs -I{} -n1 basename {} .rst > /tmp/progs for PROG in $(cat /tmp/progs); do find -name '*.rst' | xargs sed -i -e "s/\`\`$PROG\`\`/:iscman:\`$PROG\`/g"; done Additional hand-edits were done mainly around filter-aaaa and filter-a which are program names and and option names at the same time. Couple more edits was neede to fix .rst syntax broken by automatic replacement.
2022-03-03 22:17:04 +01:00
:iscman:`named`
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
,
Various text edits and fixes to the documentation
2020-06-08 15:33:45 +00:00
- ``plugin_destroy``
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
to tear down the plugin instance and free memory,
Various text edits and fixes to the documentation
2020-06-08 15:33:45 +00:00
- ``plugin_version``
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
to check that the plugin is compatible with the current version of
the plugin API,
Various text edits and fixes to the documentation
2020-06-08 15:33:45 +00:00
- ``plugin_check``
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
to test syntactic correctness of the plugin parameters.
Hyperlink program names to their manual pages Use the new role :iscman: to replace all occurences or ``binary`` with :iscman:`binary`, creating a hyperlink to the manual page. Generated using: find bin -name *.rst | xargs fgrep --files-with-matches '.. iscman' | xargs -I{} -n1 basename {} .rst > /tmp/progs for PROG in $(cat /tmp/progs); do find -name '*.rst' | xargs sed -i -e "s/\`\`$PROG\`\`/:iscman:\`$PROG\`/g"; done Additional hand-edits were done mainly around filter-aaaa and filter-a which are program names and and option names at the same time. Couple more edits was neede to fix .rst syntax broken by automatic replacement.
2022-03-03 22:17:04 +01:00
At various locations within the :iscman:`named` source code, there are "hook
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
points" at which a plugin may register itself. When a hook point is
Hyperlink program names to their manual pages Use the new role :iscman: to replace all occurences or ``binary`` with :iscman:`binary`, creating a hyperlink to the manual page. Generated using: find bin -name *.rst | xargs fgrep --files-with-matches '.. iscman' | xargs -I{} -n1 basename {} .rst > /tmp/progs for PROG in $(cat /tmp/progs); do find -name '*.rst' | xargs sed -i -e "s/\`\`$PROG\`\`/:iscman:\`$PROG\`/g"; done Additional hand-edits were done mainly around filter-aaaa and filter-a which are program names and and option names at the same time. Couple more edits was neede to fix .rst syntax broken by automatic replacement.
2022-03-03 22:17:04 +01:00
reached while :iscman:`named` is running, it is checked to see whether any
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
plugins have registered themselves there; if so, the associated "hook
Various text edits and fixes to the documentation
2020-06-08 15:33:45 +00:00
action" - a function within the plugin library - is called. Hook
actions may examine the runtime state and make changes: for example,
Convert the documentation to Sphinx documentation format The ARM and the manpages have been converted into Sphinx documentation format. Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.
2019-03-31 12:49:47 +02:00
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``.
Reference in New Issue Copy Permalink