Converting older formats to advanced

Do not overdo conversion

Note: simple facility and severity based filters which trigger writing to files can actually be very well expressed in basic. So if you have something like:

mail.info   /var/log/maillog

We suggest you leave it as-is without conversion. Equally, in our opinion it is also fine to add new rules like the above. If you still want to convert, the line may look as follows (completely in new format):

if prifilt("mail.info") then {
     action(type="omfile" file="/var/log/maillog")
}

More compact, this can also be written like:

if prifilt("mail.info") then action(type="omfile" file="/var/log/maillog")

The older-selector-style filter is well-known, so this may also write it as:

mail.info action(type="omfile" file="/var/log/maillog")

There are ample additional possibilities. We suggest to keep things consistent.

Converting Module Load

This is very straight-forward. In obsolete legacy format we use:

$ModLoad module-name

This is very simply converted to:

module(load="module-name")

Sometimes modules provide global settings. In obsolete legacy format these are given in individual lines after the $ModLoad. In advanced format they are given inside the module object. This makes it much clearer which module they belong to and that they actually are global parameters (in contrast to per-action or per-listener parameters). A typical example is imtcp:

$ModLoad imtcp
$InputTCPMaxSession 500

This is converted to:

module(load="imtcp" maxSessions="500")

Note: in obsolete legacy format it is possible to provide global parameters more than once. In this case it is unclear which one actually applies. For example:

$ModLoad imtcp
$InputTCPMaxSession 500
...
*.* /var/log/messages
...
$InputTCPMaxSession 200

This is especially problematic if module-global parameters are used multiple times in include files.

In advanced format this is no longer possible. Module-global parameters can only be applied once when the module is loaded. Any attempt to change them afterwards results in an error message and will be ignored. The error messages will help you find and fix multiple settings. Let us assume “200” is the setting actually intended in above config snippet. So it would be converted to:

module(load="imtcp" maxSessions="200")
...
*.* /var/log/messages
...

Converting Actions

In general, you have lines like:

filter action

where filter is any of the filters and action is … the action to be carried out. As could be seen above, the filter does not necessarily need to be changed in order to convert the action. All filters also work with all config formats. It often is best to keep existing filters, at least while working on the conversion (do not change too many things at once).

The following table lists traditional action syntax and how it can be converted to new-style action() objects. The link will bring you to detail documentation. In these detail documentations all parameters are given. It is also specified which obsolete legacy directives map to advanced properties. This table is not conclusive but covers the most commonly used actions.

Some concrete examples:

OLD: :hostname, contains, "remote-sender" @@central
NEW: :hostname, contains, "remote-sender" action(type="omfwd" target="central" protocol="tcp")

OLD: if $msg contains "error" then @central
NEW: if $msg contains "error" then action(type="omfwd" target="central" protocol="udp")

OLD: *.emerg :omusrmsg:*
NEW: *.emerg action(type="omusrmsg" users="*")

NOTE: Some actions do not have a basic format configuration line. They may only be called via the action() syntax. Similarly, some very few actions, mostly contributed, do not support action() syntax and thus can only be configured via basic and obsolete legacy. See module doc for details.

Action with Multiple Parameters

In many cases, actions have additional parameters, which also need to be converted. In obsolete legacy format the action parameters are given before the actual action call. To convert such constructs, you need to map all obsolete legacy parameters to advanced ones. To look these up, you need to turn to three different documentation pages:

• the action object itself

• the output module that is called in the action (e.g. omfwd)

• the queue documentation (if an action queue is used)

To find the parameter in question, you can other do an on-page search via the browser on these pages. Often it is very convenient to just use the rsyslog doc search engine: Type the obsolete legacy format statement into the search box. Most often, one of the first search results is the matching object description doc page.

Converting Action Chains

Actions can be chained via the ampersand character (’&’). In advanced format this has been replaced by blocks. For example:

*.error /var/log/errorlog
&       @remote

becomes:

*.error {
        action(type="omfile" file="/var/log/errorlog")
        action(type="omfwd" target="remote" protocol="udp")
}

The latter is much easier to understand and less error-prone when extended.

A common construct is to send messages to a remote host based on some message content and then not further process it. This involves the stop statement (or it’s very old-time equivalent tilde (’~’). It may be specified as such:

:msg, contains, "error" @remote
& ~

which is equavalent to:

:msg, contains, "error" @remote
& stop

This format is often found in more modern distro’s rsyslog.conf. It again is fully equivalent to:

:msg, contains, "error" {
        action(type="omfwd" target="remote" protocol="udp")
        stop
}

And, just to prove the point, this is also exactly the same like:

if $msg contains "error" then {
        action(type="omfwd" target="remote" protocol="udp")
        stop
}

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