A Brief Tutorial on rsyslog.conf (Shallow Thoughts)

A Brief Tutorial on rsyslog.conf

Every now and then. I find myself puzzled by which Linux system messages are going to which files in /var/log. I vaguely knew it was all configurable via the syslog service, specifically the file /etc/rsyslog.conf (on some systems it's still/etc/syslog.conf) and the directory /etc/rsyslog.d.

But every time I started wading into that 822-line rsyslog.conf(5) man page I end up deciding "perhaps another time".

But when you have a problem at work and messages are being logged to the wrong place and filling up the disk, "another time" arrives.

If you're like most people, you don't need to know esoterica like how to use a plug-in to log in a special custom format to a named pipe; you just want to know how to change the file so you see the messages you want to see, or so you don't have the same messages being logged in three different places. The man page isn't good about separating the practical information everyone needs from the esoterica.

Strangely, there doesn't seem to be much in the way of simple rsyslog web tutorials, either. So now, I present to you:

rsyslog.conf(5): the "Good Parts" Version

First, remember that you don't need to create an /etc/rsyslog.conf from scratch. You just need to be able to read the existing one and modify it a little. So start with the file you already have.

MODULES section

rsyslog has tons of modules available. They're listed in the man page with no clue offered as to what they all do. Just leave that section alone and don't worry about it.

GLOBAL DIRECTIVES

You can probably leave that section alone too.

But if you need to configure something globally -- for instance, the user who will own the files in /var/log -- the rsyslog.conf man page actually isn't too bad in describing the various options.

rsyslog.d

On some systems, notably Ubuntu, most of the configuration happens in smaller files in rsyslog.d rather than in the main rsyslog.conf. What follows applies to those files as well as the main one.

Rules section

The rest of the file(s) comprise rules for what gets logged where.

Each rule includes a selector (what gets logged) and an action (where it will get logged). Each selector includes a facility (what type of message we're talking about) and a priority (how important it is). But a selector can have several facilities/priorities, which is what makes the file look so complicated.

Enough theory. Let's look at some practical examples. These examples are taken from a plug computer running Debian.

auth,authpriv.*                 /var/log/auth.log

Messages of type auth or authpriv (the facility), with any priority, get logged to the file /var/log/auth.log.

*.*;auth,authpriv.none          -/var/log/syslog

Any message type, with any priority, gets logged to /var/log/syslog; except for auth and authpriv messages (which is good since they're already being logged to auth.log). The special priority none prevents those messages from being logged even though they would have been included in the *.*.

What's that dash in front of the filename? It's not documented in the man page, but it turns out to mean "Don't sync after every write to the file". Except that rsyslogd won't sync anyway, unless you add a special directive in the Global Directives section. So for most people, a dash makes no difference one way or the other -- it will be ignored.

So why is it there in the file, especially since the man page doesn't even document it? I have no idea; probably no one from the various distros has audited these files for years.

daemon.*                        -/var/log/daemon.log

There are quite a few facilities n addition to auth and daemon. Here's the list: auth, authpriv, cron, daemon, kern, lpr, mail, news, syslog, user, uucp and local0 through local7. There are also a couple of deprecated ones: security (considered to be the same as auth) and mark (for internal use only).

Selector priorities

Priorities can be: debug, info, notice, warning, err, crit, alert, emerg; plus the deprecated warn, error and panic (treated as warning, err and emerg).

*.=debug;\
        auth,authpriv.none;\
        news.none;mail.none     -/var/log/debug

Normally, specifying a priority like debug means to log anything of that priority or higher. So specifying *.debug would log everything. Adding an equals sign, =debug, means log only debug messages but nothing higher. This rule also excludes auth, authpriv, news and mail messages even if they're debug.

*.=info;*.=notice;*.=warn;\
        auth,authpriv.none;\
        cron,daemon.none;\
        mail,news.none          -/var/log/messages

Yow! The familiar /var/log/messages sure has a complicated rule. It gets anything of priority info, notice, or warn, unless they're facility aurh, authpriv, cron, daemon, mail or news.

Note that this overlaps with some of the other rules. So you'll see a lot of the same messages showing up in messages and syslog (which you'll recall got *.*). That was what got me started down this road: all that duplicated logging on our space-limited plug computers.

daemon.*;mail.*;\
        news.err;\
        *.=debug;*.=info;\
        *.=notice;*.=warn       |/dev/xconsole

Notice that until now, the rules have logged only to filenames. Remember all the rest of that complicated man page, explaining all the other actions besides filenames? Here's the only one that typically comes up: there's a device called /dev/xconsole where you can direct errors, and then you can run the xconsole program (you might have to specify the file, xconsole -file /dev/xconsole) to see the output.

Applying this to specific messages

How do you figure out which messages have what facilities and priorities?

That's the tricky part. Mostly, you can't. You can guess, or look at the source code, or just change rules in rsyslog.conf and see what happens.

But with a little experimentation, this guide should help you configure your own syslog configuration file and get rid of all those redundant messages filling up your disk.

Good luck!