1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
<html><head><title>Actions - rsyslog.conf</title></head>
4
<p>This is a part of the rsyslog.conf documentation.</p>
5
<a href="rsyslog_conf.html">back</a>
7
<p>The action field of a rule describes what to do with the
8
message. In general, message content is written to a kind of "logfile".
9
But also other actions might be done, like writing to a database table
10
or forwarding to another host.<br>
12
Templates can be used with all actions. If used, the specified template
13
is used to generate the message content (instead of the default
14
template). To specify a template, write a semicolon after the action
15
value immediately followed by the template name.<br>
17
Beware: templates MUST be defined BEFORE they are used. It is OK to
18
define some templates, then use them in selector lines, define more
19
templates and use use them in the following selector lines. But it is
20
NOT permitted to use a template in a selector line that is above its
21
definition. If you do this, the action will be ignored.</p>
22
<p><b>You can have multiple actions for a single selector </b> (or
23
more precisely a single filter of such a selector line). Each action
24
must be on its own line and the line must start with an ampersand
25
('&') character and have no filters. An example would be</p>
26
<p><code><b>*.=crit rger<br>
28
& /var/log/critmsgs</b></code></p>
29
<p>These three lines send critical messages to the user rger and
30
root and also store them in /var/log/critmsgs. <b>Using multiple
31
actions per selector is</b> convenient and also <b>offers
32
a performance benefit</b>. As the filter needs to be evaluated
33
only once, there is less computation required to process the directive
34
compared to the otherwise-equal config directives below:</p>
35
<p><code><b>*.=crit rger<br>
37
*.=crit /var/log/critmsgs</b></code></p>
40
<p>Typically messages are logged to real files. The file has to
41
be specified with full pathname, beginning with a slash "/''.<br>
44
You may prefix each entry with the minus "-'' sign to omit syncing the
45
file after every logging. Note that you might lose information if the
46
system crashes right behind a write attempt. Nevertheless this might
47
give you back some performance, especially if you run programs that use
48
logging in a very verbose manner.</p>
49
<p>If your system is connected to a reliable UPS and you receive
50
lots of log data (e.g. firewall logs), it might be a very good idea to
52
syncing by specifying the "-" in front of the file name. </p>
53
<p><b>The filename can be either static </b>(always
54
the same) or <b>dynamic</b> (different based on message
55
received). The later is useful if you would automatically split
56
messages into different files based on some message criteria. For
57
example, dynamic file name selectors allow you to split messages into
58
different files based on the host that sent them. With dynamic file
59
names, everything is automatic and you do not need any filters. </p>
60
<p>It works via the template system. First, you define a template
61
for the file name. An example can be seen above in the description of
62
template. We will use the "DynFile" template defined there. Dynamic
63
filenames are indicated by specifying a questions mark "?" instead of a
64
slash, followed by the template name. Thus, the selector line for our
65
dynamic file name would look as follows:</p>
67
<code>*.* ?DynFile</code>
69
<p>That's all you need to do. Rsyslog will now automatically
70
generate file names for you and store the right messages into the right
71
files. Please note that the minus sign also works with dynamic file
72
name selectors. Thus, to avoid syncing, you may use</p>
74
<code>*.* -?DynFile</code></blockquote>
75
<p>And of course you can use templates to specify the output
78
<code>*.* ?DynFile;MyTemplate</code></blockquote>
79
<p><b>A word of caution:</b> rsyslog creates files as
80
needed. So if a new host is using your syslog server, rsyslog will
81
automatically create a new file for it.</p>
82
<p><b>Creating directories is also supported</b>. For
83
example you can use the hostname as directory and the program name as
86
<code>$template DynFile,"/var/log/%HOSTNAME%/%programname%.log"</code></blockquote>
88
<p>This version of rsyslogd(8) has support for logging output to
89
named pipes (fifos). A fifo or named pipe can be used as a destination
90
for log messages by prepending a pipe symbol ("|'') to the name of the
91
file. This is handy for debugging. Note that the fifo must be created
92
with the mkfifo(1) command before rsyslogd(8) is started.</p>
93
<h3>Terminal and Console</h3>
94
<p>If the file you specified is a tty, special tty-handling is
95
done, same with /dev/console.</p>
96
<h3>Remote Machine</h3>
97
<p>Rsyslogd provides full remote logging, i.e. is able to send
98
messages to a remote host running rsyslogd(8) and to receive messages
99
from remote hosts. Using this feature you're able to control all syslog
100
messages on one host, if all other machines will log remotely to that.
102
administration needs.<br>
104
<b>Please note that this version of rsyslogd by default does NOT
105
forward messages it has received from the network to another host.
106
Specify the "-h" option to enable this.</b></p>
107
<p>To forward messages to another host, prepend the hostname with
108
the at sign ("@"). A single at sign means that messages will
109
be forwarded via UDP protocol (the standard for syslog). If you prepend
110
two at signs ("@@"), the messages will be transmitted via TCP. Please
111
note that plain TCP based syslog is not officially standardized, but
112
most major syslogds support it (e.g. syslog-ng or WinSyslog). The
113
forwarding action indicator (at-sign) can be followed by one or more
114
options. If they are given, they must be immediately (without a space)
115
following the final at sign and be enclosed in parenthesis. The
116
individual options must be separated by commas. The following options
117
are right now defined:</p>
118
<table id="table2" border="1" width="100%">
122
<p align="center"><b>z<number></b></p>
124
<td>Enable zlib-compression for the message. The
125
<number> is the compression level. It can be 1 (lowest
126
gain, lowest CPU overhead) to 9 (maximum compression, highest CPU
127
overhead). The level can also be 0, which means "no compression". If
128
given, the "z" option is ignored. So this does not make an awful lot of
129
sense. There is hardly a difference between level 1 and 9 for typical
130
syslog messages. You can expect a compression gain between 0% and 30%
131
for typical messages. Very chatty messages may compress up to 50%, but
132
this is seldom seen with typically traffic. Please note that rsyslogd
133
checks the compression gain. Messages with 60 bytes or less will never
134
be compressed. This is because compression gain is pretty unlikely and
135
we prefer to save CPU cycles. Messages over that size are always
136
compressed. However, it is checked if there is a gain in compression
137
and only if there is, the compressed message is transmitted. Otherwise,
138
the uncompressed messages is transmitted. This saves the receiver CPU
139
cycles for decompression. It also prevents small message to actually
140
become larger in compressed form.
141
<p><b>Please note that when a TCP transport is used,
142
compression will also turn on syslog-transport-tls framing. See the "o"
143
option for important information on the implications.</b></p>
144
<p>Compressed messages are automatically detected and
145
decompressed by the receiver. There is nothing that needs to be
146
configured on the receiver side.</p>
151
<p align="center"><b>o</b></p>
153
<td><b>This option is experimental. Use at your own
154
risk and only if you know why you need it! If in doubt, do NOT turn it
156
<p>This option is only valid for plain TCP based
157
transports. It selects a different framing based on IETF internet draft
158
syslog-transport-tls-06. This framing offers some benefits over
159
traditional LF-based framing. However, the standardization effort is
160
not yet complete. There may be changes in upcoming versions of this
161
standard. Rsyslog will be kept in line with the standard. There is some
162
chance that upcoming changes will be incompatible to the current
163
specification. In this case, all systems using -transport-tls framing
164
must be upgraded. There will be no effort made to retain compatibility
165
between different versions of rsyslog. The primary reason for that is
166
that it seems technically impossible to provide compatibility between
167
some of those changes. So you should take this note very serious. It is
168
not something we do not *like* to do (and may change our mind if enough
169
people beg...), it is something we most probably *can not* do for
170
technical reasons (aka: you can beg as much as you like, it won't
171
change anything...).</p>
172
<p>The most important implication is that compressed syslog
173
messages via TCP must be considered with care. Unfortunately, it is
174
technically impossible to transfer compressed records over traditional
175
syslog plain tcp transports, so you are left with two evil choices...</p>
181
The hostname may be followed by a colon and the destination port.</p>
182
<p>The following is an example selector line with forwarding:</p>
183
<p>*.* @@(o,z9)192.168.0.1:1470</p>
184
<p>In this example, messages are forwarded via plain TCP with
185
experimental framing and maximum compression to the host 192.168.0.1 at
187
<p>*.* @192.168.0.1</p>
188
<p>In the example above, messages are forwarded via UDP to the
189
machine 192.168.0.1, the destination port defaults to 514. Messages
190
will not be compressed.</p>
191
<p>Note that IPv6 addresses contain colons. So if an IPv6 address is specified
192
in the hostname part, rsyslogd could not detect where the IP address ends
193
and where the port starts. There is a syntax extension to support this:
194
put squary brackets around the address (e.g. "[2001::1]"). Square
195
brackets also work with real host names and IPv4 addresses, too.
196
<p>A valid sample to send messages to the IPv6 host 2001::1 at port 515
198
<p>*.* @[2001::1]:515
199
<p>This works with TCP, too.
200
<p><b>Note to sysklogd users:</b> sysklogd does <b>not</b>
201
support RFC 3164 format, which is the default forwarding template in
202
rsyslog. As such, you will experience duplicate hostnames if rsyslog is
203
the sender and sysklogd is the receiver. The fix is simple: you need to
204
use a different template. Use that one:</p>
205
<p class="MsoPlainText">$template
206
sysklogd,"<%PRI%>%TIMESTAMP% %syslogtag%%msg%\""<br>
207
*.* @192.168.0.1;sysklogd</p>
208
<h3>List of Users</h3>
209
<p>Usually critical messages are also directed to "root'' on
210
that machine. You can specify a list of users that shall get the
211
message by simply writing the login. You may specify more than one user
212
by separating them with commas (",''). If they're logged in they get
213
the message. Don't think a mail would be sent, that might be too late.</p>
214
<h3>Everyone logged on</h3>
215
<p>Emergency messages often go to all users currently online to
216
notify them that something strange is happening with the system. To
217
specify this wall(1)-feature use an asterisk ("*'').</p>
219
<p>This is a generic way to call an output plugin. The plugin
220
must support this functionality. Actual parameters depend on the
221
module, so see the module's doc on what to supply. The general syntax
223
<p>:modname:params;template</p>
224
<p>Currently, the ommysql database output module supports this
225
syntax (in addtion to the ">" syntax it traditionally
226
supported). For ommysql, the module name is "ommysql" and the params
227
are the traditional ones. The ;template part is not module specific, it
228
is generic rsyslog functionality available to all modules.</p>
229
<p>As an example, the ommysql module may be called as follows:</p>
230
<p>:ommysql:dbhost,dbname,dbuser,dbpassword;dbtemplate</p>
231
<p>For details, please see the "Database Table" section of this
233
<p>Note: as of this writing, the ":modname:" part is hardcoded
234
into the module. So the name to use is not necessarily the name the
235
module's plugin file is called.</p>
236
<h3>Database Table</h3>
237
<p>This allows logging of the message to a database table.
238
Currently, only MySQL databases are supported. However, other database
239
drivers will most probably be developed as plugins. By default, a <a href="http://www.monitorware.com/">MonitorWare</a>-compatible
240
schema is required for this to work. You can create that schema with
241
the createDB.SQL file that came with the rsyslog package. You can also<br>
242
use any other schema of your liking - you just need to define a proper
243
template and assign this template to the action.<br>
245
The database writer is called by specifying a greater-then sign
246
(">") in front of the database connect information. Immediately
248
sign the database host name must be given, a comma, the database name,
249
another comma, the database user, a comma and then the user's password.
250
If a specific template is to be used, a semicolon followed by the
251
template name can follow the connect information. This is as follows:<br>
253
>dbhost,dbname,dbuser,dbpassword;dbtemplate</p>
254
<p><b>Important: to use the database functionality, the
255
MySQL output module must be loaded in the config file</b> BEFORE
256
the first database table action is used. This is done by placing the</p>
257
<p><code><b>$ModLoad ommysql</b></code></p>
258
<p>directive some place above the first use of the database write
259
(we recommend doing at the the beginning of the config file).</p>
261
<p>If the discard action is carried out, the received message is
262
immediately discarded. No further processing of it occurs. Discard has
263
primarily been added to filter out messages before carrying on any
264
further processing. For obvious reasons, the results of "discard" are
265
depending on where in the configuration file it is being used. Please
266
note that once a message has been discarded there is no way to retrieve
267
it in later configuration file lines.</p>
268
<p>Discard can be highly effective if you want to filter out some
269
annoying messages that otherwise would fill your log files. To do that,
270
place the discard actions early in your log files. This often plays
271
well with property-based filters, giving you great freedom in
272
specifying what you do not want.</p>
273
<p>Discard is just the single tilde character with no further
277
<p>*.* ~</p>
278
<p>discards everything (ok, you can achive the same by not
279
running rsyslogd at all...).</p>
280
<h3>Output Channel</h3>
281
<p>Binds an output channel definition (see there for details) to
282
this action. Output channel actions must start with a $-sign, e.g. if
283
you would like to bind your output channel definition "mychannel" to
284
the action, use "$mychannel". Output channels support template
285
definitions like all all other actions.</p>
286
<h3>Shell Execute</h3>
287
<p>This executes a program in a subshell. The program is passed
288
the template-generated message as the only command line parameter.
289
Rsyslog waits until the program terminates and only then continues to
291
<p>^program-to-execute;template</p>
292
<p>The program-to-execute can be any valid executable. It
293
receives the template string as a single parameter (argv[1]).</p>
294
<p><b>WARNING:</b> The Shell Execute action was added
295
to serve an urgent need. While it is considered reasonable save when
296
used with some thinking, its implications must be considered. The
297
current implementation uses a system() call to execute the command.
298
This is not the best way to do it (and will hopefully changed in
299
further releases). Also, proper escaping of special characters is done
300
to prevent command injection. However, attackers always find smart ways
301
to circumvent escaping, so we can not say if the escaping applied will
302
really safe you from all hassles. Lastly, rsyslog will wait until the
303
shell command terminates. Thus, a program error in it (e.g. an infinite
304
loop) can actually disable rsyslog. Even without that, during the
305
programs run-time no messages are processed by rsyslog. As the IP
306
stacks buffers are quickly overflowed, this bears an increased risk of
307
message loss. You must be aware of these implications. Even though they
308
are severe, there are several cases where the "shell execute" action is
309
very useful. This is the reason why we have included it in its current
310
form. To mitigate its risks, always a) test your program thoroughly, b)
311
make sure its runtime is as short as possible (if it requires a longer
312
run-time, you might want to spawn your own sub-shell asynchronously),
313
c) apply proper firewalling so that only known senders can send syslog
314
messages to rsyslog. Point c) is especially important: if rsyslog is
315
accepting message from any hosts, chances are much higher that an
316
attacker might try to exploit the "shell execute" action.</p>
317
<h3>Template Name</h3>
318
<p>Every ACTION can be followed by a template name. If so, that
319
template is used for message formatting. If no name is given, a
320
hard-coded default template is used for the action. There can only be
321
one template name for each given action. The default template is
322
specific to each action. For a description of what a template is and
323
what you can do with it, see "TEMPLATES" at the top of this document.</p>
326
<p>[<a href="manual.html">manual index</a>]
327
[<a href="rsyslog_conf.html">rsyslog.conf</a>]
328
[<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
329
<p><font size="2">This documentation is part of the
330
<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
331
Copyright © 2008 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
332
<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL
333
version 2 or higher.</font></p>
added
removed
doc/rsyslog_conf_actions.html
