diff options
Diffstat (limited to 'source/configuration/modules/omudpspoof.rst')
| -rw-r--r-- | source/configuration/modules/omudpspoof.rst | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/source/configuration/modules/omudpspoof.rst b/source/configuration/modules/omudpspoof.rst new file mode 100644 index 0000000..2edb106 --- /dev/null +++ b/source/configuration/modules/omudpspoof.rst @@ -0,0 +1,209 @@ +************************************** +omudpspoof: UDP spoofing output module +************************************** + +=========================== =========================================================================== +**Module Name:** **omudpspoof** +**Author:** David Lang <david@lang.hm> and `Rainer Gerhards <https://rainer.gerhards.net/>`_ <rgerhards@adiscon.com> +**Available Since:** 5.1.3 +=========================== =========================================================================== + + +Purpose +======= + +This module is similar to the regular UDP forwarder, but permits to +spoof the sender address. Also, it enables to circle through a number of +source ports. + +**Important**: This module **requires root permissions**. This is a hard +requirement because raw socket access is necessary to fake UDP sender +addresses. As such, rsyslog cannot drop privileges if this module is +to be used. Ensure that you do **not** use `$PrivDropToUser` or +`$PrivDropToGroup`. Many distro default configurations (notably Ubuntu) +contain these statements. You need to remove or comment them out if you +want to use `omudpspoof`. + + +Configuration Parameters +======================== + +.. note:: + + Parameter names are case-insensitive. + +Module Parameters +----------------- + +Template +^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "RSYSLOG_TraditionalForwardFormat", "no", "none" + +This setting instructs omudpspoof to use a template different from +the default template for all of its actions that do not have a +template specified explicitly. + + +Action Parameters +----------------- + +Target +^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "none", "yes", "``$ActionOMUDPSpoofTargetHost``" + +Host that the messages shall be sent to. + + +Port +^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "514", "no", "``$ActionOMUDPSpoofTargetPort``" + +Remote port that the messages shall be sent to. Default is 514. + + +SourceTemplate +^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "RSYSLOG_omudpspoofDfltSourceTpl", "no", "``$ActionOMOMUDPSpoofSourceNameTemplate``" + +This is the name of the template that contains a numerical IP +address that is to be used as the source system IP address. While it +may often be a constant value, it can be generated as usual via the +property replacer, as long as it is a valid IPv4 address. If not +specified, the build-in default template +RSYSLOG\_omudpspoofDfltSourceTpl is used. This template is defined as +follows: +$template RSYSLOG\_omudpspoofDfltSourceTpl,"%fromhost-ip%" +So in essence, the default template spoofs the address of the system +the message was received from. This is considered the most important +use case. + + +SourcePort.start +^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "32000", "no", "``$ActionOMUDPSpoofSourcePortStart``" + +Specify the start value for circling the source ports. Start must be +less than or equal to sourcePort.End. + + +SourcePort.End +^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "42000", "no", "``$ActionOMUDPSpoofSourcePortEnd``" + +Specify the end value for circling the source ports. End must be +equal to or more than sourcePort.Start. + + +MTU +^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "integer", "1500", "no", "none" + +Maximum packet length to send. + + +Template +^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "RSYSLOG_TraditionalForwardFormat", "no", "``$ActionOMUDPSpoofDefaultTemplate``" + +This setting instructs omudpspoof to use a template different from +the default template for all of its actions that do not have a +template specified explicitly. + + +Caveats/Known Bugs +================== + +- **IPv6** is currently not supported. If you need this capability, + please let us know via the rsyslog mailing list. + +- Throughput is MUCH smaller than when using omfwd module. + + +Examples +======== + +Forwarding message through multiple ports +----------------------------------------- + +Forward the message to 192.168.1.1, using original source and port between 10000 and 19999. + +.. code-block:: none + + Action ( + type="omudpspoof" + target="192.168.1.1" + sourceport.start="10000" + sourceport.end="19999" + ) + + +Forwarding message using another source address +----------------------------------------------- + +Forward the message to 192.168.1.1, using source address 192.168.111.111 and default ports. + +.. code-block:: none + + Module ( + load="omudpspoof" + ) + Template ( + name="spoofaddr" + type="string" + string="192.168.111.111" + ) + Action ( + type="omudpspoof" + target="192.168.1.1" + sourcetemplate="spoofaddr" + ) + + |