mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-12 19:30:42 +01:00
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
This commit is contained in:
Ulrike Gerhards
GitHub
parent
b4240fe580
commit
9e55d219b5
@ -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
|
||||
----------------
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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`.
|
||||
@ -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`.
|
||||
61
doc/source/reference/parameters/omgssapi-gssmode.rst
Normal file
61
doc/source/reference/parameters/omgssapi-gssmode.rst
Normal file
@ -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`.
|
||||
Loading…
x
Reference in New Issue
Block a user