Codex/refactor rsyslog module parameter documentation omgssapi (#6294)

* omgssapi: split parameter docs into reference pages

- Introduce dedicated parameter reference files for GssForwardServiceName, GssMode, and ActionGSSForwardDefaultTemplate

- Replace inline module parameter description with list-table summaries and add hidden toctree on module page

- Link imgssapi documentation to the omgssapi module reference without duplicating toctree entries

- AI-Agent: ChatGPT

* omgssapi: correct parameter default documentation

Fix parameter reference defaults to omit erroneous module= prefixes.

With the help of AI-Agent: ChatGPT

doc/source/configuration/modules/imgssapi.rst

@@ -20,12 +20,6 @@ Note: This is a contributed module, which is not supported by the
 rsyslog team. We recommend to use RFC5425 TLS-protected syslog
 instead.
 
-.. toctree::
-   :maxdepth: 1
-
-   gssapi
-
-
 Configuration Parameters
 ========================
 
@@ -33,6 +27,8 @@ Configuration Parameters
 
    Parameter names are case-insensitive; camelCase is recommended for readability.
 
+For client-side forwarding using GSSAPI, see :doc:`omgssapi <omgssapi>`.
+
 
 Input Parameters
 ----------------

doc/source/configuration/modules/omgssapi.rst

@@ -71,3 +71,54 @@ The picture demonstrate how things work.
 
    rsyslog gssapi support
 
+
+Configuration Parameters
+========================
+
+.. note::
+
+   Parameter names are case-insensitive; camelCase is recommended for readability.
+
+Module Parameters
+-----------------
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Parameter
+     - Summary
+   * - :ref:`param-omgssapi-gssforwardservicename`
+     - .. include:: ../../reference/parameters/omgssapi-gssforwardservicename.rst
+        :start-after: .. summary-start
+        :end-before: .. summary-end
+   * - :ref:`param-omgssapi-gssmode`
+     - .. include:: ../../reference/parameters/omgssapi-gssmode.rst
+        :start-after: .. summary-start
+        :end-before: .. summary-end
+   * - :ref:`param-omgssapi-actiongssforwarddefaulttemplate`
+     - .. include:: ../../reference/parameters/omgssapi-actiongssforwarddefaulttemplate.rst
+        :start-after: .. summary-start
+        :end-before: .. summary-end
+
+Action Parameters
+-----------------
+
+The ``omgssapi`` action is configured via module parameters. In modern
+``action()`` syntax, it takes a ``target`` parameter and can optionally have a ``template`` assigned.
+
+Legacy ``:omgssapi:`` syntax is also supported and includes options for
+compression and TCP framing. These are specified in parentheses after the
+selector, for example ``:omgssapi:(z5,o)hostname``.
+
+-  **z[0-9]**: Enables zlib compression. The optional digit specifies the
+   compression level (0-9). Defaults to 9 if no digit is given.
+-  **o**: Enables octet-counted TCP framing.
+
+.. toctree::
+   :hidden:
+
+   ../../reference/parameters/omgssapi-gssforwardservicename
+   ../../reference/parameters/omgssapi-gssmode
+   ../../reference/parameters/omgssapi-actiongssforwarddefaulttemplate
+

doc/source/reference/parameters/omgssapi-actiongssforwarddefaulttemplate.rst

@@ -0,0 +1,61 @@
+.. _param-omgssapi-actiongssforwarddefaulttemplate:
+.. _omgssapi.parameter.module.actiongssforwarddefaulttemplate:
+
+ActionGSSForwardDefaultTemplate
+===============================
+
+.. index::
+   single: omgssapi; ActionGSSForwardDefaultTemplate
+   single: ActionGSSForwardDefaultTemplate
+
+.. summary-start
+
+Sets the default output template omgssapi applies when a forwarding action omits an explicit template.
+
+.. summary-end
+
+This parameter applies to :doc:`../../configuration/modules/omgssapi`.
+
+:Name: ActionGSSForwardDefaultTemplate
+:Scope: module
+:Type: string
+:Default: RSYSLOG_TraditionalForwardFormat
+:Required?: no
+:Introduced: 3.12.4
+
+Description
+-----------
+Sets a new default template for the GSS-API forwarding action. When no template is
+specified in the forwarding rule, omgssapi falls back to this value. By default the
+module uses the built-in ``RSYSLOG_TraditionalForwardFormat`` template, matching the
+legacy syslog forward format. Legacy syntax configures this with directives such as
+``$ActionGSSForwardDefaultTemplate RSYSLOG_ForwardFormat``.
+
+Module usage
+------------
+.. _param-omgssapi-module-actiongssforwarddefaulttemplate:
+.. _omgssapi.parameter.module.actiongssforwarddefaulttemplate-usage:
+
+.. code-block:: rsyslog
+
+   module(
+       load="omgssapi"
+       actionGssForwardDefaultTemplate="RSYSLOG_ForwardFormat"
+   )
+   action(type="omgssapi" target="receiver.mydomain.com")
+
+Legacy names (for reference)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Historic names/directives for compatibility. Do not use in new configs.
+
+.. _omgssapi.parameter.legacy.actiongssforwarddefaulttemplate:
+
+- $ActionGSSForwardDefaultTemplate — maps to ActionGSSForwardDefaultTemplate (status: legacy)
+
+.. index::
+   single: omgssapi; $ActionGSSForwardDefaultTemplate
+   single: $ActionGSSForwardDefaultTemplate
+
+See also
+--------
+See also :doc:`../../configuration/modules/omgssapi`.

doc/source/reference/parameters/omgssapi-gssforwardservicename.rst

@@ -0,0 +1,58 @@
+.. _param-omgssapi-gssforwardservicename:
+.. _omgssapi.parameter.module.gssforwardservicename:
+
+GssForwardServiceName
+=====================
+
+.. index::
+   single: omgssapi; GssForwardServiceName
+   single: GssForwardServiceName
+
+.. summary-start
+
+Sets the Kerberos service principal base name used when omgssapi establishes a GSSAPI-secured forwarding session.
+
+.. summary-end
+
+This parameter applies to :doc:`../../configuration/modules/omgssapi`.
+
+:Name: GssForwardServiceName
+:Scope: module
+:Type: string
+:Default: host
+:Required?: no
+:Introduced: 1.21.2
+
+Description
+-----------
+Specifies the service name used by the client when forwarding GSS-API wrapped messages.
+If unset, the module uses ``host`` as the base name. The actual service principal
+is constructed by appending ``@`` and the hostname that follows the ``:omgssapi:``
+selector in legacy configurations. In legacy syntax this is configured with
+``$GssForwardServiceName rsyslog``.
+
+Module usage
+------------
+.. _param-omgssapi-module-gssforwardservicename:
+.. _omgssapi.parameter.module.gssforwardservicename-usage:
+
+.. code-block:: rsyslog
+
+   module(load="omgssapi" gssForwardServiceName="rsyslog")
+   action(type="omgssapi" target="receiver.mydomain.com")
+
+Legacy names (for reference)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Historic names/directives for compatibility. Do not use in new configs.
+
+.. _omgssapi.parameter.legacy.gssforwardservicename:
+
+- $GssForwardServiceName — maps to GssForwardServiceName (status: legacy)
+
+.. index::
+   single: omgssapi; $GssForwardServiceName
+   single: $GssForwardServiceName
+
+See also
+--------
+See also :doc:`../../configuration/modules/omgssapi`.

doc/source/reference/parameters/omgssapi-gssmode.rst

@@ -0,0 +1,61 @@
+.. _param-omgssapi-gssmode:
+.. _omgssapi.parameter.module.gssmode:
+
+GssMode
+=======
+
+.. index::
+   single: omgssapi; GssMode
+   single: GssMode
+
+.. summary-start
+
+Chooses whether omgssapi requests integrity-only or encrypted message protection for GSSAPI sessions.
+
+.. summary-end
+
+This parameter applies to :doc:`../../configuration/modules/omgssapi`.
+
+:Name: GssMode
+:Scope: module
+:Type: string
+:Default: encryption
+:Required?: no
+:Introduced: 1.21.2
+
+Description
+-----------
+Specifies the GSS-API protection level used by the client. The available modes are:
+
+- ``integrity`` — only authenticates clients and verifies message integrity.
+- ``encryption`` — provides the same guarantees as ``integrity`` and encrypts
+  messages when both peers support it.
+
+Legacy configurations set this directive with statements such as
+``$GssMode encryption``.
+
+Module usage
+------------
+.. _param-omgssapi-module-gssmode:
+.. _omgssapi.parameter.module.gssmode-usage:
+
+.. code-block:: rsyslog
+
+   module(load="omgssapi" gssMode="encryption")
+   action(type="omgssapi" target="receiver.mydomain.com")
+
+Legacy names (for reference)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Historic names/directives for compatibility. Do not use in new configs.
+
+.. _omgssapi.parameter.legacy.gssmode:
+
+- $GssMode — maps to GssMode (status: legacy)
+
+.. index::
+   single: omgssapi; $GssMode
+   single: $GssMode
+
+See also
+--------
+See also :doc:`../../configuration/modules/omgssapi`.