Configuration Formats¶

Rsyslog has evolved over several decades. For this reason it supports three different configuration formats (“languages”):

basic - previously known as the sysklogd format, this is the format best used to express basic things, such as where the statement fits on a single line. It stems back to the original syslog.conf format, in use now for several decades.

The most common use case is matching on facility/severity and writing matching messages to a log file.
advanced - previously known as the RainerScript format, this format was first available in rsyslog v6 and is the current, best and most precise format for non-trivial use cases where more than one line is needed.

Prior to v7, there was a performance impact when using this format that encouraged use of the basic format for best results. Current versions of rsyslog do not suffer from this (historical) performance impact.

This new style format is specifically targeted towards more advanced use cases like forwarding to remote hosts that might be partially offline.
obsolete legacy - previously known simply as the legacy format, this format is exactly what its name implies: it is obsolete and should not be used when writing new configurations. It was created in the early days (up to rsyslog version 5) where we expected that rsyslog would extend sysklogd just mildly. Consequently, it was primarily aimed at small additions to the original sysklogd format. Practice has shown that it was notoriously hard to use for more advanced use cases, and thus we replaced it with the advanced format.

In essence, everything that needs to be written on a single line that starts with a dollar sign is legacy format. Users of this format are encouraged to migrate to the basic or advanced formats.

Which Format should I Use?¶

While rsyslog supports all three formats concurrently, you are strongly encouraged to avoid using the obsolete legacy format. Instead, you should use the basic format for basic configurations and the advanced format for anything else.

While it is an older format, the basic format is still suggested for configurations that mostly consist of simple statements. The classic example is writing to files (or forwarding) via priority. In basic format, this looks like:

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

This is hard to beat in simplicity, still being taught in courses and a lot of people know this syntax. It is perfectly fine to use these constructs even in newly written config files. Note that many distributions use this format in their default rsyslog.conf, so you will likely find it in existing configurations.

For anything more advanced, use the advanced format. Advantages are:

fine control over rsyslog operations via advanced parameters
easy to follow block structure
easy to write
safe for use with include files

To continue with the above example, the advanced format is preferrable if you want to make sure that an offline remote destination will not slow down local log file writing. In that case, forwarding is done via:

mail.err action(type="omfwd" protocol="tcp" queue.type="linkedList")

As can be seen by this example, the advanced format permits specifing additional parameters to fine tune the behavior, whereas the basic format does not provide this level of control.

Do not use obsolete legacy format. It will make your life miserable. It is primarily supported in order to not break existing configurations.

Whatever you can do with the obsolete legacy format, you can also do with the advanced format. The opposite is not true: Many newer features cannot be turned on via the obsolete legacy format. The obsolete legacy format is hard to understand and hard to get right. As you may inherit a rsyslog configuration that makes use of it, this documentation gives you some clues of what the obsolete statements do. For full details, obtain a v5 version of the rsyslog documentation (yes, this format is dead since 2010!).

Configuration Formats¶

Which Format should I Use?¶

Table Of Contents

Previous topic

Next topic

This Page