summaryrefslogtreecommitdiff
path: root/doc/imudp.html
blob: 6c949536841971630898bb3803d72f56450ecbdc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en">
<title>UDP Syslog Input Module (imudp)</title>
</head>

<body>
<a href="rsyslog_conf_modules.html">back to rsyslog module overview</a>

<h1>UDP Syslog Input Module</h1>
<p><b>Module Name:&nbsp;&nbsp;&nbsp; imudp</b></p>
<p><b>Author: </b>Rainer Gerhards &lt;rgerhards@adiscon.com&gt;</p>
<p><b>Multi-Ruleset Support: </b>since 5.3.2
<p><b>Description</b>:</p>
<p>Provides the ability to receive syslog messages via UDP.
<p>Multiple receivers may be configured by specifying
multiple input actions.
</p>

<p><b>Configuration Parameters</b>:</p>
<p><b>Module Parameters</b>:</p>
<ul>
<li><b>TimeRequery</b> &lt;nbr-of-times&gt;<br>
this is a performance
optimization. Getting the system time is very costly. With this setting, imudp can
be instructed to obtain the precise time only once every n-times. This logic is
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.
<li><b>SchedulingPolicy</b> &lt;rr/fifo/other&gt;<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> &lt;number&gt;<br>
Scheduling priority to use. 
</ul>
<p><b>Input Parameters</b>:</p>
<ul>
<li><b>Address</b> &lt;IP&gt;<br>
local IP address (or name) the UDP listens should bind to</li>
<li><b>Port</b> &lt;port&gt;<br>
default 514, start UDP server on this port. Either a single port can be specified or an array of ports. If multiple ports are specified, a listener will be automatically started for each port. Thus, no additional inputs need to be configured.
<br>Single port: Port="514"
<br>Array of ports: Port=["514","515","10514","..."]</li>
<li><b>Ruleset</b> &lt;ruleset&gt;<br>
Binds the listener to a specific <a href="multi_ruleset.html">ruleset</a>.</li>
<li><b>RateLimit.Interval</b> [number] - (available since 7.3.1) specifies the rate-limiting
interval in seconds.  Default value is 0, which turns off rate limiting. Set it to a number
of seconds (5 recommended) to activate rate-limiting.
</li>
<li><b>RateLimit.Burst</b> [number] - (available since 7.3.1) specifies the rate-limiting
burst in number of messages. Default is 10,000.
</li>
<li><b>InputName</b> [name] - (available since 7.3.9) specifies the value of
the inputname. In older versions, this was always "imudp" for all listeners,
which still i the default.
Starting with 7.3.9 it can be set to different values for each listener.
Note that when a single input statement defines multipe listner ports, the
inputname will be the same for all of them. If you want to differentiate in that
case, use "InputName.AppendPort" to make them unique.
Note that the "InputName" parameter can be an empty string. In that case, the
corresponding inputname property will obviously also be the empty string. This
is primarily meant to be used togehter with "InputName.AppendPort" to set the
inputname equal to the port.
</li>
<li><b>InputName.AppendPort</b> [on/<b>off</b>] - (available since 7.3.9)
appends the port the the inputname. Note that when no inputname is specified,
the default of "imudp" is used and the port is appended to that default. So,
for example, a listner port of 514 in that case will lead to an inputname
of "imudp514". The ability to append a port is most useful when multiple ports
are defined for a single input and each of the inputnames shall be unique.
Note that there currently is no differentiation between IPv4/v6 listners on
the same port.
</li>
</ul>
<b>Caveats/Known Bugs:</b>
<ul>
<li>Scheduling parameters are set <b>after</b> privileges have been dropped.
In most cases, this means that setting them will not be possible after
privilege drop. This may be worked around by using a sufficiently-privileged
user account.
</li>
</ul>
<p><b>Samples:</b></p>
<p>This sets up an UPD server on port 514:<br>
</p>
<textarea rows="3" cols="60">module(load="imudp") # needs to be done just once
input(type="imudp" port="514")
</textarea>

<p>In the next example, we set up three listners at ports 10514, 10515 and 10516
and assign a listner name of "udp" to it, followed by the port number:
</p>
<textarea rows="4" cols="60">module(load="imudp")
input(type="imudp" port=["10514","10515","10516"]
      inputname="udp" inputname.appendPort="on")
</textarea>

<p>The next example is almost equal to the previous one, but
now the inputname property will just be set to the port number.
So if a message was received on port 10515, the input name will be
"10515" in this example whereas it was "udp10515" in the previous one.
Note that to do that we set the inputname to the empty string.
</p>
<textarea rows="4" cols="60">module(load="imudp")
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.
</p>
<ul>
<li>$UDPServerAddress &lt;IP&gt;<br>
equivalent to: Address </li>
<li>$UDPServerRun &lt;port&gt;<br>
equivalent to: Port </li>
<li>$UDPServerTimeRequery &lt;nbr-of-times&gt;<br>
equivalent to: TimeRequery 
<li>$InputUDPServerBindRuleset &lt;ruleset&gt;<br>
equivalent to: Ruleset </li>
<li>$IMUDPSchedulingPolicy &lt;rr/fifo/other&gt; Available since 4.7.4+, 5.7.3+, 6.1.3+.<br>
equivalent to: SchedulingPolicy 
<li>$IMUDPSchedulingPriority &lt;number&gt; Available since 4.7.4+, 5.7.3+, 6.1.3+.<br>
equivalent to: SchedulingPriority 
</ul>
<p><b>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
$UDPServerRun 514
</textarea>

<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
<p><font size="2">This documentation is part of the
<a href="http://www.rsyslog.com/">rsyslog</a>
project.<br>
Copyright &copy; 2009-2013 by
<a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
<a href="http://www.adiscon.com/">Adiscon</a>.
Released under the GNU GPL version 3 or higher.</font></p>
</body></html>