diff options
Diffstat (limited to 'doc/imudp.html')
| -rw-r--r-- | doc/imudp.html | 70 |
1 files changed, 67 insertions, 3 deletions
diff --git a/doc/imudp.html b/doc/imudp.html index a8dbca3..b57eb71 100644 --- a/doc/imudp.html +++ b/doc/imudp.html @@ -29,13 +29,42 @@ only activated if messages come in at a very fast rate, so doing less frequent time calls should usually be acceptable. The default value is two, because we have seen that even without optimization the kernel often returns twice the identical time. You can set this value as high as you like, but do so at your own risk. The higher -the value, the less precise the timestamp. +the value, the less precise the timestamp.<br> +<b>Note:</b> the timeRequery is done based on executed system calls (<b>not</b> +messages received). So when batch +sizes are used, multiple messages are received with one system call. All of these +messages always receive the same timestamp, as they are effectively received at the +same time. When there is very high traffic and successive system calls immediately +return the next batch of messages, the time requery logic kicks in, which means that +by default time is only queried for every second batch. Again, this should not cause +a too-much deviation as it requires messages to come in very rapidly. However, we advise +not to set the "timeRequery" parameter to a large value (larger than 10) if input +batches are used. <li><b>SchedulingPolicy</b> <rr/fifo/other><br> Can be used the set the scheduler priority, if the necessary functionality is provided by the platform. Most useful to select "fifo" for real-time processing under Linux (and thus reduce chance of packet loss). <li><b>SchedulingPriority</b> <number><br> Scheduling priority to use. +<li><b>batchSize</b> <number><br> +This parameter is only meaningful if the system support recvmmsg() (newer Linux +OSs do this). The parameter is silently ignored if the system does not support +it. If supported, it sets the maximum number of UDP messages that can be obtained +with a single OS call. For systems with high UDP traffic, a relatively high batch +size can reduce system overhead and improve performance. However, this parameter +should not be overdone. For each buffer, max message size bytes are statically +required. Also, a too-high number leads to reduced efficiency, as some structures +need to be completely initialized before the OS call is done. We would suggest to not +set it above a value of 128, except if experimental results show that this is useful. +<li><b>threads</b> <number> (default 1), available since 7.5.5<br> +Number of worker threads to process incoming messages. These +threads are utilized to pull data off the network. On a busy system, additional +threads (but not more than there are CPUs/Cores) can help improving +performance and avoiding message loss. Note that with too many threads, performance +can suffer. +There is a hard upper limit on the number of threads that can be defined. +Currently, this limit is set to 32. It may increase in the future when massive +multicore processors become available. </ul> <p><b>Input Parameters</b>:</p> <ul> @@ -75,7 +104,36 @@ are defined for a single input and each of the inputnames shall be unique. Note that there currently is no differentiation between IPv4/v6 listeners on the same port. </li> +<li><b>defaultTZ</b> <timezone-info><br> +This is an <b>experimental</b> parameter; details may change at any time and it may +also be discoutinued without any early warning.<br> +Permits to set a default timezone for this listener. This is useful when working with +legacy syslog (RFC3164 et al) residing in different timezones. If set it will be used as +timezone for all messages <b>that do not contain timezone info</b>. +Currently, the format <b>must</b> be "+/-hh:mm", e.g. "-05:00", "+01:30". Other formats, +including TZ names (like EST) are NOT yet supported. Note that consequently no daylight +saving settings are evaluated when working with timezones. If an invalid format is used, +"interesting" things can happen, among them malformed timestamps and rsyslogd segfaults. +This will obviously be changed at the time this feature becomes non-experimental.</li> +<li><b>rcvbufSize</b> [size] - (available since 7.5.3) +This request a socket receive buffer of specific size from the operating system. +It is an expert parameter, which should only be changed for a good reason. Note that +setting this parameter disables Linux auto-tuning, which usually works pretty well. +The default value is 0, which means "keep the OS buffer size unchanged". This is a size +value. So in addition to pure integer values, sizes like "256k", "1m" and the like can +be specified. Note that setting very large sizes may require root or other special +privileges. Also note that the OS may slightly adjust the value or shrink it to a +system-set max value if the user is not sufficiently privileged. Technically, this +parameter will result in a setsockopt() call with SO_RCVBUF (and SO_RCVBUFFORCE if it +is available). </ul> +<p><b>See Also</b> +<ul> +<li>Description of +<a href="http://www.rsyslog.com/rsyslog-statistic-counter/">rsyslog statistic counters</a> +This also describes all imudp counters. +</ul> +<p> <b>Caveats/Known Bugs:</b> <ul> <li>Scheduling parameters are set <b>after</b> privileges have been dropped. @@ -91,6 +149,13 @@ user account. input(type="imudp" port="514") </textarea> +<p>The following sample is mostly equivalent to the first one, but request a +larger rcvuf size. Note that 1m most probably will not be honored by the OS +until the user is sufficiently privileged.</p> +<textarea rows="3" cols="60">module(load="imudp") # needs to be done just once +input(type="imudp" port="514" rcvbufSize="1m") +</textarea> + <p>In the next example, we set up three listeners at ports 10514, 10515 and 10516 and assign a listner name of "udp" to it, followed by the port number: </p> @@ -110,7 +175,6 @@ input(type="imudp" port=["10514","10515","10516"] inputname="" inputname.appendPort="on") </textarea> - <p><b>Legacy Configuration Directives</b>:</p> <p>Multiple receivers may be configured by specifying $UDPServerRun multiple times. @@ -129,7 +193,7 @@ equivalent to: SchedulingPolicy <li>$IMUDPSchedulingPriority <number> Available since 4.7.4+, 5.7.3+, 6.1.3+.<br> equivalent to: SchedulingPriority </ul> -<p><b>Sample:</b></p> +<p><b>Legacy Sample:</b></p> <p>This sets up an UPD server on port 514:<br> </p> <textarea rows="3" cols="60">$ModLoad imudp # needs to be done just once |