doc: added v7 conf samples to omudpspoof doc

1 files changed, 77 insertions, 5 deletions

diff --git a/doc/omudpspoof.html b/doc/omudpspoof.html
index 811c73e2..ffbd04e1 100644
--- a/doc/omudpspoof.html
+++ b/doc/omudpspoof.html
@@ -7,9 +7,10 @@
 
 <h1>UDP spoofing output module (omudpspoof)</h1>
 <p><b>Module Name:&nbsp;&nbsp;&nbsp; omstdout</b></p>
-<p><b>Author: </b>David Lang  &lt;david@lang.hm&gt; and Rainer Gerhards
-&lt;rgerhards@adiscon.com&gt;</p>
-<p><b>Available Since</b>: 5.1.3</p>
+<p><b>Authors: </b>Rainer Gerhards &lt;rgerhards@adiscon.com&gt;
+and David Lang  &lt;david@lang.hm&gt; 
+</p>
+<p><b>Available Since</b>: 5.1.3 / v7 config since 7.2.5</p>
 <p><b>Description</b>:</p>
 <p>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
@@ -33,7 +34,7 @@ source ports.
 	Template to use as message text.
 	<br></li><br>
 
-	<li><strong>sourcetemplate </strong>[Word]<br>
+	<li><strong>SourceTemplate </strong>[Word]<br>
 	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
@@ -59,7 +60,7 @@ source ports.
 	Maximum MTU supported by the network. Default respects Ethernet and must
 	usually not be adjusted. Setting a too-high MTU can lead to message loss,
 	too low to excess message fragmentation. Change only if you really know what
-	you are doing.
+	you are doing. This is always given in number of bytes.
 	<br></li><br>
 </ul>
 <p><b>pre-v7 Configuration Directives</b>:</p>
@@ -85,6 +86,77 @@ fragmented, up to a total upper limit of 64K (induced by UDP). Message sizes ove
 64K will be truncated. For older versions, messages over 1472 may be totally discarded
 or truncated, depending on version and environment.
 </ul>
+
+<p><b>Config Samples</b></p>
+<p>The following sample forwards all syslog messages in standard form to the
+remote server server.example.com. The original sender's address is used. We do not
+care about the source port. This example is considered the typical use case for
+omudpspoof.
+</p>
+<textarea rows="3" cols="80">module(load="omudpspoof")
+action(type="omudpspoof" target="server.example.com")
+</textarea>
+
+<p>The following sample forwards all syslog messages in unmodified form to the
+remote server server.example.com. The sender address 192.0.2.1 with fixed
+source port 514 is used.
+</p>
+<textarea rows="7" cols="80">module(load="omudpspoof")
+template(name="spoofaddr" type="string" string="192.0.2.1")
+template(name="spooftemplate" type="string" string="%rawmsg%")
+action(type="omudpspoof" target="server.example.com"
+       sourcetemplate="spoofaddr" template="spooftemplate"
+       sourceport.start="514" sourceport.end="514)
+</textarea>
+<p>The following sample is exatly like the previous, but it specifies a larger size
+MTU. If, for example, the envrionment supports Jumbo Ethernet frames, increasing the
+MTU is useful as it reduces packet fragmentation, which most often is the source of
+problems. Note that setting the MTU to a value larger than the local-attached network
+supports will lead to send errors and loss of message. So use with care!
+</p>
+<textarea rows="8" cols="80">module(load="omudpspoof")
+template(name="spoofaddr" type="string" string="192.0.2.1")
+template(name="spooftemplate" type="string" string="%rawmsg%")
+action(type="omudpspoof" target="server.example.com"
+       sourcetemplate="spoofaddr" template="spooftemplate"
+       sourceport.start="514" sourceport.end="514
+       mtu="8000")
+</textarea>
+<p>Of course, the action can be combined with any type of filter, for
+example a tradition PRI filter:</p>
+<textarea rows="8" cols="80">module(load="omudpspoof")
+template(name="spoofaddr" type="string" string="192.0.2.1")
+template(name="spooftemplate" type="string" string="%rawmsg%")
+local0.* action(type="omudpspoof" target="server.example.com"
+                sourcetemplate="spoofaddr" template="spooftemplate"
+                sourceport.start="514" sourceport.end="514
+                mtu="8000")
+</textarea>
+<p>... or any complex expression-based filter:</p>
+<textarea rows="8" cols="80">module(load="omudpspoof")
+template(name="spoofaddr" type="string" string="192.0.2.1")
+template(name="spooftemplate" type="string" string="%rawmsg%")
+if prifilt("local0.*") and $msg contains "error" then
+         action(type="omudpspoof" target="server.example.com"
+                sourcetemplate="spoofaddr" template="spooftemplate"
+                sourceport.start="514" sourceport.end="514
+                mtu="8000")
+</textarea>
+<p>and of course it can also be combined with as many other actions
+as one likes:</p>
+<textarea rows="11" cols="80">module(load="omudpspoof")
+template(name="spoofaddr" type="string" string="192.0.2.1")
+template(name="spooftemplate" type="string" string="%rawmsg%")
+if prifilt("local0.*") and $msg contains "error" then {
+         action(type="omudpspoof" target="server.example.com"
+                sourcetemplate="spoofaddr" template="spooftemplate"
+                sourceport.start="514" sourceport.end="514
+                mtu="8000")
+         action(type="omfile" file="/var/log/somelog")
+	 stop # or whatever...
+}
+</textarea>
+
 <p><b>Legacy Sample (pre-v7):</b></p>
 <p>The following sample forwards all syslog messages in standard form to the
 remote server server.example.com. The original sender's address is used. We do not