Basic Structure¶

This page introduces the core concepts and structure of rsyslog configuration. Rsyslog is best thought of as a highly extensible logging and event processing framework. While the general message flow is fixed, almost every aspect of its processing pipeline can be customized by configuring rsyslog objects.

Message Flow Overview¶

At a high level, rsyslog processes messages in three main stages:

Inputs: Messages are received from input modules (e.g., imuxsock for system logs or imtcp for TCP-based logging).
Rulesets: Each message is passed through one or more rulesets. A ruleset contains a sequence of rules, each with a filter and associated actions.
Actions (Outputs): When a rule matches, its actions are executed. Actions determine what to do with the message: write to a file, forward to a remote server, insert into a database, or other processing.

        flowchart LR
    A[Input Modules] --> B[Rulesets]
    B --> C[Rules: Filter and Action List]
    C --> D[Actions and Outputs]
    D --> E[File, DB, Remote,<br>Custom Destinations]

Processing Principles¶

Key rules to understand the rsyslog processing model:

Rulesets as Entry Points:

Inputs submit messages to a ruleset. If no ruleset is explicitly bound, the default ruleset (RSYSLOG_DefaultRuleset) is used. Additional, custom rulesets can be defined.
Rules within Rulesets:

A ruleset contains zero or more rules (though zero rules makes no sense). Rules are evaluated in order, top to bottom, within the ruleset.
Filter and Action Lists:

A rule consists of a filter (evaluated as true/false) and an action list. When a filter matches, the action list is executed. If a filter does not match, rsyslog continues with the next rule.
Full Evaluation:

All rules are evaluated unless message processing is explicitly stopped by a stop command. stop immediately halts processing for that message.
Action Lists:

An action list can contain one or multiple actions. Actions are executed sequentially. Actions have no filters inside the same list (filters apply only at the rule level).

        flowchart TD
    Start([Message Entered]) --> CheckFilter1{Filter 1 Match?}
    CheckFilter1 -- Yes --> Action1[Execute Action 1]
    CheckFilter1 -- No --> CheckFilter2{Filter 2 Match?}
    CheckFilter2 -- Yes --> Action2[Execute Action 2]
    CheckFilter2 -- No --> End([Processing Ends])
    Action1 --> CheckFilter2
    Action2 --> End

Configuration File¶

By default, rsyslog loads its configuration from /etc/rsyslog.conf. This file may include other configuration snippets (commonly under /etc/rsyslog.d/).

To specify a different configuration file, use:

rsyslogd -f /path/to/your-config.conf

Supported Configuration Formats¶

Rsyslog historically supported three configuration syntaxes:

RainerScript (modern style) – recommended and actively maintained

This is the current, fully supported configuration format. It is clean, structured, and best suited for new and complex configurations.
sysklogd style (legacy) – deprecated for new configs

This format is widely known and still functional, but hard to grasp for new users. It remains an option for experienced admins who know it well or need to maintain older configurations. Example:
```
mail.info    /var/log/mail.log
mail.err     @server.example.net
```
Legacy rsyslog style (dollar-prefix) – deprecated

This format, with directives starting with $ (e.g., $ActionFileDefaultTemplate), is fully supported for backward compatibility but not recommended for any new configuration.

Why Prefer RainerScript?¶

RainerScript is easier to read and maintain, avoids side effects with include files, and supports modern features such as structured filters, templates, and complex control flow.

For new configurations, always use RainerScript. Legacy formats exist only for compatibility with older setups and distributions.

Example RainerScript rule:

if $syslogfacility-text == 'mail' and $syslogseverity-text == 'err' then {
    action(type="omfile" file="/var/log/mail-errors.log")
}

Comments¶

Rsyslog supports:

# Comments — start with # and extend to the end of the line.
C-style Comments — start with /* and end with */. These can span multiple lines but cannot be nested.

Processing Order¶

Directives are processed in order from top to bottom of the configuration.
Once a message is stopped via stop subsequent statements will not be evaluated for that message.

Flow Control¶

Control structures (if/else, etc.) are available in RainerScript.
Filters (e.g., prifilt()) provide conditional matching for messages.

See Control Structures and Filter Conditions for details.

Data Manipulation¶

Data can be modified using the set, unset, and reset statements. For details, refer to Variable (Property) types.

Inputs¶

Each input requires a dedicated input module.
Inputs are defined using the input() object after loading the module.

Example:

module(load="imtcp")                   # Load TCP input module
input(type="imtcp" port="514")         # Listen on TCP port 514

See Modules for the full list of input modules.

Outputs (Actions)¶

Actions are responsible for output, such as writing to files, databases, or forwarding to other systems.
Actions are configured with the action() object.

Example:

action(type="omfile" file="/var/log/messages")   # Write to local file

Rulesets and Rules¶

A ruleset acts like a “program” for message processing.
A ruleset can be bound to specific inputs or used as the default.

Example:

ruleset(name="fileLogging") {
    if prifilt("*.info") then {
        action(type="omfile" file="/var/log/info.log")
    }
}

        graph TD
    Input1[Input: imtcp] --> Ruleset1
    Input2[Input: imudp] --> Ruleset2
    Ruleset1 --> Action1[omfile]
    Ruleset2 --> Action2[omfwd]
    Ruleset2 --> Action3[omelasticsearch]

For details, see Multiple Rulesets in rsyslog.

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project