rsyslog.conf configuration file

This document is currently being enhanced. Please pardon its current appearance.

Rsyslogd is configured via the rsyslog.conf file, typically found in /etc. By default, rsyslogd reads the file /etc/rsyslog.conf.

While rsyslogd contains enhancements over standard syslogd, efforts have been made to keep the configuration file as compatible as possible. While, for obvious reasons, enhanced features 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.

Global Directives

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.

• $ActionResumeInterval

Basic Structure

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.

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.

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.

Lines starting with a hash mark ("#'') and empty lines are ignored.

ActionExecOnlyIfPreviousIsSuspended

This directive allows to specify if actions should always be executed ("off," the default) or only if the previous action is suspended ("on"). This directive works hand-in-hand with the multiple actions per selector feature. It can be used, for example, to create rules that automatically switch destination servers or databases to a (set of) backup(s), if the primary server fails. Note that this feature depends on proper implementation of the suspend feature in the output module. All built-in output modules properly support it (most importantly the database write and the syslog message forwarder).

The following is an example of what can be done with it (a config file excerpt):

*.* @@primary-syslog.example.com
$ActionExecOnlyIfPreviousIsSuspended on
&   @@secondary-1-syslog.example.com    # & is used to have more than one action for
&   @@secondary-2-syslog.example.com    # the same selector - the mult-action feature
&   /var/log/localbuffer
$ActionExecOnlyIfPreviousIsSuspended off # to re-set it for the next selector

This selector processes all messages it receives (*.*).  It tries to forward every message to primary-syslog.example.com (via tcp). If it can not reach that server, it tries secondary-1-syslog.example.com, if that fails too, it tries secondary-2-syslog.example.com. If neither of these servers can be connected, the data is stored in /var/log/localbuffer. Please note that the secondaries and the local log buffer are only used if the one before them does not work. So ideally, /var/log/localbuffer will never receive a message. If one of the servers resumes operation, it automatically takes over processing again.

We strongly advise not to use repeated line reduction together with ActionExecOnlyIfPreviousIsSuspended. It may lead to "interesting" and undesired results (but you can try it if you like).

Allowed Sender Lists

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).

Allowed sender lists can be defined for UDP and TCP senders separately. There can be as many allowed senders as needed. The syntax to specify them is:

$AllowedSender <protocol>, ip[/bits], ip[/bits]

"$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 with IPv4, they are adjusted to 32. For IPv6, the limit is 128 for obvious reasons. Hostnames, with and without wildcards, may also be provided. If so, the result of revers DNS resolution is used for filtering. 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.

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.

WARNING: by UDP design, rsyslogd can not identify a spoofed sender address in UDP syslog packets. As such, a malicious person could spoof the address 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.

Rsyslog also detects some kind of malicious reverse DNS entries. In any case, using DNS names adds an extra layer of vulnerability. We recommend to stick with hard-coded IP addresses whereever possible.

An example for an allowed sender list is as follows:

$AllowedSender UDP, 127.0.0.1, 192.0.2.0/24, [::1]/128, *.example.net, somehost.example.com

UMASK

The $umask directive allows to specify the rsyslogd processes' umask. If not specified, the system-provided default is used. The value given must always be a 4-digit octal number, with the initial digit being zero. This sample removes all umask-restriction:

$umask 0000

If $umask is specified multiple times in the configuration file, results may be somewhat unpredictable. It is recommended to specify it only once.

FileCreateMode

The $FileCreateMode directive allows to specify the creation mode with which rsyslogd creates new files. If not specified, the value 0644 is used (which retains backward-compatibility with earlier releases). The value given must always be a 4-digit octal number, with the initial digit being zero. This sample lets rsyslog create files with read and write access only for the users it runs under:

$FileCreateMode 0600

Please note that the actual permission depend on rsyslogd's process umask. If in doubt, use "$umask 0000" right at the beginning of the configuration file to remove any restrictions.

$FileCreateMode may be specified multiple times. If so, it specifies the creation mode for all selector lines that follow until the next $FileCreateMode directive. Order of lines is vitally important. Here is a sample (this is deemed to be a complete rsyslog.conf):

$umask 0000 # make sure nothing interfers with the following definitions
*.* /var/log/file-with-0644-default
$FileCreateMode 0600
*.* /var/log/file-with-0600
$FileCreateMode 0644
*.* /var/log/file-with-0644

As you can see, open modes depend on position in the config file. Note the first line, which is created with the hardcoded default creation mode.

DebugPrintCFSyslineHandlerList

Specifies whether or not the configuration file sysline handler list should be written to the debug log. Possible values: on/off. Default is on. Does not affect operation if debugging is disabled.

DebugPrintModuleList

Specifies whether or not the module list should be written to the debug log. Possible values: on/off. Default is on. Does not affect operation if debugging is disabled.

DebugPrintTemplateList

Specifies whether or not the template list should be written to the debug log. Possible values: on/off. Default is on. Does not affect operation if debugging is disabled.

DirCreateMode

This is the same as $FileCreateMode, but for directories automatically generated.

DirGroup

Set the group for directories newly created. Please note that this setting does not affect the group of directories already existing. The parameter is a group name, for which the groupid is obtained by rsyslogd on startup and on HUPing. Interim changes to the user mapping are not detected.

$DirGroup loggroup

DirOwner

Set the file owner for directories newly created. Please note that this setting does not affect the owner of directories already existing. The parameter is a user name, for which the userid is obtained by rsyslogd on startup and on HUPing. Interim changes to the user mapping are not detected.

$DirOwner loguser

IncludeConfig

This directive allows to include other files into the main configuration file. As soon as an IncludeConfig directive is found, the contents of the new file is processed. IncludeConfigs can be nested. Please note that from a logical point of view the files are merged. Thus, if the include modifies some parameters (e.g. $DynaFileChacheSize), these new parameters are in place for the "calling" configuration file when the include is completed. To avoid any side effects, do a $ResetConfigVariables after the $IncludeConfig. It may also be a good idea to do a $ResetConfigVariables right at the start of the include, so that the module knows exactly what it does. Of course, one might specifically NOT do this to inherit parameters from the main file. As always, use it as it best fits...

$IncludeConfig /etc/some-included-file.conf

Directories can also be included. To do so, the name must end on a slash:

$IncludeConfig /etc/rsyslog.d/

In this case, all regular files in the /etc/rsyslog.d directory are included. Files starting with "." are ignored - so you can use them to place comments into the dir (e.g. "/etc/rsyslog.d/.mycomment" will be ignored). Michael Biebl had the idea to this functionality. Let me quote hím:

Say you can add an option
$IncludeConfig /etc/rsyslog.d/
(which probably would make a good default)
to /etc/rsyslog.conf, which would then merge and include all *.conf files
in /etc/rsyslog.d/.

This way, a distribution can modify its packages easily to drop a simple
config file into this directory upon installation.

As an example, the network-manager package could install a simple config
file /etc/rsyslog.d/network-manager.conf which would contain.
:programname, contains, "NetworkManager" -/var/log/NetworkManager.log

Upon uninstallation, the file could be easily removed again. This approach
would be much cleaner and less error prone, than having to munge around
with the /etc/rsyslog.conf file directly.

Please note that in this description, only "*.conf" files would be read. The actual implementation, however, reads all files except for those starting with a dot. If you find this is a real big problem, please complain.

RepeatedMsgReduction

This directive specifies whether or not repeated messages should be reduced (this is the "Last line repeated n times" feature). If set to on, repeated messages are reduced. If set to off, every message is logged. Please note that this directive overrides the -e command line option. In case -e is given, it is just the default value until the first RepeatedMsgReduction directive is encountered. Sample:

$RepeatedMsgReduction off    # log every message

Directives affects selector lines until a new directive is specified.

DynaFileCacheSize

This directive specifies the maximum size of the cache for dynamically-generated file names. Selector lines with dynamic files names ('?' indicator) support writing to multiple files with a single selector line. This setting specifies how many open file handles should be cached. If, for example, the file name is generated with the hostname in it and you have 100 different hosts, a cache size of 100 would ensure that files are opened once and then stay open. This can be a great way to increase performance. If the cache size is lower than the number of different files, the least recently used one is discarded (and the file closed). The hardcoded maximum is 10,000 - a value that we assume should already be very extreme. Please note that if you expect to run with a very large number of files, you probably need to reconfigure the kernel to support such a large number. In practice, we do NOT recommend to use a cache of more than 1,000 entries. The cache lookup would probably require more time than the open and close operations. The minimum value is 1. Here is a sample:

$DynaFileCacheSize 100    # a cache of 100 files at most

Numbers are always in decimal. Leading zeros should be avoided (in some later version, they may be mis-interpreted as being octal). Multiple directives may be given. They are applied to selector lines based on order of appearance.

DropMsgsWithMaliciousDnsPTRRecords

Rsyslog contains code to detect malicious DNS PTR records (reverse name resolution). An attacker might use specially-crafted DNS entries to make you think that a message might have originated on another IP address. Rsyslog can detect those cases. It will log an error message in any case. It this option here is set to "on", the malicious message will be completely dropped from your logs. If the option is set to "off", the message will be logged, but the original IP will be used instead of the DNS name.

$DropMsgsWithMaliciousDnsPTRRecords on

DropTrailingLFOnReception

Syslog messages frequently have the line feed character (LF) as the last character of the message. In allmost all cases, this LF should not really become part of the message. However, recent IETF syslog standardization recommends against modifying syslog messages (e.g. to keep digital signatures valid). This option allows to specify if trailing LFs should be dropped or not. The default is to drop them, which is consistent with what sysklogd does. To not drop them, use

$DropTrailingLFOnRecption off

ControlCharacterEscapePrefix

This option specifies the prefix character to be used for control character escaping (see option $EscapeControlCharactersOnReceive). By default, it is '\', which is backwards-compatible with sysklogd. Change it to '#' in order to be compliant to the value that is somewhat suggested by Internet-Draft syslog-protocol. The first non-whitespace character after the command is treated as prefix:

$EscapeControlCharactersOnReceive #  # as of syslog-protocol

IMPORTANT: do not use the ' character. This is reserved and will most probably be used in the future as a character delimiter. For the same reason, the syntax of this directive will probably change in furture releases.

EscapeControlCharactersOnReceive

This directive instructs rsyslogd to replace control characters during reception of the message. The intent is to provide a way to stop non-printable messages from entering the syslog system as whole. If this option is truned on, all control-characters are converted to a 3-digit octal number and be prefixed with the $ControlCharacterEscapePrefix character (being '\' by default). For example, if the BEL character (ctrl-g) is included in the message, it would be converted to "\007". To be compatible to sysklogd, this option must be turned on.

$EscapeControlCharactersOnReceive on

Warning:

• turning on this option most probably destroys non-western character sets (like Japanese, Chinese and Korean)
• turning on this option destroys digital signatures if such exists inside the message

FailOnChownFailure

This option modifies behaviour of dynaFile creation. If different owners or groups are specified for new files or directories and rsyslogd fails to set these new owners or groups, it will log an error and NOT write to the file in question if that option is set to "on". If it is set to "off", the error will be ignored and processing continues. Keep in mind, that the files in this case may be (in)accessible by people who should not have permission. The default is "on".

$FailOnChownFailure off

FileGroup

Set the group for dynaFiles newly created. Please note that this setting does not affect the group of files already existing. The parameter is a group name, for which the groupid is obtained by rsyslogd on startup and on HUPing. Interim changes to the user mapping are not detected.

$FileGroup loggroup

FileOwner

Set the file owner for dynaFiles newly created. Please note that this setting does not affect the owner of files already existing. The parameter is a user name, for which the userid is obtained by rsyslogd on startup and on HUPing. Interim changes to the user mapping are not detected.

$FileOwner loguser

ResetConfigVariables

Resets all configuration variables to their default value. Any settings made will not be applied to configuration lines following the $ResetConfigVariables. This is a good method to make sure no side-effects exists from previous directives. This directive has no parameters.

$ResetConfigVariables

MainMsgQueueSize

This allows to specify the maximum size of the message queue. This directive is only available when rsyslogd has been compiled with multithreading support. In this mode, receiver and output modules are de-coupled via an in-memory queue. This queue buffers messages when the output modules are not capable to process them as fast as they are received. Once the queue size is exhausted, messages will be dropped. The slower the output (e.g. MySQL), the larger the queue should be. Buffer space for the actual queue entries is allocated on an as-needed basis. Please keep in mind that a very large queue may exhaust available system memory and swap space. Keep this in mind when configuring the max size. The actual size of a message depends largely on its content and the orginator. As a rule of thumb, typically messages should not take up more then roughtly 1k (this is the memory structure, not what you see in a network dump!). For typical linux messages, 512 bytes should be a good bet. Please also note that there is a minimal amout of memory taken for each queue entry, no matter if it is used or not. This is one pointer value, so on 32bit systems, it should typically be 4 bytes and on 64bit systems it should typically be 8 bytes. For example, the default queue size of 10,000 entries needs roughly 40k fixed overhead on a 32 bit system.

$MainMsgQueueSize 100000 # 100,000 may be a value to handle bursty traffic

ModLoad

This currently is a dummy directive. It will support the loading of plug-ins in future releases of rsyslog supporting plug-ins. Currently, only

$ModLoad MySQL

is supported, which activates MySQL support (if rsyslog is compiled with MySQL functionality).

Templates

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.

A template consists of a template directive, a name, the actual template text and optional options. A sample is:

$template MyTemplateName,"\7Text %property% some more text\n",<options>

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.

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.

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).

Template options are case-insensitive. Currently defined are:

sql - 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 NO_BACKSLASH_ESCAPES mode must be turned off for this format to work (this is the default).

stdsql - 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 NO_BACKSLASH_ESCAPES is turned on.

Either the sql or stdsql  option must 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. If you choose the wrong one, you are still vulnerable to sql injection.

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 ;)

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 NO_BACKSLASH_ESCAPES in your MySQL config, you need to supply a template with the stdsql option. Otherwise you will become vulnerable to SQL injection.

To escape:
% = \%
\ = \\ --> '\' is used to escape (as in C)
$template TraditionalFormat,%timegenerated% %HOSTNAME% %syslogtag%%msg%\n"

Properties can be accessed by the property replacer (see there for details).

Please note that as of 1.15.0, templates can also by used to generate selector lines with dynamic file names. 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:

$template DynFile,"/var/log/system-%HOSTNAME%.log"

This template can then be used when defining an output selector line. It will result in something like "/var/log/system-localhost.log"

Output Channels

Output Channels are a new concept first introduced in rsyslog 0.9.0. As of this writing, it is most likely that they will be replaced by something different in the future. So if you use them, be prepared to change you configuration file syntax when you upgrade to a later release.

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,
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
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.

In concept, an output channel includes everything needed to know about an output actions. In practice, the current implementation only carries
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.

Output channels are defined via an $outchannel directive. It's syntax is as follows:

$outchannel name,file-name,max-size,action-on-max-size

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.

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.

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:

*.* $mychannel

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.

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.

Filter Conditions

Rsyslog offers two different types "filter conditions":

• "traditional" severity and facility based selectors
• property-based filters

Blocks

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.

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: ’. 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 ‘*’.

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.

Selectors

Selectors are the traditional way of filtering syslog messages. 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 not second-class citicens in rsyslog and offer the best performance for this job.

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.

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.

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.

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

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.

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.

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.

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.

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.

Property-Based Filters

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 property replacer documentation (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.

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:

:property, [!]compare-operation, "value"

The following compare-operations are currently supported:

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:

:msg, contains, "error"

but this one matches:

:msg, !contains, "error"

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:

*.* /var/log/allmsgs-including-informational.log
:msg, contains, "informational"  ~
*.* /var/log/allmsgs-but-informational.log

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.

Value is a quoted string. It supports some escape sequences:

\" - the quote character (e.g. "String with \"Quotes\"")
\\ - the backslash character (e.g. "C:\\tmp")

Escape sequences always start with a backslash. Additional escape sequences might be added in the future. Backslash characters must be escaped. Any other sequence then those outlined above is invalid and may lead to unpredictable results.

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:

:msg, contains, "ID-4711"

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.

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.

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.

ACTIONS

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.

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.

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.

You can have multiple actions for a single selector  (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

*.=crit rger
& root
& /var/log/critmsgs

These three lines send critical messages to the usrs rger and root and also store them in /var/log/critmsgs. Using multiple actions per selector is convenient and also offers a performance benefit. 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:

*.=crit rger
*.=crit root
*.=crit /var/log/critmsgs

Regular File

Typically messages are logged to real files. The file has to be specified with full pathname, beginning with a slash "/''.

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.

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.

The filename can be either static (always the same) or dynamic (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.

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:

*.* ?DynFile

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

*.* -?DynFile

And of course you can use templates to specify the output format:

*.* ?DynFile;MyTemplate

A word of caution: rsyslog creates files as needed. So if a new host is using your syslog server, rsyslog will automatically create a new file for it. However, directories are never created. 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.

Named Pipes

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.

Terminal and Console

If the file you specified is a tty, special tty-handling is done, same with /dev/console.

Remote Machine

Rsyslogd provides full remote logging, i.e. is able to send messages to a remote host running rsyslogd(8) and to receive messages from remote hosts. Using this feature you're able to control all syslog messages on one host, if all other machines will log remotely to that. This tears down
administration needs.

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.

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:

The hostname may be followed by a colon and the destination port.

The following is an example selector line with forwarding:

*.*    @@(o,z9)192.168.0.1:1470

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.

*.* @192.168.0.1

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.

List of Users

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.

Everyone logged on

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 ("*'').

Database Table

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
use any other schema of your liking - you just need to define a proper template and assign this template to the action.

The database writer is called by specifying a greater-then sign (">") in front of the database connect information. Immediately after that
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:

>dbhost,dbname,dbuser,dbpassword;dbtemplate

Important: to use the database functionality, MySQL must be enabled in the config file BEFORE the first database table action is used. This is done by placing the

$ModLoad MySQL

directive some place above the first use of the database write (we recommend doing at the the begining of the config file). Please note that rsyslog must also have been built with MySQL support (many packages do not do this by default).

Discard

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.

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.

Discard is just the single tilde character with no further parameters:

~

For example,

*.*   ~

discards everything (ok, you can achive the same by not running rsyslogd at all...).

Output Channel

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.

Shell Execute

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.

^program-to-execute;template

The program-to-execute can be any valid executable. It receives the template string as a single parameter (argv[1]).

WARNING: 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.

TEMPLATE NAME

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.

EXAMPLES

Below are example for templates and selector lines. I hope they are self-explanatory. If not, please see www.monitorware.com/rsyslog/ for advise.

TEMPLATES

Please note that the samples are split across multiple lines. A template MUST NOT actually be split across multiple lines.

A template that resambles traditional syslogd file output:
$template TraditionalFormat,"%timegenerated% %HOSTNAME%
%syslogtag%%msg:::drop-last-lf%\n"

A template that tells you a little more about the message:
$template precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,
%syslogtag%,%msg%\n"

A template for RFC 3164 format:
$template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag%%msg%"

A template for the format traditonally used for user messages:
$template usermsg," XXXX%syslogtag%%msg%\n\r"

And a template with the traditonal wall-message format:
$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME% at %timegenerated%

A template that can be used for the database write (please note the SQL
template option)
$template MySQLInsert,"insert iut, message, receivedat values
('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')
into systemevents\r\n", SQL

The following template emulates WinSyslog format (it's an Adiscon 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.

$template WinSyslogFmt,"%HOSTNAME%,%timegenerated:1:10:date-rfc3339%,
%timegenerated:12:19:date-rfc3339%,%timegenerated:1:10:date-rfc3339%,
%timegenerated:12:19:date-rfc3339%,%syslogfacility%,%syslogpriority%,
%syslogtag%%msg%\n"

SELECTOR LINES

# Store critical stuff in critical
#
*.=crit;kern.none /var/adm/critical

This will store all messages with the priority crit in the file /var/adm/critical, except for any kernel message.


# Kernel messages are first, stored in the kernel
# file, critical messages and higher ones also go
# to another host and to the console. Messages to
# the host finlandia are forwarded in RFC 3164
# format (using the template defined above).
#
kern.* /var/adm/kernel
kern.crit @finlandia;RFC3164fmt
kern.crit /dev/console
kern.info;kern.!err /var/adm/kernel-info

The first rule direct any message that has the kernel facility to the file /var/adm/kernel.

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.

The third rule directs these messages to the actual console, so the person who works on the machine will get them, too.

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.


# The tcp wrapper loggs with mail.info, we display
# all the connections on tty12
#
mail.=info /dev/tty12

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.


# Store all mail concerning stuff in a file
#
mail.*;mail.!=info /var/adm/mail

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.


# Log all mail.info and news.info messages to info
#
mail,news.=info /var/adm/info

This will extract all messages that come either with mail.info or with news.info and store them in the file /var/adm/info.


# Log info and notice messages to messages file
#
*.=info;*.=notice;\
mail.none /var/log/messages

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
messages that use the mail facility.


# Log info messages to messages file
#
*.=info;\
mail,news.none /var/log/messages

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.


# Emergency messages will be displayed using wall
#
*.=emerg *

This rule tells rsyslogd to write all emergency messages to all currently logged in users. This is the wall action.


# Messages of the priority alert will be directed
# to the operator
#
*.alert root,rgerhards

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.


*.* @finlandia

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.

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:


*.* @@finlandia

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:


*.* @@finlandia:1514

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-
sons. If you would like to do that, it's quite easy:


*.* @finlandia:1514



*.* >dbhost,dbname,dbuser,dbpassword;dbtemplate

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.

:msg,contains,"error" @errorServer

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

CONFIGURATION FILE SYNTAX DIFFERENCES

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.

The original BSD syslogd doesn't understand spaces as separators between the selector and the action field.

When compared to syslogd from sysklogd package, rsyslogd offers additional features (like template and database support). For obvious reasons, the syntax for defining such features is available in rsyslogd, only.