diff options
Diffstat (limited to '')
| -rw-r--r-- | source/configuration/modules/pmciscoios.rst | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/source/configuration/modules/pmciscoios.rst b/source/configuration/modules/pmciscoios.rst new file mode 100644 index 0000000..dc82e43 --- /dev/null +++ b/source/configuration/modules/pmciscoios.rst @@ -0,0 +1,183 @@ +********** +pmciscoios +********** + +=========================== =========================================================================== +**Module Name:** **pmciscoios** +**Author:** `Rainer Gerhards <https://rainer.gerhards.net/>`_ <rgerhards@adiscon.com> +**Available since:** 8.3.4+ +=========================== =========================================================================== + + +Purpose +======= + +This is a parser that understands Cisco IOS "syslog" format. Note +that this format is quite different from RFC syslog format, and +so the default parser chain cannot deal with it. + +Note that due to large differences in IOS logging format, pmciscoios +may currently not be able to handle all possible format variations. +Nevertheless, it should be fairly easy to adapt it to additional +requirements. So be sure to ask if you run into problems with +format issues. + +Note that if your Cisco system emits timezone information in a supported +format, rsyslog will pick it up. In order to apply proper timezone offsets, +the timezone ids (e.g. "EST") must be configured via the +:doc:`timezone object <../timezone>`. + +Note if the clock on the Cisco device has not been set and cannot be +verified the Cisco will prepend the timestamp field with an asterisk (*). +If the clock has gone out of sync with its configured NTP server the +timestamp field will be prepended with a dot (.). In both of these cases +parsing the timestamp would fail, therefore any preceding asterisks (*) or +dots (.) are ignored. This may lead to "incorrect" timestamps being logged. + + +Configuration Parameters +======================== + +.. note:: + + Parameter names are case-insensitive. + + +Parser Parameters +----------------- + +present.origin +^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "none" + +This setting tell the parser if the origin field is present inside +the message. Due to the nature of Cisco's logging format, the parser +cannot sufficiently correctly deduce if the origin field is present +or not (at least not with reasonable performance). As such, the parser +must be provided with that information. If the origin is present, +its value is stored inside the HOSTNAME message property. + + +present.xr +^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "none" + +If syslog is received from an IOSXR device the syslog format will usually +start with the RSP/LC/etc that produced the log, then the timestamp. +It will also contain an additional syslog tag before the standard Cisco +%TAG, this tag references the process that produced the log. +In order to use this Cisco IOS parser module with XR format messages both +of these additional fields must be ignored. + + +Examples +======== + +Listening multiple devices, some emitting origin information and some not +------------------------------------------------------------------------- + +We assume a scenario where we have some devices configured to emit origin +information whereas some others do not. In order to differentiate between +the two classes, rsyslog accepts input on different ports, one per class. +For each port, an input() object is defined, which binds the port to a +ruleset that uses the appropriately-configured parser. Except for the +different parsers, processing shall be identical for both classes. In our +first example we do this via a common ruleset which carries out the +actual processing: + +.. code-block:: none + + module(load="imtcp") + module(load="pmciscoios") + + input(type="imtcp" port="10514" ruleset="withoutOrigin") + input(type="imtcp" port="10515" ruleset="withOrigin") + + ruleset(name="common") { + ... do processing here ... + } + + ruleset(name="withoutOrigin" parser="rsyslog.ciscoios") { + /* this ruleset uses the default parser which was + * created during module load + */ + call common + } + + parser(name="custom.ciscoios.withOrigin" type="pmciscoios" + present.origin="on") + ruleset(name="withOrigin" parser="custom.ciscoios.withOrigin") { + /* this ruleset uses the parser defined immediately above */ + call common + } + + +Date stamp immediately following the origin +------------------------------------------- + +The example configuration above is a good solution. However, it is possible +to do the same thing in a somewhat condensed way, but if and only if the date +stamp immediately follows the origin. In that case, the parser has a chance to +detect if the origin is present or not. The key point here is to make sure +the parser checking for the origin is given before the default one, in which +case the first on will detect it does not match an pass on to the next +one inside the parser chain. However, this comes at the expense of additional +runtime overhead. The example below is **not** good practice -- it is given +as a purely educational sample to show some fine details of how parser +definitions interact. In this case, we can use a single listener. + +.. code-block:: none + + module(load="imtcp") + module(load="pmciscoios") + + input(type="imtcp" port="10514" ruleset="ciscoBoth") + + parser(name="custom.ciscoios.withOrigin" type="pmciscoios" + present.origin="on") + ruleset(name="ciscoBoth" + parser=["custom.ciscoios.withOrigin", "rsyslog.ciscoios"]) { + ... do processing here ... + } + + +Handling Cisco IOS and IOSXR formats +------------------------------------ + +The following sample demonstrates how to handle Cisco IOS and IOSXR formats + +.. code-block:: none + + module(load="imudp") + module(load="pmciscoios") + + input(type="imudp" port="10514" ruleset="ios") + input(type="imudp" port="10515" ruleset="iosxr") + + ruleset(name="common") { + ... do processing here ... + } + + ruleset(name="ios" parser="rsyslog.ciscoios") { + call common + } + + parser(name="custom.ciscoios.withXr" type="pmciscoios" + present.xr="on") + ruleset(name="iosxr" parser="custom.ciscoios.withXr"] { + call common + } + + |