summaryrefslogtreecommitdiff
path: root/doc/man-sections/plugin-options.rst
diff options
context:
space:
mode:
authorBernhard Schmidt <berni@debian.org>2020-09-01 16:52:17 +0200
committerBernhard Schmidt <berni@debian.org>2020-09-01 16:52:17 +0200
commit9fc3b98112217f2d92a67977dbde0987cc7a1803 (patch)
tree29fcc8654ee65d9dd89ade797bea2f3d9dfd9cfd /doc/man-sections/plugin-options.rst
parenta8758c0e03eed188dcb9da0e4fd781a67c25bf1e (diff)
parent69b02b1f7fd609d84ace13ab04697158de2418a9 (diff)
Merge branch 'debian/experimental-2.5'
Diffstat (limited to 'doc/man-sections/plugin-options.rst')
-rw-r--r--doc/man-sections/plugin-options.rst57
1 files changed, 57 insertions, 0 deletions
diff --git a/doc/man-sections/plugin-options.rst b/doc/man-sections/plugin-options.rst
new file mode 100644
index 0000000..51c574f
--- /dev/null
+++ b/doc/man-sections/plugin-options.rst
@@ -0,0 +1,57 @@
+Plug-in Interface Options
+-------------------------
+
+OpenVPN can be extended by loading external plug-in modules at runtime. These
+plug-ins must be prebuilt and adhere to the OpenVPN Plug-In API.
+
+--plugin args
+ Loads an OpenVPN plug-in module.
+
+ Valid syntax:
+ ::
+
+ plugin module-name
+ plugin module-name "arguments"
+
+ The ``module-name`` needs to be the first
+ argument, indicating the plug-in to load. The second argument is an
+ optional init string which will be passed directly to the plug-in.
+ If the init consists of multiple arguments it must be enclosed in
+ double-quotes (\"). Multiple plugin modules may be loaded into one
+ OpenVPN process.
+
+ The ``module-name`` argument can be just a filename or a filename
+ with a relative or absolute path. The format of the filename and path
+ defines if the plug-in will be loaded from a default plug-in directory
+ or outside this directory.
+ ::
+
+ --plugin path Effective directory used
+ ===================== =============================
+ myplug.so DEFAULT_DIR/myplug.so
+ subdir/myplug.so DEFAULT_DIR/subdir/myplug.so
+ ./subdir/myplug.so CWD/subdir/myplug.so
+ /usr/lib/my/plug.so /usr/lib/my/plug.so
+
+
+ ``DEFAULT_DIR`` is replaced by the default plug-in directory, which is
+ configured at the build time of OpenVPN. ``CWD`` is the current directory
+ where OpenVPN was started or the directory OpenVPN have switched into
+ via the ``--cd`` option before the ``--plugin`` option.
+
+ For more information and examples on how to build OpenVPN plug-in
+ modules, see the README file in the ``plugin`` folder of the OpenVPN
+ source distribution.
+
+ If you are using an RPM install of OpenVPN, see
+ :code:`/usr/share/openvpn/plugin`. The documentation is in ``doc`` and
+ the actual plugin modules are in ``lib``.
+
+ Multiple plugin modules can be cascaded, and modules can be used in
+ tandem with scripts. The modules will be called by OpenVPN in the order
+ that they are declared in the config file. If both a plugin and script
+ are configured for the same callback, the script will be called last. If
+ the return code of the module/script controls an authentication function
+ (such as tls-verify, auth-user-pass-verify, or client-connect), then
+ every module and script must return success (:code:`0`) in order for the
+ connection to be authenticated.