Compatibility Notes for rsyslog v8

output plugin interface

To support the new core engine, the output interface has been considerably changed. It is suggested to review some of the project-provided plugins for full details. In this doc, we describe the most important changes from a high level perspective.

Multi-thread awareness required

The new engine activates one workerinstance of output actions on each worker thread. This means an action has now three types of data:

• global

• action-instance - previously known pData, one for each action inside the config

• worker-action-instance - one for each worker thread (called pWrkrData), note that this is specific to exactly one pData

The plugin must now by multi-threading aware. It may be called by multiple threads concurrently, but it is guaranteed that each call is for a unique pWrkrData structure. This still permits to write plugins easily, but enables the engine to work with much higher performance. Note that plugin developers should assume it is the norm that multiple concurrent worker action instances are active a the some time.

New required entry points

In order to support the new threading model, new entry points are required. Most importantly, only the plugin knows which data must be present in pData and pWrkrData, so it must created and destroy these data structures on request of the engine. Note that pWrkrData may be destroyed at any time and new ones re-created later. Depending on workload structure and configuration, this can happen frequently.

New entry points are:

• createWrkrInstance

• freeWrkrInstance

The calling interface for these entry points has changed. Basically, they now receive a pWrkrData object instead pData. It is assumed that createWrkrInstance populates pWrkrData->pData appropriately.

• beginTransaction

• doAction

• endTransaction

Changed entry points

Some of the existing entry points have been changed.

The doAction entry point formerly got a variable iMsgOpts which is no longer provided. This variable was introduced in early days and exposed some internal message state information to the output module. Review of all known existing plugins showed that none except omfile ever used that variable. And omfile only did so to do some no longer required legacy handling.

In essence, it is highly unlikely that you ever accessed this variable. So we expect that nobody actually notices that the variable has gone away.

Removal of the variable provides a slight performance gain, as we do no longer need to maintain it inside the output system (which leads to less CPU instructions and better cache hits).

RS_RET_SUSPENDED is no longer supported when creating an action instance

This means a plugin must not try to establish any connections or the like before any of its processing entry points (like beginTransaction or doAction) is called. This was generally also the case with v7, but was not enforced in all cases. In v8, creating action fails if anything but RS_RET_OK is returned.

string generator interface

Bottom line: string generators need to be changed or will abort.

The BEGINstrgen() entry point has greatly changed. Instead of two parameters for the output buffers, they now receive a single iparam pointer, which contains all data items needed. Also, the message pointer is now const to “prevent” (accidental) changes to the message via the strgen interface.

Note that strgen modules must now maintain the iparam->lenStr field, which must hold the length of the generated string on exit. This is necessary as we cache the string sizes in order to reduced strlen() calls. Also, the numerical parameters are now unsigned and no longer size_t. This permits us to store them directly into optimized heap structures.

Unsupported Command Line Options Removed

The command line options a, h, m, o, p, g, r, t and c were not supported since many versions. However, they spit out an error message that they were unsupported. This error message now no longer appears, instead the regular usage() display happens. This should not have any effect to users.

imfile changes

Starting with 8.5.0, imfile supports wildcards in file names, but does do so only in inotify mode. In order to support wildcards, the handling of statefile needed to be changed. Most importantly, the statefile input parameter has been deprecated. See imfile module documentation for more details.

Command Line Options

There is a small set of configuration command line options available dating back to the dark ages of syslog technology. Setting command-line options is distro specific and a hassle for most users. As such, we are phasing out these options, and will do so rather quickly.

Some of them (most notably -l, -s) will completely be removed, as feedback so far indicated they are no longer in use. Others will be replaced by proper configuration objects.

Expect future rsyslog versions to no longer accept those configuration command line options.

Please see this table to see what to use as a replacement for the current options:

Copyright 2008-2023 Rainer Gerhards (Großrinderfeld), and Others.