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
RainerScriptformat, 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 v8, there was a performance impact when using this format that encouraged use of the
basicformat 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
legacyformat, 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
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
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
basic format for basic configurations and the
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
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
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
Whatever you can do with the
obsolete legacy format, you can also do
advanced format. The opposite is not true: Many newer features
cannot be turned on via the
obsolete legacy format. The
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!).