From 341f5a39e76f5bf238ef3184d397371752bb6797 Mon Sep 17 00:00:00 2001 From: Ulrike Gerhards Date: Thu, 11 Sep 2025 18:07:23 +0200 Subject: [PATCH] refactor rsyslog module parameter documentation for mmsnmptrapd * mmsnmptrapd: split parameter docs into reference pages --- .../configuration/modules/mmsnmptrapd.rst | 47 +++++++------- .../mmsnmptrapd-severitymapping.rst | 63 +++++++++++++++++++ .../reference/parameters/mmsnmptrapd-tag.rst | 57 +++++++++++++++++ 3 files changed, 145 insertions(+), 22 deletions(-) create mode 100644 doc/source/reference/parameters/mmsnmptrapd-severitymapping.rst create mode 100644 doc/source/reference/parameters/mmsnmptrapd-tag.rst diff --git a/doc/source/configuration/modules/mmsnmptrapd.rst b/doc/source/configuration/modules/mmsnmptrapd.rst index 0f75d8c95..48ad470cf 100644 --- a/doc/source/configuration/modules/mmsnmptrapd.rst +++ b/doc/source/configuration/modules/mmsnmptrapd.rst @@ -57,30 +57,34 @@ this module, with the help of filters or multiple rulesets and ruleset bindings. In short words, all capabilities rsyslog offers to control output modules are also available to mmsnmptrapd. -**Configuration Parameters**: +Module Parameters +----------------- -Note: parameter names are case-insensitive. +.. note:: -- **$mmsnmptrapdTag** [tagname] + Parameter names are case-insensitive; camelCase is recommended for + readability. - Tells the module which start string inside the tag to look for. The - default is "snmptrapd". Note that a slash is automatically added to - this tag when it comes to matching incoming messages. It MUST not be - given, except if two slashes are required for whatever reasons (so - "tag/" results in a check for "tag//" at the start of the tag field). +.. list-table:: + :widths: 30 70 + :header-rows: 1 -- **$mmsnmptrapdSeverityMapping** [severitymap] - This specifies the severity mapping table. It needs to be specified - as a list. Note that due to the current config system **no - whitespace** is supported inside the list, so be sure not to use any - whitespace inside it. - The list is constructed of Severity-Name/Severity-Value pairs, - delimited by comma. Severity-Name is a case-sensitive string, e.g. - "warning" and an associated numerical value (e.g. 4). Possible values - are in the rage 0..7 and are defined in RFC5424, table 2. The given - sample would be specified as "warning/4". - If multiple instances of mmsnmptrapd are used, each instance uses - the most recently defined $mmsnmptrapdSeverityMapping before itself. + * - Parameter + - Summary + * - :ref:`param-mmsnmptrapd-tag` + - .. include:: ../../reference/parameters/mmsnmptrapd-tag.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-mmsnmptrapd-severitymapping` + - .. include:: ../../reference/parameters/mmsnmptrapd-severitymapping.rst + :start-after: .. summary-start + :end-before: .. summary-end + +.. toctree:: + :hidden: + + ../../reference/parameters/mmsnmptrapd-tag + ../../reference/parameters/mmsnmptrapd-severitymapping **Caveats/Known Bugs:** @@ -93,10 +97,9 @@ warning severities. The default tag is used. :: - $ModLoad mmsnmptrapd # needs to be done just once + module(load="mmsnmptrapd" severityMapping="warning/4,error/3") # needs to be done just once # ... other module loads and listener setup ... *.* /path/to/file/with/originalMessage # this file receives unmodified messages - $mmsnmptrapdSeverityMapping warning/4,error/3 *.* :mmsnmptrapd: # now message is modified *.* /path/to/file/with/modifiedMessage # this file receives modified messages # ... rest of config ... diff --git a/doc/source/reference/parameters/mmsnmptrapd-severitymapping.rst b/doc/source/reference/parameters/mmsnmptrapd-severitymapping.rst new file mode 100644 index 000000000..5dc698e5f --- /dev/null +++ b/doc/source/reference/parameters/mmsnmptrapd-severitymapping.rst @@ -0,0 +1,63 @@ +.. _param-mmsnmptrapd-severitymapping: +.. _mmsnmptrapd.parameter.module.severitymapping: + +severityMapping +=============== + +.. index:: + single: mmsnmptrapd; severityMapping + single: severityMapping + +.. summary-start + +Defines severity string to numeric code mappings. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/mmsnmptrapd`. + +:Name: severityMapping +:Scope: module +:Type: string +:Default: module=none +:Required?: no +:Introduced: at least 5.8.1, possibly earlier + +Description +----------- +This specifies the severity mapping table. It must be specified as a list. +Note that **no whitespace** is supported inside the list, as it will likely +lead to parsing errors. The list is +constructed of Severity-Name/Severity-Value pairs, delimited by comma. +Severity-Name is a case-sensitive string, e.g. ``warning`` and an associated +numerical value (e.g. 4). Possible values are in the range 0..7 and are defined +in `RFC5424, table 2 `_. +The given sample would be specified as ``warning/4``. The mapping is defined +when the module is loaded using the ``module()`` statement. This setting applies +to all subsequent actions that use this module instance. To use different +mappings, load separate instances of the module in different rulesets. + +Module usage +------------ +.. _param-mmsnmptrapd-module-severitymapping: +.. _mmsnmptrapd.parameter.module.severitymapping-usage: + +.. code-block:: rsyslog + + module(load="mmsnmptrapd" severityMapping="warning/4,error/3") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _mmsnmptrapd.parameter.legacy.mmsnmptrapdseveritymapping: + +- $mmsnmptrapdSeverityMapping — maps to severityMapping (status: legacy) + +.. index:: + single: mmsnmptrapd; $mmsnmptrapdSeverityMapping + single: $mmsnmptrapdSeverityMapping + +See also +-------- +See also :doc:`../../configuration/modules/mmsnmptrapd`. diff --git a/doc/source/reference/parameters/mmsnmptrapd-tag.rst b/doc/source/reference/parameters/mmsnmptrapd-tag.rst new file mode 100644 index 000000000..8abc797ab --- /dev/null +++ b/doc/source/reference/parameters/mmsnmptrapd-tag.rst @@ -0,0 +1,57 @@ +.. _param-mmsnmptrapd-tag: +.. _mmsnmptrapd.parameter.module.tag: + +tag +=== + +.. index:: + single: mmsnmptrapd; tag + single: tag + +.. summary-start + +Specifies the tag prefix that identifies messages for processing. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/mmsnmptrapd`. + +:Name: tag +:Scope: module +:Type: word (see :doc:`../../rainerscript/constant_strings`) +:Default: module=snmptrapd +:Required?: no +:Introduced: at least 5.8.1, possibly earlier + +Description +----------- +Tells the module which start string inside the tag to look for. The default is +``snmptrapd``. Note that a slash (``/``) is automatically appended to this tag for +matching. You should not include a trailing slash unless you specifically need +to match a double slash. For example, setting ``tag="tag/"`` results in a +check for ``tag//`` at the start of the tag field. + +Module usage +------------ +.. _param-mmsnmptrapd-module-tag: +.. _mmsnmptrapd.parameter.module.tag-usage: + +.. code-block:: rsyslog + + module(load="mmsnmptrapd" tag="snmptrapd") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _mmsnmptrapd.parameter.legacy.mmsnmptrapdtag: + +- $mmsnmptrapdTag — maps to tag (status: legacy) + +.. index:: + single: mmsnmptrapd; $mmsnmptrapdTag + single: $mmsnmptrapdTag + +See also +-------- +See also :doc:`../../configuration/modules/mmsnmptrapd`.