From: Christopher Faulet <cfaulet@haproxy.com>
Date: Wed, 7 Oct 2026 19:18:36 +0000 (+0200)
Subject: DOC: lua: Document the filter instance declaration of Lua filters
X-Git-Tag: v3.5-dev9~52
X-Git-Url: https://git.kaiwu.me/$%7BISSUES%7D/static/gitweb.js?a=commitdiff_plain;h=73bd8d7e5667cf0fcc56991f62ca599154c71bc7;p=haproxy.git

DOC: lua: Document the filter instance declaration of Lua filters

The filter instance mode documentation claims that the supported filter
classes are documented in the section 9 of the configuration manual, but
the Lua filters are missing: they are not built-in classes, they are
registered by the Lua scripts with core.register_filter() and are
declared with the "lua" filter class. The Lua API documentation only
shows the legacy declaration of a Lua filter.

Document the "filter-config lua id <name>" declaration in the Lua API
documentation, next to the legacy one: the instance id selects the
registered filter to instantiate, the optional "enabled" token activates
the instance, and the other arguments are the same as for the legacy
declaration. Mention that contrary to the legacy "filter" directive, the
Lua filters may be declared in defaults sections with the new mode, to
be inherited by the proxies using them. Finally, point to the Lua API
documentation from the introduction of the section 9.
---

diff --git a/doc/configuration.txt b/doc/configuration.txt
index b80479f48..23acb5ccc 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -31510,6 +31510,10 @@ with "filter-config" may differ from the legacy filter name; it is given in
 the documentation of each filter. The "filter-config" syntax is documented
 below the legacy one.
 
+The Lua filters are not documented here: they are registered by Lua scripts
+with core.register_filter() and are declared with the "lua" filter class.
+See the Lua API documentation for their declaration syntax.
+
 The filter instances of a proxy may be inspected with the "show filter
 classes" and "show filter instances" CLI commands (see the management
 manual).
diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index e46adc443..8632aaf6a 100644
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -706,6 +706,20 @@ Core class
     mode http
     filter lua.my-filter arg1 arg2 arg3
 
+With the filter instance mode, the same filter is declared like this::
+
+  filter-config lua id my-filter enabled arg1 arg2 arg3
+
+The instance id selects the registered filter to instantiate: the instance
+with id 'my-filter' instantiates the filter registered as "lua.my-filter".
+The optional "enabled" token activates the instance, which may also be
+enabled or disabled later with the "filter-enable" and "filter-disable"
+directives. The other arguments are the same as for the legacy declaration
+and are passed to the registration function. Contrary to the legacy "filter"
+directive, "filter-config lua" is also allowed in defaults sections, the
+instances being inherited by the proxies using them. See the
+"filter-config" entry in the configuration manual for the details.
+
 ..
 
   :see: :js:class:`Filter`