This file is indexed.

/usr/share/doc/rsyslog-doc/html/rsyslog_conf_actions.html is in rsyslog-doc 7.4.4-1ubuntu2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>Actions - rsyslog.conf</title></head>
<body>
<p>This is a part of the rsyslog.conf documentation.</p>
<a href="rsyslog_conf.html">back</a>
<h2>Actions</h2>
Action object describe what is to be done with a message. They are
implemented via <a href="rsyslog_conf_modules.html#om">outpout modules</a>.
<p>The action object has different parameters:
<ul>
<li>those that apply to all actions and are action specific. These
    are documented below.
<li>parameters for the action queue. While they also apply to 
    all parameters, they are queue-specific, not action-specific (they
    are the same that are used in rulesets, for example).
<li>action-specific parameters. These are specific to a certain
    type of actions. They are documented by the output module
    in question.
</ul>
<h3>General Action Parameters</h3>
<ul>
	<li><b>name</b> word
	<br>used for statistics gathering and documentation
	<li><b>type</b> string
	<br>Mandatory parameter for every action. The name of the module that should be used. </li>
	<li><b>action.writeAllMarkMessages</b> on/off
	<br>Normally, mark messages are written to actions only if the action was not recently executed (by default, recently means within the past 20 minutes). If this setting is switched to "on", mark messages are always sent to actions, no matter how recently they have been executed. In this mode, mark messages can be used as a kind of heartbeat. Note that this option auto-resets to "off", so if you intend to use it with multiple actions, it must be specified in front off all selector lines that should provide this functionality. </li>
	<li><b>action.execOnlyEveryNthTime</b> integer
	<br>If configured, the next action will only be executed every n-th time. For example, if configured to 3, the first two messages that go into the action will be dropped, the 3rd will actually cause the action to execute, the 4th and 5th will be dropped, the 6th executed under the action, ... and so on. Note: this setting is automatically re-set when the actual action is defined.</li>
	<li><b>action.execOnlyEveryNthTimeout</b> integer
	<br>Has a meaning only if Action.ExecOnlyEveryNthTime is also configured for the same action. If so, the timeout setting specifies after which period the counting of "previous actions" expires and a new action count is begun. Specify 0 (the default) to disable timeouts.
Why is this option needed? Consider this case: a message comes in at, eg., 10am. That's count 1. Then, nothing happens for the next 10 hours. At 8pm, the next one occurs. That's count 2. Another 5 hours later, the next message occurs, bringing the total count to 3. Thus, this message now triggers the rule.
The question is if this is desired behavior? Or should the rule only be triggered if the messages occur within an e.g. 20 minute window? If the later is the case, you need a
<br>Action.ExecOnlyEveryNthTimeTimeout="1200"
<br>This directive will timeout previous messages seen if they are older than 20 minutes. In the example above, the count would now be always 1 and consequently no rule would ever be triggered. </li>
	<li><b>action.execOnlyOnceEveryInterval</b> integer
	<br>Execute action only if the last execute is at last <seconds> seconds in the past (more info in ommail, but may be used with any action)</li>
	<li><b>action.execOnlyWhenpReviousIsSuspended</b> on/off
	<br>This directive allows to specify if actions should always be executed ("off," the default) or only if the previous action is suspended ("on"). This directive works hand-in-hand with the multiple actions per selector feature. It can be used, for example, to create rules that automatically switch destination servers or databases to a (set of) backup(s), if the primary server fails. Note that this feature depends on proper implementation of the suspend feature in the output module. All built-in output modules properly support it (most importantly the database write and the syslog message forwarder).</li>
	<li><b>action.repeatedmsgcontainsoriginalmsg</b> on/off
	<br>"last message repeated n times" messages, if generated, have a different format that contains the message that is being repeated. Note that only the first "n" characters are included, with n to be at least 80 characters, most probably more (this may change from version to version, thus no specific limit is given). The bottom line is that n is large enough to get a good idea which message was repeated but it is not necessarily large enough for the whole message. (Introduced with 4.1.5). Once set, it affects all following actions.</li>
	<li><b>action.resumeRetryCount</b> integer
	<br>[default 0, -1 means eternal]</li>
	<li><b>action.resumeInterval</b> integer
	<br>Sets the ActionResumeInterval for the action. The interval provided is always in seconds. Thus, multiply by 60 if you need minutes and 3,600 if you need hours (not recommended).
When an action is suspended (e.g. destination can not be connected), the action is resumed for the configured interval. Thereafter, it is retried. If multiple retires fail, the interval is automatically extended. This is to prevent excessive ressource use for retires. After each 10 retries, the interval is extended by itself. To be precise, the actual interval is (numRetries / 10 + 1) * Action.ResumeInterval. so after the 10th try, it by default is 60 and after the 100th try it is 330.</li>
</ul>


<h2>Legacy Format</h2>
<p><b>Be warned that legacy action format is hard to get right. It is
recommended to use RainerScript-Style action format whenever possible!</b>
A key problem with legacy format is that a single action is defined via
multiple configurations lines, which may be spread all across rsyslog.conf.
Even the definition of multiple actions may be intermixed (often not
intentional!). If legacy actions format needs to be used (e.g. some modules
may not yet implement the RainerScript format), it is strongly recommended
to place all configuration statements pertaining to a single action
closely together.
<p>Please also note that legacy action parameters <b>do not</b> affect
RainerScript action objects. So if you define for example:

<code><pre>
$actionResumeRetryCount 10
action(type="omfwd" target="server1.example.net")
@@server2.example.net
</pre></code>

server1's "action.resumeRetryCount" parameter is <b>not</b> set, instead
server2's is!
<p>A goal of the new RainerScript action format was to avoid confusion
which parameters are actually used. As such, it would be counter-productive
to honor legacy action parameters inside a RainerScript definition. As 
result, both types of action definitions are strictly (and nicely)
separated from each other. The bottom line is that if RainerScript actions
are used, one does not need to care about which legacy action parameters may 
(still...) be in effect.
<p>
<p>Note that not all modules necessarily support legacy action format.
Especially newer modules are recommended to NOT support it.
<h3>Legacy Description</h3>
<p>Templates can be used with many actions. If used, the specified template
is used to generate the message content (instead of the default
template). To specify a template, write a semicolon after the action
value immediately followed by the template name.<br>
<br>
Beware: templates MUST be defined BEFORE they are used. It is OK to
define some templates, then use them in selector lines, define more
templates and use use them in the following selector lines. But it is
NOT permitted to use a template in a selector line that is above its
definition. If you do this, the action will be ignored.</p>
<p><b>You can have multiple actions for a single selector </b>&nbsp;(or
more precisely a single filter of such a selector line). Each action
must be on its own line and the line must start with an ampersand
('&amp;') character and have no filters. An example would be</p>
<p><code><b>*.=crit :omusrmsg:rger<br>
&amp; root<br>
&amp; /var/log/critmsgs</b></code></p>
<p>These three lines send critical messages to the user rger and
root and also store them in /var/log/critmsgs. <b>Using multiple
actions per selector is</b> convenient and also <b>offers
a performance benefit</b>. As the filter needs to be evaluated
only once, there is less computation required to process the directive
compared to the otherwise-equal config directives below:</p>
<p><code><b>*.=crit :omusrmsg:rger<br>
*.=crit root<br>
*.=crit /var/log/critmsgs</b></code></p>
<p>&nbsp;</p>
<h3>Regular File</h3>
<p>Typically messages are logged to real files. The file usually is
specified by full pathname, beginning with a slash "/".
Starting with version 4.6.2 and 5.4.1 (previous v5 version do NOT support this)
relative file names can also be specified. To do so, these must begin with a
dot. For example, use "./file-in-current-dir.log" to specify a file in the
current directory. Please note that rsyslogd usually changes its working 
directory to the root, so relative file names must be tested with care (they
were introduced primarily as a debugging vehicle, but may have useful other applications
as well).<br>
<br>
<br>
You may prefix each entry with the minus "-'' sign to omit syncing the
file after every logging. Note that you might lose information if the
system crashes right behind a write attempt. Nevertheless this might
give you back some performance, especially if you run programs that use
logging in a very verbose manner.</p>
<p>If your system is connected to a reliable UPS and you receive
lots of log data (e.g. firewall logs), it might be a very good idea to
turn of
syncing by specifying the "-" in front of the file name. </p>
<p><b>The filename can be either static </b>(always
the same) or <b>dynamic</b> (different based on message
received). The later is useful if you would automatically split
messages into different files based on some message criteria. For
example, dynamic file name selectors allow you to split messages into
different files based on the host that sent them. With dynamic file
names, everything is automatic and you do not need any filters. </p>
<p>It works via the template system. First, you define a template
for the file name. An example can be seen above in the description of
template. We will use the "DynFile" template defined there. Dynamic
filenames are indicated by specifying a questions mark "?" instead of a
slash, followed by the template name. Thus, the selector line for our
dynamic file name would look as follows:</p>
<blockquote>
<code>*.* ?DynFile</code>
</blockquote>
<p>That's all you need to do. Rsyslog will now automatically
generate file names for you and store the right messages into the right
files. Please note that the minus sign also works with dynamic file
name selectors. Thus, to avoid syncing, you may use</p>
<blockquote>
<code>*.* -?DynFile</code></blockquote>
<p>And of course you can use templates to specify the output
format:</p>
<blockquote>
<code>*.* ?DynFile;MyTemplate</code></blockquote>
<p><b>A word of caution:</b> rsyslog creates files as
needed. So if a new host is using your syslog server, rsyslog will
automatically create a new file for it.</p>
<p><b>Creating directories is also supported</b>. For
example you can use the hostname as directory and the program name as
file name:</p>
<blockquote>
<code>$template DynFile,"/var/log/%HOSTNAME%/%programname%.log"</code></blockquote>
<h3>Named Pipes</h3>
<p>This version of rsyslogd(8) has support for logging output to
named pipes (fifos). A fifo or named pipe can be used as a destination
for log messages by prepending a pipe symbol ("|'') to the name of the
file. This is handy for debugging. Note that the fifo must be created
with the mkfifo(1) command before rsyslogd(8) is started.</p>
<h3>Terminal and Console</h3>
<p>If the file you specified is a tty, special tty-handling is
done, same with /dev/console.</p>
<h3>Remote Machine</h3>
<p>Rsyslogd provides full remote logging, i.e. is able to send
messages to a remote host running rsyslogd(8) and to receive messages
from remote hosts. Using this feature you're able to control all syslog
messages on one host, if all other machines will log remotely to that.
This tears down administration needs.</p>
<p>To forward messages to another host, prepend the hostname with
the at sign ("@"). A single at sign means that messages will
be forwarded via UDP protocol (the standard for syslog). If you prepend
two at signs ("@@"), the messages will be transmitted via TCP. Please
note that plain TCP based syslog is not officially standardized, but
most major syslogds support it (e.g. syslog-ng or
<a href="http://www.winsyslog.com/">WinSyslog</a>). The
forwarding action indicator (at-sign) can be followed by one or more
options. If they are given, they must be immediately (without a space)
following the final at sign and be enclosed in parenthesis. The
individual options must be separated by commas. The following options
are right now defined:</p>
<table id="table2" border="1" width="100%">
<tbody>
<tr>
<td>
<p align="center"><b>z&lt;number&gt;</b></p>
</td>
<td>Enable zlib-compression for the message. The
&lt;number&gt; is the compression level. It can be 1 (lowest
gain, lowest CPU overhead) to 9 (maximum compression, highest CPU
overhead). The level can also be 0, which means "no compression". If
given, the "z" option is ignored. So this does not make an awful lot of
sense. There is hardly a difference between level 1 and 9 for typical
syslog messages. You can expect a compression gain between 0% and 30%
for typical messages. Very chatty messages may compress up to 50%, but
this is seldom seen with typically traffic. Please note that rsyslogd
checks the compression gain. Messages with 60 bytes or less will never
be compressed. This is because compression gain is pretty unlikely and
we prefer to save CPU cycles. Messages over that size are always
compressed. However, it is checked if there is a gain in compression
and only if there is, the compressed message is transmitted. Otherwise,
the uncompressed messages is transmitted. This saves the receiver CPU
cycles for decompression. It also prevents small message to actually
become larger in compressed form.
<p><b>Please note that when a TCP transport is used,
compression will also turn on syslog-transport-tls framing. See the "o"
option for important information on the implications.</b></p>
<p>Compressed messages are automatically detected and
decompressed by the receiver. There is nothing that needs to be
configured on the receiver side.</p>
</td>
</tr>
<tr>
<td>
<p align="center"><b>o</b></p>
</td>
<td><b>This option is experimental. Use at your own
risk and only if you know why you need it! If in doubt, do NOT turn it
on.</b>
<p>This option is only valid for plain TCP based
transports. It selects a different framing based on IETF internet draft
syslog-transport-tls-06. This framing offers some benefits over
traditional LF-based framing. However, the standardization effort is
not yet complete. There may be changes in upcoming versions of this
standard. Rsyslog will be kept in line with the standard. There is some
chance that upcoming changes will be incompatible to the current
specification. In this case, all systems using -transport-tls framing
must be upgraded. There will be no effort made to retain compatibility
between different versions of rsyslog. The primary reason for that is
that it seems technically impossible to provide compatibility between
some of those changes. So you should take this note very serious. It is
not something we do not *like* to do (and may change our mind if enough
people beg...), it is something we most probably *can not* do for
technical reasons (aka: you can beg as much as you like, it won't
change anything...).</p>
<p>The most important implication is that compressed syslog
messages via TCP must be considered with care. Unfortunately, it is
technically impossible to transfer compressed records over traditional
syslog plain tcp transports, so you are left with two evil choices...</p>
</td>
</tr>
</tbody>
</table>
<p><br>
The hostname may be followed by a colon and the destination port.</p>
<p>The following is an example selector line with forwarding:</p>
<p>*.*&nbsp;&nbsp;&nbsp; @@(o,z9)192.168.0.1:1470</p>
<p>In this example, messages are forwarded via plain TCP with
experimental framing and maximum compression to the host 192.168.0.1 at
port 1470.</p>
<p>*.* @192.168.0.1</p>
<p>In the example above, messages are forwarded via UDP to the
machine 192.168.0.1, the destination port defaults to 514. Messages
will not be compressed.</p>
<p>Note that IPv6 addresses contain colons. So if an IPv6 address is specified
in the hostname part, rsyslogd could not detect where the IP address ends
and where the port starts. There is a syntax extension to support this:
put squary brackets around the address (e.g. "[2001::1]"). Square
brackets also work with real host names and IPv4 addresses, too.
<p>A valid sample to send messages to the IPv6 host 2001::1 at port 515
is as follows:
<p>*.* @[2001::1]:515
<p>This works with TCP, too.
<p><b>Note to sysklogd users:</b> sysklogd does <b>not</b>
support RFC 3164 format, which is the default forwarding template in
rsyslog. As such, you will experience duplicate hostnames if rsyslog is
the sender and sysklogd is the receiver. The fix is simple: you need to
use a different template. Use that one:</p>
<p class="MsoPlainText">$template
sysklogd,"&lt;%PRI%&gt;%TIMESTAMP% %syslogtag%%msg%\""<br>
*.* @192.168.0.1;sysklogd</p>
<h3>List of Users</h3>
<p>Usually critical messages are also directed to "root'' on
that machine. You can specify a list of users that shall get the
message by simply writing ":omusrmsg: followed by the login name. For example,
the send messages to root, use ":omusrmsg:root".
You may specify more than one user
by separating them with commas (",''). Do not repeat the ":omusrmsg:" prefix in
this case. For example, to send data to users root and rger, use
":omusrmsg:root,rger" (do not use ":omusrmsg:root,:omusrmsg:rger", this is invalid).
If they're logged in they get
the message.</p>
<h3>Everyone logged on</h3>
<p>Emergency messages often go to all users currently online to
notify them that something strange is happening with the system. To
specify this wall(1)-feature use an asterisk as the user message
destination(":omusrmsg:*'').</p>
<h3>Call Plugin</h3>
<p>This is a generic way to call an output plugin. The plugin
must support this functionality. Actual parameters depend on the
module, so see the module's doc on what to supply. The general syntax
is as follows:</p>
<p>:modname:params;template</p>
<p>Currently, the ommysql database output module supports this
syntax (in addtion to the "&gt;" syntax it traditionally
supported). For ommysql, the module name is "ommysql" and the params
are the traditional ones. The ;template part is not module specific, it
is generic rsyslog functionality available to all modules.</p>
<p>As an example, the ommysql module may be called as follows:</p>
<p>:ommysql:dbhost,dbname,dbuser,dbpassword;dbtemplate</p>
<p>For details, please see the "Database Table" section of this
documentation.</p>
<p>Note: as of this writing, the ":modname:" part is hardcoded
into the module. So the name to use is not necessarily the name the
module's plugin file is called.</p>
<h3>Database Table</h3>
<p>This allows logging of the message to a database table.
Currently, only MySQL databases are supported. However, other database
drivers will most probably be developed as plugins. By default, a <a href="http://www.monitorware.com/">MonitorWare</a>-compatible
schema is required for this to work. You can create that schema with
the createDB.SQL file that came with the rsyslog package. You can also<br>
use any other schema of your liking - you just need to define a proper
template and assign this template to the action.<br>
<br>
The database writer is called by specifying a greater-then sign
("&gt;") in front of the database connect information. Immediately
after that<br>
sign the database host name must be given, a comma, the database name,
another comma, the database user, a comma and then the user's password.
If a specific template is to be used, a semicolon followed by the
template name can follow the connect information. This is as follows:<br>
<br>
&gt;dbhost,dbname,dbuser,dbpassword;dbtemplate</p>
<p><b>Important: to use the database functionality, the
MySQL output module must be loaded in the config file</b> BEFORE
the first database table action is used. This is done by placing the</p>
<p><code><b>$ModLoad ommysql</b></code></p>
<p>directive some place above the first use of the database write
(we recommend doing at the the beginning of the config file).</p>
<h3>Discard</h3>
<p>If the discard action is carried out, the received message is
immediately discarded. No further processing of it occurs. Discard has
primarily been added to filter out messages before carrying on any
further processing. For obvious reasons, the results of "discard" are
depending on where in the configuration file it is being used. Please
note that once a message has been discarded there is no way to retrieve
it in later configuration file lines.</p>
<p>Discard can be highly effective if you want to filter out some
annoying messages that otherwise would fill your log files. To do that,
place the discard actions early in your log files. This often plays
well with property-based filters, giving you great freedom in
specifying what you do not want.</p>
<p>Discard is just the single tilde character with no further
parameters:</p>
<p>~</p>
<p>For example,</p>
<p>*.*&nbsp;&nbsp; ~</p>
<p>discards everything (ok, you can achive the same by not
running rsyslogd at all...).</p>
<h3>Output Channel</h3>
<p>Binds an output channel definition (see there for details) to
this action. Output channel actions must start with a $-sign, e.g. if
you would like to bind your output channel definition "mychannel" to
the action, use "$mychannel". Output channels support template
definitions like all all other actions.</p>
<h3>Shell Execute</h3>
<p>This executes a program in a subshell. The program is passed
the template-generated message as the only command line parameter.
Rsyslog waits until the program terminates and only then continues to
run.</p>
<p>^program-to-execute;template</p>
<p>The program-to-execute can be any valid executable. It
receives the template string as a single parameter (argv[1]).</p>
<p><b>WARNING:</b> The Shell Execute action was added
to serve an urgent need. While it is considered reasonable save when
used with some thinking, its implications must be considered. The
current implementation uses a system() call to execute the command.
This is not the best way to do it (and will hopefully changed in
further releases). Also, proper escaping of special characters is done
to prevent command injection. However, attackers always find smart ways
to circumvent escaping, so we can not say if the escaping applied will
really safe you from all hassles. Lastly, rsyslog will wait until the
shell command terminates. Thus, a program error in it (e.g. an infinite
loop) can actually disable rsyslog. Even without that, during the
programs run-time no messages are processed by rsyslog. As the IP
stacks buffers are quickly overflowed, this bears an increased risk of
message loss. You must be aware of these implications. Even though they
are severe, there are several cases where the "shell execute" action is
very useful. This is the reason why we have included it in its current
form. To mitigate its risks, always a) test your program thoroughly, b)
make sure its runtime is as short as possible (if it requires a longer
run-time, you might want to spawn your own sub-shell asynchronously),
c) apply proper firewalling so that only known senders can send syslog
messages to rsyslog. Point c) is especially important: if rsyslog is
accepting message from any hosts, chances are much higher that an
attacker might try to exploit the "shell execute" action.</p>
<h3>Template Name</h3>
<p>Every ACTION can be followed by a template name. If so, that
template is used for message formatting. If no name is given, a
hard-coded default template is used for the action. There can only be
one template name for each given action. The default template is
specific to each action. For a description of what a template is and
what you can do with it, see "TEMPLATES" at the top of this document.</p>

<p>[<a href="manual.html">manual index</a>]
[<a href="rsyslog_conf.html">rsyslog.conf</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; 2008-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 2 or higher.</font></p>
</body>
</html>