# 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 preferable 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 specifying 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!).

See also

Help with configuring/using `Rsyslog`:

- Mailing list - best route for general questions

- GitHub: rsyslog source project - detailed questions, reporting issues that are believed to be bugs with `Rsyslog`

- Stack Exchange (View, Ask) - experimental support from rsyslog community

See also

Contributing to `Rsyslog`:

- Source project: rsyslog project README.

- Documentation: rsyslog-doc project README

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