mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-20 14:20:42 +01:00
1079 lines
54 KiB
HTML
1079 lines
54 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<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. This may be changed by a command line option.</p>
|
|
<p><a href="http://wiki.rsyslog.com/index.php/Configuration_Samples">
|
|
Configuration file examples can be found in the rsyslog wiki</a>.</p>
|
|
<p>There is also one sample file provided together with the
|
|
documentation set. If you do not like to read, be sure to have at least
|
|
a quick look at
|
|
<a href="rsyslog-example.conf">rsyslog-example.conf</a>.
|
|
</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>Modules</h2>
|
|
<p>Rsyslog has a modular design. Consequently, there is a growing
|
|
number of modules. Here is the entry point to their documentation and
|
|
what they do (list is currently not complete)</p>
|
|
<ul>
|
|
<li><a href="omsnmp.html">omsnmp</a> - SNMP
|
|
trap output module</li>
|
|
<li>omgss - output module for GSS-enabled syslog</li>
|
|
<li>ommysql - output module for MySQL</li>
|
|
<li>ompgsql - output module for PostgreSQL</li>
|
|
<li><a href="omlibdbi.html">omlibdbi</a> -
|
|
generic database output module (Firebird/Interbase, MS SQL, Sybase,
|
|
SQLLite, Ingres, Oracle, mSQL)</li>
|
|
<li><a href="imfile.html">imfile</a>
|
|
- input module for text files</li>
|
|
<li>imudp - udp syslog message input</li>
|
|
<li><a href="imtcp.html">imtcp</a> - input plugin for plain tcp syslog</li><li><a href="imgssapi.html">imgssapi</a> - input plugin for plain tcp and GSS-enable syslog</li>
|
|
<li>immark - support for mark messages</li>
|
|
<li>imklog - kernel logging</li>
|
|
</ul>
|
|
<p>Please note that each module provides configuration
|
|
directives, which are NOT necessarily being listed below. Also
|
|
remember, that a modules configuration directive (and functionality) is
|
|
only available if it has been loaded (using $ModLoad).</p>
|
|
<h2>Lines</h2>
|
|
Lines can be continued by specifying a backslash ("\") as the last
|
|
character of the line.<br>
|
|
<h2>Global Directives</h2>
|
|
<p>All global directives need to be specified on a line by their
|
|
own and must start with a dollar-sign. Here is a list in alphabetical
|
|
order. Follow links for a description.</p>
|
|
<p>Not all directives have an in-depth description right now.
|
|
Default values for them are in bold. A more in-depth description will
|
|
appear as implementation progresses. Directives may change during that
|
|
process, we will NOT try hard to maintain backwards compatibility
|
|
(after all, v3 is still very early in development and quite
|
|
unstable...). So you have been warned ;)</p>
|
|
<p><b>Be sure to read information about <a href="queues.html">queues in rsyslog</a></b> -
|
|
many parameter settings modify queue parameters. If in doubt, use the
|
|
default, it is usually well-chosen and applicable in most cases.</p>
|
|
<ul>
|
|
<li><a href="rsconf1_actionexeconlywhenpreviousissuspended.html">$ActionExecOnlyWhenPreviousIsSuspended</a></li>
|
|
<li>$ActionQueueCheckpointInterval <number></li>
|
|
<li>$ActionQueueDequeueSlowdown <number> [number
|
|
is timeout in <i> micro</i>seconds (1000000us is 1sec!),
|
|
default 0 (no delay). Simple rate-limiting!]</li>
|
|
<li>$ActionQueueDiscardMark <number> [default
|
|
9750]</li>
|
|
<li>$ActionQueueDiscardSeverity <number>
|
|
[*numerical* severity! default 4 (warning)]</li>
|
|
<li>$ActionQueueFileName <name></li>
|
|
<li>$ActionQueueHighWaterMark <number> [default
|
|
8000]</li>
|
|
<li>$ActionQueueImmediateShutdown [on/<b>off</b>]</li>
|
|
<li>$ActionQueueSize <number></li>
|
|
<li>$ActionQueueLowWaterMark <number> [default
|
|
2000]</li>
|
|
<li>$ActionQueueMaxFileSize <size_nbr>, default 1m</li>
|
|
<li>$ActionQueueTimeoutActionCompletion <number>
|
|
[number is timeout in ms (1000ms is 1sec!), default 1000, 0 means
|
|
immediate!]</li>
|
|
<li>$ActionQueueTimeoutEnqueue <number> [number
|
|
is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li>
|
|
<li>$ActionQueueTimeoutShutdown <number> [number
|
|
is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li>
|
|
<li>$ActionQueueWorkerTimeoutThreadShutdown
|
|
<number> [number is timeout in ms (1000ms is 1sec!),
|
|
default 60000 (1 minute)]</li>
|
|
<li>$ActionQueueType [FixedArray/LinkedList/<b>Direct</b>/Disk]</li>
|
|
<li>$ActionQueueSaveOnShutdown [on/<b>off</b>]
|
|
</li>
|
|
<li>$ActionQueueWorkerThreads <number>, num
|
|
worker threads, default 1, recommended 1</li>
|
|
<li>$ActionQueueWorkerThreadMinumumMessages
|
|
<number>, default 100</li>
|
|
<li><a href="rsconf1_actionresumeinterval.html">$ActionResumeInterval</a></li>
|
|
<li>$AddUnixListenSocket <name-of-socket> adds
|
|
additional unix socket, default none -- former -a option</li>
|
|
<li>$ActionResumeRetryCount <number> [default 0,
|
|
-1 means eternal]</li>
|
|
<li><a href="rsconf1_allowedsender.html">$AllowedSender</a></li>
|
|
<li><a href="rsconf1_controlcharacterescapeprefix.html">$ControlCharacterEscapePrefix</a></li>
|
|
<li><a href="rsconf1_debugprintcfsyslinehandlerlist.html">$DebugPrintCFSyslineHandlerList</a></li>
|
|
<li>$DebugPrintKernelSymbols (imklog) [on/<b>off</b>]</li>
|
|
<li><a href="rsconf1_debugprintmodulelist.html">$DebugPrintModuleList</a></li>
|
|
<li><a href="rsconf1_debugprinttemplatelist.html">$DebugPrintTemplateList</a></li>
|
|
<li><a href="rsconf1_dircreatemode.html">$DirCreateMode</a></li>
|
|
<li><a href="rsconf1_dirgroup.html">$DirGroup</a></li>
|
|
<li><a href="rsconf1_dirowner.html">$DirOwner</a></li>
|
|
<li><a href="rsconf1_dropmsgswithmaliciousdnsptrrecords.html">$DropMsgsWithMaliciousDnsPTRRecords</a></li>
|
|
<li><a href="rsconf1_droptrailinglfonreception.html">$DropTrailingLFOnReception</a></li>
|
|
<li><a href="rsconf1_dynafilecachesize.html">$DynaFileCacheSize</a></li>
|
|
<li><a href="rsconf1_escapecontrolcharactersonreceive.html">$EscapeControlCharactersOnReceive</a></li>
|
|
<li><a href="rsconf1_failonchownfailure.html">$FailOnChownFailure</a></li>
|
|
<li><a href="rsconf1_filecreatemode.html">$FileCreateMode</a></li>
|
|
<li><a href="rsconf1_filegroup.html">$FileGroup</a></li>
|
|
<li><a href="rsconf1_fileowner.html">$FileOwner</a></li>
|
|
<li><a href="rsconf1_gssforwardservicename.html">$GssForwardServiceName</a></li>
|
|
<li><a href="rsconf1_gsslistenservicename.html">$GssListenServiceName</a></li>
|
|
<li><a href="rsconf1_gssmode.html">$GssMode</a></li>
|
|
<li><a href="rsconf1_includeconfig.html">$IncludeConfig</a></li>
|
|
<li>$klogSymbolLookup (imklog) [<b>on</b>/off] --
|
|
former klogd -x option</li>
|
|
<li>$klogUseSyscallInterface (imklog) [on/<b>off</b>]
|
|
-- former klogd -2 option</li>
|
|
<li>$klogSymbolsTwice (imklog) [on/<b>off</b>] --
|
|
former klogd -s option</li>
|
|
<li>$MainMsgQueueCheckpointInterval <number></li>
|
|
<li>$MainMsgQueueDequeueSlowdown <number> [number
|
|
is timeout in <i> micro</i>seconds (1000000us is 1sec!),
|
|
default 0 (no delay). Simple rate-limiting!]</li>
|
|
<li>$MainMsgQueueDiscardMark <number> [default
|
|
9750]</li>
|
|
<li>$MainMsgQueueDiscardSeverity <severity>
|
|
[either a textual or numerical severity! default 4 (warning)]</li>
|
|
<li>$MainMsgQueueFileName <name></li>
|
|
<li>$MainMsgQueueHighWaterMark <number> [default
|
|
8000]</li>
|
|
<li>$MainMsgQueueImmediateShutdown [on/<b>off</b>]</li>
|
|
<li><a href="rsconf1_mainmsgqueuesize.html">$MainMsgQueueSize</a></li>
|
|
<li>$MainMsgQueueLowWaterMark <number> [default
|
|
2000]</li>
|
|
<li>$MainMsgQueueMaxFileSize <size_nbr>, default
|
|
1m</li>
|
|
<li>$MainMsgQueueTimeoutActionCompletion
|
|
<number> [number is timeout in ms (1000ms is 1sec!),
|
|
default
|
|
1000, 0 means immediate!]</li>
|
|
<li>$MainMsgQueueTimeoutEnqueue <number> [number
|
|
is timeout in ms (1000ms is 1sec!), default 2000, 0 means indefinite]</li>
|
|
<li>$MainMsgQueueTimeoutShutdown <number> [number
|
|
is timeout in ms (1000ms is 1sec!), default 0 (indefinite)]</li>
|
|
<li>$MainMsgQueueWorkerTimeoutThreadShutdown
|
|
<number> [number is timeout in ms (1000ms is 1sec!),
|
|
default 60000 (1 minute)]</li>
|
|
<li>$MainMsgQueueType [<b>FixedArray</b>/LinkedList/Direct/Disk]</li>
|
|
<li>$MainMsgQueueSaveOnShutdown [on/<b>off</b>]
|
|
</li>
|
|
<li>$MainMsgQueueWorkerThreads <number>, num
|
|
worker threads, default 1, recommended 1</li>
|
|
<li>$MainMsgQueueWorkerThreadMinumumMessages
|
|
<number>, default 100</li>
|
|
<li><a href="rsconf1_markmessageperiod.html">$MarkMessagePeriod</a>
|
|
(immark)</li>
|
|
<li><a href="rsconf1_moddir.html">$ModDir</a></li>
|
|
<li><a href="rsconf1_modload.html">$ModLoad</a></li>
|
|
<li>$OmitLocalLogging (imuxsock) [on/<b>off</b>] --
|
|
former -o option</li>
|
|
<li><a href="rsconf1_repeatedmsgreduction.html">$RepeatedMsgReduction</a></li>
|
|
<li><a href="rsconf1_resetconfigvariables.html">$ResetConfigVariables</a></li>
|
|
<li>$WorkDirectory <name> (directory for spool
|
|
and other work files)</li>
|
|
<li>$SystemLogSocketName <name-of-socket> --
|
|
former -p option</li>
|
|
<li>$UDPServerAddress <IP> (imudp) -- local IP
|
|
address (or name) the UDP listens should bind to</li>
|
|
<li>$UDPServerRun <port> (imudp) -- former
|
|
-r<port> option, default 514, start UDP server on this
|
|
port, "*" means all addresses</li>
|
|
<li><a href="rsconf1_umask.html">$UMASK</a></li>
|
|
</ul>
|
|
<p><b>Where <size_nbr> is specified above,</b>
|
|
modifiers can be used after the number part. For example, 1k means
|
|
1024. Supported are k(ilo), m(ega), g(iga), t(era), p(eta) and e(xa).
|
|
Lower case letters refer to the traditional binary defintion (e.g. 1m
|
|
equals 1,048,576) whereas upper case letters refer to their new
|
|
1000-based definition (e.g 1M equals 1,000,000).</p>
|
|
<p>Numbers may include '.' and ',' for readability. So you can
|
|
for example specify either "1000" or "1,000" with the same result.
|
|
Please note that rsyslogd simply ignores the punctuation. Form it's
|
|
point of view, "1,,0.0.,.,0" also has the value 1000. </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>
|
|
<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>
|
|
<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.
|
|
</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>
|
|
<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 accidental 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. <b>As of this writing, it is most likely that they will
|
|
be replaced by something different in the future.</b> 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 definition, 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.
|
|
This command always has exactly one parameter. The binary is that part
|
|
of action-on-max-size before the first space, its parameter is
|
|
everything behind that space.<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 reached, rsyslogd will execute the action-on-max-size command
|
|
and then reopen the file and retry. The command should be something
|
|
like a <a href="log_rotation_fix_size.html">log rotation
|
|
script</a> or a similar thing.</p>
|
|
<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 ‘ppp’ as the program, directly followed by a block
|
|
that selects messages from the hostname ‘dialhost’, then the second
|
|
block will only log messages from the ppp program on dialhost.
|
|
</p>
|
|
<p>A program specification is a line beginning with ‘!prog’ and
|
|
the following blocks will be associated with calls to syslog from that
|
|
specific program. A program specification for ‘foo’ will also match any
|
|
message logged by the kernel with the prefix ‘foo: ’. Alternatively, a
|
|
program specification ‘-foo’ causes the following blocks to be applied
|
|
to messages from any program but the one specified. A hostname
|
|
specification of the form ‘+hostname’ and the following blocks will be
|
|
applied to messages received from the specified hostname.
|
|
Alternatively, a hostname specification ‘-hostname’ causes the
|
|
following blocks to be applied to messages from any host but the one
|
|
specified. If the hostname is given as ‘@’, the local hostname will be
|
|
used. (NOT YET IMPLEMENTED) A program or hostname specification may be
|
|
reset by giving the program or hostname as ‘*’.</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 original
|
|
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 citizens
|
|
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 insensitive 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>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 id="table1" border="1" width="100%">
|
|
<tbody>
|
|
<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 searches 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".</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>regex</td>
|
|
<td>Compares the property against the provided regular
|
|
expression.</td>
|
|
</tr>
|
|
</tbody>
|
|
</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>
|
|
<h3>Expression-Based Filters</h3>
|
|
So far, please see <a href="expression.h">expressions</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>
|
|
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><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 MySQL</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>
|
|
<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
|
|
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>
|
|
<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 resembles 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> |