This section describes how rsyslog configuration basically works. Think of rsyslog as a big logging and event processing toolset. It can be considered a framework with some basic processing that is fixed in the way data flows, but is highly customizable 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. writes it to a file, database or forwards 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 similar facility.
Rsyslog supports three different types of configuration statements concurrently:
The rsyslog.conf files consists of statements. For old style (sysklogd & legacy rsyslog), lines do matter. For new style (RainerScript) line spacing is irrelevant. Most importantly, this means with new style actions and all other objects can split across lines as users want to.
In general it is recommended to use RainerScript type statements, as these provide clean and easy to read control-of-flow as well as no doubt about which parameters are active. They also have no side-effects with include files, which can be a major obstacle with legacy rsyslog statements.
For very simple things sysklogd statement types are still suggested, especially if the full config consists of such simple things. The classical sample is writing to files (or forwarding) via priority. In sysklogd, this looks like:
mail.info /var/log/mail.log
mail.err @server.example.net
This is hard to beat in simplicity, still being taught in courses and a lot of people know this syntax. It is perfectly fine to use these constructs even in newly written config files.
As a rule of thumb, RainerScript config statements should be used when
It is usually not recommended to use rsyslog legacy config format (those directives starting with a dollar sign). However, a few settings and modules have not yet been converted to RainerScript. In those cases, the legacy syntax must be used.
There are two types of comments:
Directives are processed from the top of rsyslog.conf to the bottom. Order matters. For example, if you stop processing of a message, obviously all statements after the stop statement are never evaluated.
Data manipulation is achieved by set, unset and reset statements which are documented here in detail.
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. Once loaded, inputs are defined via the input() object.
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.
An action is invoked via the action(type=”type” ...) object. Type is mandatory and must contain the name of the plugin to be called (e.g. “omfile” or “ommongodb”). Other parameters may be present. Their type and use depends on the output plugin in question.
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 detailed documentation available for rsyslog rulesets.
For quick reference, rulesets are defined as follows:
ruleset(name="rulesetname") {
action(type="omfile" file="/path/to/file")
action(type="..." ...)
/* and so on... */
}