Use this documentation with care! It describes
the heavily outdated version 5, which was actively
developed around 2010 and is considered dead by the
rsyslog team for many years now.
This documentation reflects the latest update of the
previously existing (now removed) v5-stable branch.
It describes the 5.10.2 version, which was never
released. As such, it contains some content that
does not apply to any released version.
To obtain the doc that properly matches your installed
v5 version, obtain the doc set from your distro. Each
version of rsyslog contained the version that exactly
matches it.
As general advise, it is strongly suggested to
upgrade to the current version supported by the rsyslog
project. The current version can always be found on
the right-hand side info box on the
rsyslog web site.
Note that there is no rsyslog community support available
for this heavily outdated version. If you need to stick
with it, please ask your distribution for support.
This section describes how rsyslog configuration basically works. Think of rsyslog as a big logging and event processing toolset. It can be considered as a framework with some basic processing that is fixed in the way data flows, but is highly custumizable in the details of this message flow. During configuration, this customization is done by defining and customizing the rsyslog objects.
Messages enter rsyslog with the help of input modules. Then, they are passed to ruleset, where rules are conditionally applied. When a rule matches, the message is transferred to an action, which then does something to the message, e.g. write it to a file or database or forward it to a remote host.
Upon startup, rsyslog reads its configuration from the rsyslog.conf
file by default. This file may contain references to include other
config files.
A different “root” configuration file can be specified via the -f <file>
rsyslogd command line option. This is usually done within some init
script or similiar facility.
Rsyslog supports two different types of configuration statements concurrently:
The rsyslog.conf files consists of statements. Each statement must be on one line (and not be split among lines).
Comments start with a hash sign (#) and run to the end of the line.
Directives are processed from the top of rsyslog.conf to the bottom. Sequence matters. For example, if you stop processing of a message, obviously all statements after the stop statement are never evaluated.
Flow control is provided by filter conditions.
Every input requires an input module to be loaded and a listener defined for it. Full details can be found inside the rsyslog modules documentation.
Outputs are also called “actions”. A small set of actions is pre-loaded (like the output file writer, which is used in almost every rsyslog.conf), others must be loaded just like inputs.
Rulesets and rules form the basis of rsyslog processing. In short, a rule is a way how rsyslog shall process a specific message. Usually, there is a type of filter (if-statement) in front of the rule. Complex nesting of rules is possible, much like in a programming language.
Rulesets are containers for rules. A single ruleset can contain many rules. In the programming language analogy, one may think of a ruleset like being a program. A ruleset can be “bound” (assigned) to a specific input. In the analogy, this means that when a message comes in via that input, the “program” (ruleset) bound to it will be executed (but not any other!).
There is detail documentation available for rsyslog rulesets.