mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-18 19:10:42 +01:00
789 lines
45 KiB
HTML
789 lines
45 KiB
HTML
<html>
|
||
<head>
|
||
<title>rsyslog.conf file</title>
|
||
</head>
|
||
<body>
|
||
<h1>rsyslog.conf configuration file</h1>
|
||
<p><b>This document is currently being enhanced. Please pardon its current
|
||
appearance.</b></p>
|
||
<p><b>Rsyslogd is configured via the rsyslog.conf file</b>, typically found in
|
||
/etc. By default, rsyslogd reads the file /etc/rsyslog.conf.</p>
|
||
<p>While rsyslogd contains enhancements over standard syslogd, efforts have been
|
||
made to keep the configuration file as compatible as possible. While, for
|
||
obvious reasons, <a href="features.html">enhanced features</a> require a
|
||
different config file syntax, rsyslogd should be able to work with a standard
|
||
syslog.conf file. This is especially useful while you are migrating from syslogd
|
||
to rsyslogd.</p>
|
||
<h2>Basic Structure</h2>
|
||
<p>Rsyslog supports standard sysklogd's configuration file format and extends
|
||
it. So in general, you can take a "normal" syslog.conf and use it together with
|
||
rsyslogd. It will understand everything. However, to use most of rsyslogd's
|
||
unique features, you need to add extended configuration directives.<p>Rsyslogd
|
||
supports the classical, selector-based rule lines. They are still at the heart
|
||
of it and all actions are initiated via rule lines. A rule lines is any line not
|
||
starting with a $ or the comment sign (#). Lines starting with $ carry
|
||
rsyslog-specific directives.<p>Every rule line consists of two fields, a selector field and an action field.
|
||
These two fields are separated by one or more spaces or tabs. The selector field
|
||
specifies a pattern of facilities and priorities belonging to the specified
|
||
action.<br>
|
||
<br>
|
||
Lines starting with a hash mark ("#'') and empty lines are ignored.
|
||
<h2>Allowed Sender Lists</h2>
|
||
<p>Allowed sender lists can be used to specify which remote systems are allowed
|
||
to send syslog messages to rsyslogd. With them, further hurdles can be placed
|
||
between an attacker and rsyslogd. If a message from a system not in the allowed
|
||
sender list is received, that message is discarded. A diagnostic message is
|
||
logged, so that the fact is recorded (this message can be turned off with the
|
||
"-w" rsyslogd command line option).</p>
|
||
<p>Allowed sender lists can be defined for UDP and TCP senders seperately. There
|
||
can be as many allowed senders as needed. The syntax to specify them is:</p>
|
||
<p><code><b>$AllowedSender <protocol>, ip[/bits], ip[/bits]</b></code></p>
|
||
<p>"$AllowedSender" is the directive - it must be written exactly as shown and
|
||
the $ must start at the first column of the line. "<protocol>" is either "UDP"
|
||
or "TCP". It must immediately be followed by the comma, else you will receive an
|
||
error message. "ip[/bits]" is a machine or network ip address as in
|
||
"192.0.2.0/24" or "127.0.0.1". If the "/bits" part is omitted, a single host is
|
||
assumed (32 bits or mask 255.255.255.255). "/0" is not allowed, because that
|
||
would match any sending system. If you intend to do that, just remove all $AllowedSender
|
||
directives. If more than 32 bits are requested, they are adjusted to 32.
|
||
Multiple allowed senders can be specified in a comma-delimited list. Also,
|
||
multiple $AllowedSender lines can be given. They are all combined into one UDP
|
||
and one TCP list. Performance-wise, it is good to specify those allowed senders
|
||
with high traffic volume before those with lower volume. As soon as a match is
|
||
found, no further evaluation is necessary and so you can save CPU cycles.</p>
|
||
<p>Rsyslogd handles allowed sender detection very early in the code, nearly as
|
||
the first action after receiving a message. This keeps the access to potential
|
||
vulnerable code in rsyslog at a minimum. However, it is still a good idea to
|
||
impose allowed sender limitations via firewalling.</p>
|
||
<p><b>WARNING:</b> by UDP design, rsyslogd can not identify a spoofed sender
|
||
address in UDP syslog packets. As such, a malicous person could spoof the adress
|
||
of an allowed sender, send such packets to rsyslogd and rsyslogd would accept
|
||
them as being from the faked sender. To prevent this, use syslog via TCP
|
||
exclusively. If you need to use UDP-based syslog, make sure that you do proper
|
||
egress and ingress filtering at the firewall and router level.</p>
|
||
<p>An example for an allowed sender list is as follows:</p>
|
||
<p><code><b>$AllowedSender UDP, 127.0.0.1, 192.0.2.0/24</b></code></p>
|
||
<h2>Templates</h2>
|
||
<p>Templates are a key feature of rsyslog. They allow to specify any format a user
|
||
might want. They are also used for dynamic file name generation. Every output in rsyslog uses templates - this holds true for files,
|
||
user messages and so on. The database writer expects its template to be a proper
|
||
SQL statement - so this is highly customizable too. You might ask how does all
|
||
of this work when no templates at all are specified. Good question ;) The answer
|
||
is simple, though. Templates compatible with the stock syslogd formats are
|
||
hardcoded into rsyslogd. So if no template is specified, we use one of these
|
||
hardcoded templates. Search for "template_" in syslogd.c and you will find the
|
||
hardcoded ones.</p>
|
||
<p>A template consists of a template directive, a name, the actual template text
|
||
and optional options. A sample is:</p>
|
||
<blockquote><code>$template MyTemplateName,"\7Text %property% some more text\n",<options></code></blockquote>
|
||
<p>The "$template" is the template directive. It tells rsyslog that this line
|
||
contains a template. "MyTemplateName" is the template name. All
|
||
other config lines refer to this name. The text within quotes is the actual
|
||
template text. The backslash is an escape character, much as it is in C. It does
|
||
all these "cool" things. For example, \7 rings the bell (this is an ASCII
|
||
value), \n is a new line. C programmers and perl coders have the advantage of
|
||
knowing this, but the set in rsyslog is a bit restricted currently.
|
||
<p>
|
||
All text in the template is used literally, except for things within percent
|
||
signs. These are properties and allow you access to the contents of the syslog
|
||
message. Properties are accessed via the property replacer (nice name, huh) and
|
||
it can do cool things, too. For example, it can pick a substring or do
|
||
date-specific formatting. More on this is below, on some lines of the property
|
||
replacer.<br>
|
||
<br>
|
||
The <options> part is optional. It carries options influencing the template as
|
||
whole. See details below. Be sure NOT to mistake template options with property
|
||
options - the later ones are processed by the property replacer and apply to a
|
||
SINGLE property, only (and not the whole template).<br>
|
||
<br>
|
||
Template options are case-insensitive. Currently defined are: </p>
|
||
<p><b>sql</b> - format the string suitable for a SQL statement in MySQL format. This will
|
||
replace single quotes ("'") and the backslash character by their
|
||
backslash-escaped counterpart ("\'" and "\\") inside each field. Please note
|
||
that in MySQL configuration, the <code class="literal">NO_BACKSLASH_ESCAPES</code>
|
||
mode must be turned off for this format to work (this is the default).</p>
|
||
<p><b>stdsql</b> - format the string suitable for a SQL statement that is to be
|
||
sent to a standards-compliant sql server. This will
|
||
replace single quotes ("'") by two single quotes ("''") inside each field.
|
||
You must use stdsql together with MySQL if in MySQL configuration the
|
||
<code class="literal">NO_BACKSLASH_ESCAPES</code> is turned on.</p>
|
||
<p>Either the <b>sql</b> or <b>stdsql</b>
|
||
option <b>must</b> be specified when a template is used for writing to a database,
|
||
otherwise injection might occur. Please note that due to the unfortunate fact
|
||
that several vendors have violated the sql standard and introduced their own
|
||
escape methods, it is impossible to have a single option doing all the work.
|
||
So you yourself must make sure you are using the right format. <b>If you choose
|
||
the wrong one, you are still vulnerable to sql injection.</b><br>
|
||
<br>
|
||
Please note that the database writer *checks* that the sql option is present in
|
||
the template. If it is not present, the write database action is disabled. This
|
||
is to guard you against accidential forgetting it and then becoming vulnerable
|
||
to SQL injection. The sql option can also be useful with files - especially if
|
||
you want to import them into a database on another machine for performance
|
||
reasons. However, do NOT use it if you do not have a real need for it - among
|
||
others, it takes some toll on the processing time. Not much, but on a really
|
||
busy system you might notice it ;)</p>
|
||
<p>The default template for the write to database action has the sql option set.
|
||
As we currently support only MySQL and the sql option matches the default MySQL
|
||
configuration, this is a good choice. However, if you have turned on
|
||
<code class="literal">NO_BACKSLASH_ESCAPES</code> in your MySQL config, you need
|
||
to supply a template with the stdsql option. Otherwise you will become
|
||
vulnerable to SQL injection. <br>
|
||
<br>
|
||
To escape:<br>
|
||
% = \%<br>
|
||
\ = \\ --> '\' is used to escape (as in C)<br>
|
||
$template TraditionalFormat,%timegenerated% %HOSTNAME% %syslogtag%%msg%\n"<br>
|
||
<br>
|
||
Properties can be accessed by the <a href="property_replacer.html">property replacer</a>
|
||
(see there for details).</p>
|
||
<p><b>Please note that as of 1.15.0, templates can also by used to generate
|
||
selector lines with dynamic file names.</b> For example, if you would like to
|
||
split syslog messages from different hosts to different files (one per host),
|
||
you can define the following template:</p>
|
||
<blockquote><code>$template DynFile,"/var/log/system-%HOSTNAME%.log"</code></blockquote>
|
||
<p>This template can then be used when defining an output selector line. It will
|
||
result in something like "/var/log/system-localhost.log"</p>
|
||
<h2>Output Channels</h2>
|
||
<p>Output Channels are a new concept first introduced in rsyslog 0.9.0. As of this
|
||
writing, it is still unclear if they will stay in rsyslog or go away. So if you
|
||
use them, be prepared to change you configuration file syntax when you upgrade
|
||
to a later release.<br>
|
||
<br>
|
||
The idea behind output channel definitions is that it shall provide an umbrella
|
||
for any type of output that the user might want. In essence,<br>
|
||
this is the "file" part of selector lines (and this is why we are not sure
|
||
output channel syntax will stay after the next review). There is a<br>
|
||
difference, though: selector channels both have filter conditions (currently
|
||
facility and severity) as well as the output destination. Output channels define
|
||
the output defintion, only. As of this build, they can only be used to write to
|
||
files - not pipes, ttys or whatever else. If we stick with output channels, this
|
||
will change over time.</p>
|
||
<p>In concept, an output channel includes everything needed to know about an
|
||
output actions. In practice, the current implementation only carries<br>
|
||
a filename, a maximum file size and a command to be issued when this file size
|
||
is reached. More things might be present in future version, which might also
|
||
change the syntax of the directive.</p>
|
||
<p>Output channels are defined via an $outchannel directive. It's syntax is as
|
||
follows:<br>
|
||
<br>
|
||
$outchannel name,file-name,max-size,action-on-max-size<br>
|
||
<br>
|
||
name is the name of the output channel (not the file), file-name is the file
|
||
name to be written to, max-size the maximum allowed size and action-on-max-size
|
||
a command to be issued when the max size is reached.<br>
|
||
<br>
|
||
Please note that max-size is queried BEFORE writing the log message to the file.
|
||
So be sure to set this limit reasonably low so that any message might fit. For
|
||
the current release, setting it 1k lower than you expected is helpful. The
|
||
max-size must always be specified in bytes - there are no special symbols (like
|
||
1k, 1m,...) at this point of development.<br>
|
||
<br>
|
||
Keep in mind that $outchannel just defines a channel with "name". It does not
|
||
activate it. To do so, you must use a selector line (see below). That selector
|
||
line includes the channel name plus an $ sign in front of it. A sample might be:<br>
|
||
<br>
|
||
*.* $mychannel<br>
|
||
<br>
|
||
In its current form, output channels primarily provide the ability to size-limit
|
||
an output file. To do so, specify a maximum size. When this size is reachead,
|
||
rsyslogd will execute the action-on-max-size command and then reopen the file
|
||
and retry. The command should be something like a log rotation script or a
|
||
similar thing.</p>
|
||
<blockquote>
|
||
<p><b>WARNING</b>
|
||
<p>The current command logic is a quick hack. It simply issues the command via a
|
||
system() call, which is very dirty. Don't make rsyslogd a suid
|
||
binary and use action-on-max-size commands - this will mess up things. Fixing
|
||
this is on top of the todo list and the fix will hopefully
|
||
appear soon.</p>
|
||
</blockquote>
|
||
<p>If there is no action-on-max-size command or the command did not resolve the
|
||
situation, the file is closed and never reopened by rsyslogd (except, of course,
|
||
by huping it). This logic was integrated when we first experienced severe issues
|
||
with files larger 2gb, which could lead to rsyslogd dumping core. In such cases,
|
||
it is more appropriate to stop writing to a single file. Meanwhile, rsyslogd has
|
||
been fixed to support files larger 2gb, but obviously only on file systems and
|
||
operating system versions that do so. So it can still make sense to enforce a
|
||
2gb file size limit.</p>
|
||
<h2>Filter Conditions</h2>
|
||
<p>Rsyslog offers two different types "filter conditions":</p>
|
||
<ul>
|
||
<li>"traditional" severity and facility based selectors</li>
|
||
<li>property-based filters</li>
|
||
</ul>
|
||
<h3>Blocks</h3>
|
||
<p>Rsyslogd supports BSD-style blocks inside rsyslog.conf. Each block of lines
|
||
is separated from the previous block by a program or hostname specification. A
|
||
block will only log messages corresponding to the most recent program and
|
||
hostname specifications given. Thus, a block which selects <20>ppp<70> as the program,
|
||
directly followed by a block that selects messages from the hostname <20>dialhost<73>,
|
||
then the second block will only log messages from the ppp program on dialhost.
|
||
</p>
|
||
<p>A program specification is a line beginning with <20>!prog<6F> and the following
|
||
blocks will be associated with calls to syslog from that specific program. A
|
||
program specification for <20>foo<6F> will also match any message logged by the kernel
|
||
with the prefix <20>foo: <20>. A hostname specification of the form <20>+hostname<6D> and
|
||
the following blocks will be applied to messages received from the specified
|
||
hostname. Alternatively, a hostname specification <20>-hostname<6D> causes the
|
||
following blocks to be applied to messages from any host but the one specified.
|
||
If the hostname is given as <20>@<40>, the local hostname will be used. (NOT YET
|
||
IMPLEMENTED) A program or hostname specification may be reset by giving the
|
||
program or hostname as <20>*<2A>.</p>
|
||
<p>Please note that the "#!prog", "#+hostname" and "#-hostname" syntax available
|
||
in BSD syslogd is not supported by rsyslogd. By default, no hostname or program
|
||
is set.</p>
|
||
<h3>Selectors</h3>
|
||
<p><b>Selectors are the traditional way of filtering syslog messages.</b> They
|
||
have been kept in rsyslog with their orginal syntax, because it is well-known,
|
||
highly effective and also needed for compatibility with stock syslogd
|
||
configuration files. If you just need to filter based on priority and facility,
|
||
you should do this with selector lines. They are <b>not</b> second-class
|
||
citicens in rsyslog and offer the best performance for this job.</p>
|
||
<p>The selector field itself again consists of two parts, a facility and a
|
||
priority, separated by a period (``.''). Both parts are case insenstive and can
|
||
also be specified as decimal numbers, but don't do that, you have been warned.
|
||
Both facilities and priorities are described in rsyslog(3). The names mentioned
|
||
below correspond to the similar LOG_-values in /usr/include/rsyslog.h.<br><br>The facility is one of the following keywords: auth, authpriv, cron, daemon,
|
||
kern, lpr, mail, mark, news, security (same as auth), syslog, user, uucp and
|
||
local0 through local7. The keyword security should not be used anymore and mark
|
||
is only for internal use and therefore should not be used in applications.
|
||
Anyway, you may want to specify and redirect these messages here. The facility
|
||
specifies the subsystem that produced the message, i.e. all mail programs log
|
||
with the mail facility (LOG_MAIL) if they log using syslog.<br><br>Please note that the upcoming next syslog-RFC specifies many more facilities.
|
||
Support for them will be added in a future version of rsyslog, which might
|
||
require changes to existing configuration files.<br><br>The priority is one of the following keywords, in ascending order: debug, info,
|
||
notice, warning, warn (same as warning), err, error (same as err), crit, alert,
|
||
emerg, panic (same as emerg). The keywords error, warn and panic are deprecated
|
||
and should not be used anymore. The priority defines the severity of the message<br>
|
||
<br>The behavior of the original BSD syslogd is that all messages of the specified
|
||
priority and higher are logged according to the given action. Rsyslogd behaves the same, but has some extensions.<br><br>In addition to the above mentioned names the rsyslogd(8) understands the
|
||
following extensions: An asterisk (``*'') stands for all facilities or all
|
||
priorities, depending on where it is used (before or after the period). The
|
||
keyword none stands for no priority of the given facility.<br><br>You can specify multiple facilities with the same priority pattern in one
|
||
statement using the comma (``,'') operator. You may specify as much facilities
|
||
as you want. Remember that only the facility part from such a statement is
|
||
taken, a priority part would be skipped.</p>
|
||
<p>Multiple selectors may be specified for a single action using the semicolon
|
||
(``;'') separator. Remember that each selector in the selector field is capable
|
||
to overwrite the preceding ones. Using this behavior you can exclude some
|
||
priorities from the pattern.</p>
|
||
<p>Rsyslogd has a syntax extension to the original BSD source, that makes its
|
||
use more intuitively. You may precede every priority with an equation sign
|
||
(``='') to specify only this single priority and not any of the above. You may
|
||
also (both is valid, too) precede the priority with an exclamation mark (``!'')
|
||
to ignore all that priorities, either exact this one or this and any higher
|
||
priority. If you use both extensions than the exclamation mark must occur before
|
||
the equation sign, just use it intuitively.</p>
|
||
<h3>Property-Based Filters</h3>
|
||
<p>Property-based filters are unique to rsyslogd. They allow to filter on any
|
||
property, like HOSTNAME, syslogtag and msg. A list of all currently-supported
|
||
properties can be found in the <a href="property_replacer.html">property
|
||
replacer documentation</a> (but keep in mind that only the properties, not the
|
||
replacer is supported). With this filter, each properties can be checked against
|
||
a specified value, using a specified compare operation. Currently, there is only
|
||
a single compare operation (contains) available, but additional operations will be added in the
|
||
future.</p>
|
||
<p>A property-based filter must start with a colon in column 0. This tells
|
||
rsyslogd that it is the new filter type. The colon must be followed by the
|
||
property name, a comma, the name of the compare operation to carry out, another
|
||
comma and then the value to compare against. This value must be quoted. There
|
||
can be spaces and tabs between the commas. Property names and compare operations
|
||
are case-sensitive, so "msg" works, while "MSG" is an invalid property name. In
|
||
brief, the syntax is as follows:</p>
|
||
<p><code><b>:property, [!]compare-operation, "value"</b></code></p>
|
||
<p>The following <b>compare-operations</b> are currently supported:</p>
|
||
<table border="1" width="100%" id="table1">
|
||
<tr>
|
||
<td>contains</td>
|
||
<td>Checks if the string provided in value is contained in the property.
|
||
There must be an exact match, wildcards are not supported.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>isequal</td>
|
||
<td>Compares the "value" string provided and the property contents.
|
||
These two values must be exactly equal to match. The difference to
|
||
contains is that contains searchs for the value anywhere inside the
|
||
property value, whereas all characters must be identical for isequal. As
|
||
such, isequal is most useful for fields like syslogtag or FROMHOST,
|
||
where you probably know the exact contents.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>startswith</td>
|
||
<td>Checks if the value is found exactly at the beginning of the
|
||
property value. For example, if you search for "val" with<p><code><b>:msg,
|
||
startswith, "val"</b></code></p>
|
||
<p>it will be a match if msg contains "values are in this message" but
|
||
it won't match if the msg contains "There are values in this message"
|
||
(in the later case, contains would match). Please note that "startswith"
|
||
is by far faster than regular expressions. So even once they are
|
||
implemented, it can make very much sense (performance-wise) to use "startswith".</td>
|
||
</tr>
|
||
<tr>
|
||
<td>regex</td>
|
||
<td><b>NOT YET IMPLEMENTED</b> - value holds an regular expression</td>
|
||
</tr>
|
||
</table>
|
||
<p>You can use the bang-character (!) immediately in front of a
|
||
compare-operation, the outcome of this operation is negated. For example, if msg
|
||
contains "This is an informative message", the following sample would not match:</p>
|
||
<p><code><b>:msg, contains, "error"</b></code></p>
|
||
<p>but this one matches:</p>
|
||
<p><code><b>:msg, !contains, "error"</b></code></p>
|
||
<p>Using negation can be useful if you would like to do some generic processing
|
||
but exclude some specific events. You can use the discard action in conjunction
|
||
with that. A sample would be:</p>
|
||
<p><code><b>*.* /var/log/allmsgs-including-informational.log<br>
|
||
:msg, contains, "informational" <font color="#FF0000" size="4">~</font>
|
||
<br>*.* /var/log/allmsgs-but-informational.log</b></code></p>
|
||
<p>Do not overlook the red tilde in line 2! In this sample, all messages are
|
||
written to the file allmsgs-including-informational.log. Then, all messages
|
||
containing the string "informational" are discarded. That means the config file
|
||
lines below the "discard line" (number 2 in our sample) will not be applied to
|
||
this message. Then, all remaining lines will also be written to the file
|
||
allmsgs-but-informational.log.</p>
|
||
<p><b>Value</b> is a quoted string. It supports some escape sequences:</p>
|
||
<p>\" - the quote character (e.g. "String with \"Quotes\"")<br>
|
||
\\ - the backslash character (e.g. "C:\\tmp")</p>
|
||
<p>Escape sequences always start with a backslash. Additional escape sequences
|
||
might be added in the future. Backslash characters <b>must</b> be escaped. Any
|
||
other sequence then those outlined above is invalid and may lead to
|
||
unpredictable results.</p>
|
||
<p>Probably, "msg" is the most prominent use case of property based filters. It
|
||
is the actual message text. If you would like to filter based on some message
|
||
content (e.g. the presence of a specific code), this can be done easily by:</p>
|
||
<p><code><b>:msg, contains, "ID-4711"</b></code></p>
|
||
<p>This filter will match when the message contains the string "ID-4711". Please
|
||
note that the comparison is case-sensitive, so it would not match if "id-4711"
|
||
would be contained in the message.</p>
|
||
<p>Getting property-based filters right can sometimes be challenging. In order
|
||
to help you do it with as minimal effort as possible, rsyslogd spits out debug
|
||
information for all property-based filters during their evaluation. To enable
|
||
this, run rsyslogd in foreground and specify the "-d" option.</p>
|
||
<p>Boolean operations inside property based filters (like 'message contains
|
||
"ID17" or message contains "ID18"') are currently not supported
|
||
(except for "not" as outlined above). Please note
|
||
that while it is possible to query facility and severity via property-based filters,
|
||
it is far more advisable to use classic selectors (see above) for those
|
||
cases.</p>
|
||
<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 selectore line that is above its definition. If you do this, the selector
|
||
line will be ignored.</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>
|
||
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>
|
||
<p align="center">
|
||
<code>*.* ?DynFile</code>
|
||
</p>
|
||
<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.</p>
|
||
<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. <b>However, directories are never created</b>. So if you use a dynamic
|
||
directory name, you must make sure that all possible directories are created,
|
||
otherwise the writes will fail. This restriction will most probably be removed
|
||
in later versions of rsyslogd.</p>
|
||
<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 border="1" width="100%" id="table2">
|
||
<tr>
|
||
<td>
|
||
<p align="center"><b>z<number></b></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 seldomly seen with typicaly 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. Messags 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.</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p align="center"><b>o</b></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 pepole 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...</td>
|
||
</tr>
|
||
</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>
|
||
<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>Database Table</h3>
|
||
<p>This allows logging of the message to a database table. Currently, only MySQL
|
||
databases are supported. By default, a MonitorWare-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 semicolong followed by the template name can follow
|
||
the connect information. This is as follows:<br>
|
||
<br>
|
||
>dbhost,dbname,dbuser,dbpassword;dbtemplate</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 retrive 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 programm 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>^programm-to-execute;template</p>
|
||
<p>The program-to-execute can be any valid executable.</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. Lastely, 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 thouroughly, 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>
|
||
<h2>TEMPLATE NAME</h2>
|
||
<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 hardcoded 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>
|
||
<h2>EXAMPLES</h2>
|
||
<p>Below are example for templates and selector lines. I hope they are
|
||
self-explanatory. If not, please see www.monitorware.com/rsyslog/ for advise.</p>
|
||
<h3>TEMPLATES</h3>
|
||
<p>Please note that the samples are split across multiple lines. A template MUST
|
||
NOT actually be split across multiple lines.<br>
|
||
<br>
|
||
A template that resambles traditional syslogd file output:<br>
|
||
$template TraditionalFormat,"%timegenerated% %HOSTNAME%<br>
|
||
%syslogtag%%msg:::drop-last-lf%\n"<br>
|
||
<br>
|
||
A template that tells you a little more about the message:<br>
|
||
$template precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,<br>
|
||
%syslogtag%,%msg%\n"<br>
|
||
<br>
|
||
A template for RFC 3164 format:<br>
|
||
$template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag%%msg%"<br>
|
||
<br>
|
||
A template for the format traditonally used for user messages:<br>
|
||
$template usermsg," XXXX%syslogtag%%msg%\n\r"<br>
|
||
<br>
|
||
And a template with the traditonal wall-message format:<br>
|
||
$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME% at %timegenerated%<br>
|
||
<br>
|
||
A template that can be used for the database write (please note the SQL<br>
|
||
template option)<br>
|
||
$template MySQLInsert,"insert iut, message, receivedat values<br>
|
||
('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')<br>
|
||
into systemevents\r\n", SQL<br>
|
||
<br>
|
||
The following template emulates <a href="http://www.winsyslog.com/en/">WinSyslog</a>
|
||
format (it's an <a href="http://www.adiscon.com/en/">Adiscon</a> format, you do
|
||
not feel bad if you don't know it ;)). It's interesting to see how it takes
|
||
different parts out of the date stamps. What happens is that the date stamp is
|
||
split into the actual date and time and the these two are combined with just a
|
||
comma in between them.<br>
|
||
<br>
|
||
$template WinSyslogFmt,"%HOSTNAME%,%timegenerated:1:10:date-rfc3339%,<br>
|
||
%timegenerated:12:19:date-rfc3339%,%timegenerated:1:10:date-rfc3339%,<br>
|
||
%timegenerated:12:19:date-rfc3339%,%syslogfacility%,%syslogpriority%,<br>
|
||
%syslogtag%%msg%\n"</p>
|
||
<h3>SELECTOR LINES</h3>
|
||
<p># Store critical stuff in critical<br>
|
||
#<br>
|
||
*.=crit;kern.none /var/adm/critical<br>
|
||
<br>
|
||
This will store all messages with the priority crit in the file /var/adm/critical,
|
||
except for any kernel message.<br>
|
||
<br>
|
||
<br>
|
||
# Kernel messages are first, stored in the kernel<br>
|
||
# file, critical messages and higher ones also go<br>
|
||
# to another host and to the console. Messages to<br>
|
||
# the host finlandia are forwarded in RFC 3164<br>
|
||
# format (using the template defined above).<br>
|
||
#<br>
|
||
kern.* /var/adm/kernel<br>
|
||
kern.crit @finlandia;RFC3164fmt<br>
|
||
kern.crit /dev/console<br>
|
||
kern.info;kern.!err /var/adm/kernel-info<br>
|
||
<br>
|
||
The first rule direct any message that has the kernel facility to the file /var/adm/kernel.<br>
|
||
<br>
|
||
The second statement directs all kernel messages of the priority crit and higher
|
||
to the remote host finlandia. This is useful, because if the host crashes and
|
||
the disks get irreparable errors you might not be able to read the stored
|
||
messages. If they're on a remote host, too, you still can try to find out the
|
||
reason for the crash.<br>
|
||
<br>
|
||
The third rule directs these messages to the actual console, so the person who
|
||
works on the machine will get them, too.<br>
|
||
<br>
|
||
The fourth line tells rsyslogd to save all kernel messages that come with
|
||
priorities from info up to warning in the file /var/adm/kernel-info. Everything
|
||
from err and higher is excluded.<br>
|
||
<br>
|
||
<br>
|
||
# The tcp wrapper loggs with mail.info, we display<br>
|
||
# all the connections on tty12<br>
|
||
#<br>
|
||
mail.=info /dev/tty12<br>
|
||
<br>
|
||
This directs all messages that uses mail.info (in source LOG_MAIL | LOG_INFO) to
|
||
/dev/tty12, the 12th console. For example the tcpwrapper tcpd(8) uses this as
|
||
it's default.<br>
|
||
<br>
|
||
<br>
|
||
# Store all mail concerning stuff in a file<br>
|
||
#<br>
|
||
mail.*;mail.!=info /var/adm/mail<br>
|
||
<br>
|
||
This pattern matches all messages that come with the mail facility, except for
|
||
the info priority. These will be stored in the file /var/adm/mail.<br>
|
||
<br>
|
||
<br>
|
||
# Log all mail.info and news.info messages to info<br>
|
||
#<br>
|
||
mail,news.=info /var/adm/info<br>
|
||
<br>
|
||
This will extract all messages that come either with mail.info or with news.info
|
||
and store them in the file /var/adm/info.<br>
|
||
<br>
|
||
<br>
|
||
# Log info and notice messages to messages file<br>
|
||
#<br>
|
||
*.=info;*.=notice;\<br>
|
||
mail.none /var/log/messages<br>
|
||
<br>
|
||
This lets rsyslogd log all messages that come with either the info or the notice
|
||
facility into the file /var/log/messages, except for all<br>
|
||
messages that use the mail facility.<br>
|
||
<br>
|
||
<br>
|
||
# Log info messages to messages file<br>
|
||
#<br>
|
||
*.=info;\<br>
|
||
mail,news.none /var/log/messages<br>
|
||
<br>
|
||
This statement causes rsyslogd to log all messages that come with the info
|
||
priority to the file /var/log/messages. But any message coming either with the
|
||
mail or the news facility will not be stored.<br>
|
||
<br>
|
||
<br>
|
||
# Emergency messages will be displayed using wall<br>
|
||
#<br>
|
||
*.=emerg *<br>
|
||
<br>
|
||
This rule tells rsyslogd to write all emergency messages to all currently logged
|
||
in users. This is the wall action.<br>
|
||
<br>
|
||
<br>
|
||
# Messages of the priority alert will be directed<br>
|
||
# to the operator<br>
|
||
#<br>
|
||
*.alert root,rgerhards<br>
|
||
<br>
|
||
This rule directs all messages with a priority of alert or higher to the
|
||
terminals of the operator, i.e. of the users ``root'' and ``rgerhards'' if
|
||
they're logged in.<br>
|
||
<br>
|
||
<br>
|
||
*.* @finlandia<br>
|
||
<br>
|
||
This rule would redirect all messages to a remote host called finlandia. This is
|
||
useful especially in a cluster of machines where all syslog messages will be
|
||
stored on only one machine.<br>
|
||
<br>
|
||
In the format shown above, UDP is used for transmitting the message. The
|
||
destination port is set to the default auf 514. Rsyslog is also capable of using
|
||
much more secure and reliable TCP sessions for message forwarding. Also, the
|
||
destination port can be specified. To select TCP, simply add one additional @ in
|
||
front of the host name (that is, @host is UPD, @@host is TCP). For example:<br>
|
||
<br>
|
||
<br>
|
||
*.* @@finlandia<br>
|
||
<br>
|
||
To specify the destination port on the remote machine, use a colon followed by
|
||
the port number after the machine name. The following forwards to port 1514 on
|
||
finlandia:<br>
|
||
<br>
|
||
<br>
|
||
*.* @@finlandia:1514<br>
|
||
<br>
|
||
This syntax works both with TCP and UDP based syslog. However, you will probably
|
||
primarily need it for TCP, as there is no well-accepted port for this transport
|
||
(it is non-standard). For UDP, you can usually stick with the default auf 514,
|
||
but might want to modify it for security rea-<br>
|
||
sons. If you would like to do that, it's quite easy:<br>
|
||
<br>
|
||
<br>
|
||
*.* @finlandia:1514<br>
|
||
<br>
|
||
<br>
|
||
<br>
|
||
*.* >dbhost,dbname,dbuser,dbpassword;dbtemplate<br>
|
||
<br>
|
||
This rule writes all message to the database "dbname" hosted on "dbhost". The
|
||
login is done with user "dbuser" and password "dbpassword". The actual table
|
||
that is updated is specified within the template (which contains the insert
|
||
statement). The template is called "dbtemplate" in this case.</p>
|
||
<p>:msg,contains,"error" @errorServer</p>
|
||
<p>This rule forwards all messages that contain the word "error" in the msg part
|
||
to the server "errorServer". Forwarding is via UDP. Please note the colon in
|
||
fron</p>
|
||
<h2>CONFIGURATION FILE SYNTAX DIFFERENCES</h2>
|
||
<p>Rsyslogd uses a slightly different syntax for its configuration file than the
|
||
original BSD sources. Originally all messages of a specific priority and above
|
||
were forwarded to the log file. The modifiers ``='', ``!'' and ``-'' were added
|
||
to make rsyslogd more flexible and to use it in a more intuitive manner.<br>
|
||
<br>
|
||
The original BSD syslogd doesn't understand spaces as separators between the
|
||
selector and the action field.<br>
|
||
<br>
|
||
When compared to syslogd from sysklogd package, rsyslogd offers additional
|
||
<a href="features.html">features</a> (like template and database support). For obvious reasons, the syntax for
|
||
defining such features is available
|
||
in rsyslogd, only.<br>
|
||
</p>
|
||
</body>
|
||
</html> |