# 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:

1. Inputs: Messages are received from input modules (e.g., imuxsock for system logs or imtcp for TCP-based logging).

2. Rulesets: Each message is passed through one or more rulesets. A ruleset contains a sequence of rules, each with a filter and associated actions.

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

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

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

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

© 2008–2025 Rainer Gerhards and others. Licensed under the Apache License 2.0.