mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-19 20:50:42 +01:00
337 lines
17 KiB
HTML
337 lines
17 KiB
HTML
<!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>
|
|
<p>The action field of a rule describes what to do with the
|
|
message. In general, message content is written to a kind of "logfile".
|
|
But also other actions might be done, like writing to a database table
|
|
or forwarding to another host.<br>
|
|
<br>
|
|
Templates can be used with all 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> (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
|
|
('&') character and have no filters. An example would be</p>
|
|
<p><code><b>*.=crit rger<br>
|
|
& root<br>
|
|
& /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 rger<br>
|
|
*.=crit root<br>
|
|
*.=crit /var/log/critmsgs</b></code></p>
|
|
<p> </p>
|
|
<h3>Regular File</h3>
|
|
<p>Typically messages are logged to real files. The file has to
|
|
be specified with full pathname, beginning with a slash "/''.<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<br>
|
|
administration needs.<br>
|
|
<br>
|
|
<b>Please note that this version of rsyslogd by default does NOT
|
|
forward messages it has received from the network to another host.
|
|
Specify the "-h" option to enable this.</b></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 WinSyslog). 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<number></b></p>
|
|
</td>
|
|
<td>Enable zlib-compression for the message. The
|
|
<number> 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>*.* @@(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,"<%PRI%>%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 the login. You may specify more than one user
|
|
by separating them with commas (",''). If they're logged in they get
|
|
the message. Don't think a mail would be sent, that might be too late.</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 ("*'').</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 ">" 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
|
|
(">") 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>
|
|
>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>*.* ~</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 © 2008 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>
|
|
|