doc/source/configuration/basic_structure.rst - main - githubmirror/rsyslog

doc/source/configuration/basic_structure.rst
248 строк7 KB
Rainer Gerhards
doc: clarify RainerScript semicolon use
21 июн 2026, 10:37
21 июн 2026, 10:37c4b0b25
Basic Structure
===============

.. meta::
   :description: Introduction to rsyslog configuration structure, formats,
      rulesets, actions, and common RainerScript syntax.
   :keywords: rsyslog, configuration, RainerScript, ruleset, action, input, semicolon

.. summary-start

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.

.. summary-end

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.

.. mermaid::

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

.. mermaid::

   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:

.. code-block:: bash

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

Supported Configuration Formats
-------------------------------

Rsyslog currently supports four configuration syntaxes:

1. **RainerScript (modern style)** - **fully supported and actively maintained**

   This is the current, fully supported configuration format. It is
   clean, structured, and a strong fit when you author rsyslog logic directly.

2. **YAML** - **fully supported for YAML-centric workflows**

   Use this when rsyslog is part of a broader YAML-based deployment or
   automation environment. YAML and RainerScript express the same underlying
   rsyslog concepts and share the same core semantics.

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

   .. code-block:: none

      mail.info    /var/log/mail.log
      mail.err     @server.example.net

4. **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 Use RainerScript Directly?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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 direct rsyslog authoring, RainerScript remains the clearest default.
If your environment is already YAML-centric, YAML is also a first-class fit.
Legacy formats exist only for compatibility with older setups and
distributions.

Example RainerScript rule:

.. code-block:: rsyslog

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

Configuration objects such as ``action()``, ``module()``, and ``input()`` end
at the closing parenthesis. Do not add a semicolon after them:

.. code-block:: rsyslog

   action(type="omfile" file="/var/log/messages")    # correct
   action(type="omfile" file="/var/log/messages");   # invalid

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 :doc:`../rainerscript/control_structures` and :doc:`filters` for details.

Data Manipulation
~~~~~~~~~~~~~~~~~

Data can be modified using the `set`, `unset`, and `reset` statements.
For details, refer to :doc:`../rainerscript/variable_property_types`.

Inputs
------

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

Example:

.. code-block:: rsyslog

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

See :doc:`modules/index` 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:

.. code-block:: rsyslog

   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:

.. code-block:: rsyslog

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

.. mermaid::

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

For details, see :doc:`../concepts/multi_ruleset`.