path: root/rsyslog.conf.5

.\" rsyslog.conf - rsyslogd(8) configuration file
.\" Copyright 2003-2004 Rainer Gerhards and Adiscon GmbH.
.\" 
.\" This file is part of the rsyslog  package, an enhanced system log daemon.
.\" 
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.
.\"
.TH RSYSLOG.CONF 5 "2005-07-20" "Version 0.9" "Linux System Administration"
.SH NAME
rsyslog.conf \- rsyslogd(8) configuration file
.SH DESCRIPTION
The
.I rsyslog.conf
file is the main configuration file for the
.BR rsyslogd (8)
which logs system messages on *nix systems.  This file specifies rules
for logging.  For special features see the
.BR rsyslogd (8)
manpage.

While rsyslogd contains enhancements over standard syslogd, efforts
have been made to keep the configuration file as compatible as
possible. While, for obvious reasons, enhanced features require
a different config file syntax, rsyslogd should be able to work with
a standard syslog.conf file. This is especially useful while you
are migrating from syslogd to rsyslogd.

Every rule consists of two fields, a 
.I selector
field and an
.I action 
field.  These two fields are separated by one or more spaces or
tabs.  The selector field specifies a pattern of facilities and
priorities belonging to the specified action.

Lines starting with a hash mark (``#'') and empty lines are ignored.

.SH TEMPLATES
Templates are a key feature of rsyslog. They allow to specify any
format a user might want. Every output in rsyslog uses templates - this
holds true for files, user messages and so on. The database writer
expects its template to be a proper SQL statement - so this is highly
customizable too. You might ask how does all of this work when no templates
at all are specified. Good question ;) The answer is simple, though. Templates
compatible with the stock syslogd formats are hardcoded into rsyslog. So if
no template is specified, we use one of these hardcoded templates. Search for
"template_" in syslogd.c and you will find the hardcoded ones.

A template consists of a template directive, a name, the actual template text
and optional options. A sample is:

$template MyTemplateName,"\\7Text %property% some more text\\n",<options>

The "$template" is the template directive. It tells rsyslog that this
line contains a template.  "MyTemplateName" is the template name.
All other config lines refer to this name.

The text within quotes is the actual template text. The backslash is 
an escape character, much as it is in C. It does all these "cool" things. For
example, \\7 rings the bell (this is an ASCII value), \\n is a new line.
C programmers and perl coders have the advantage of knowing this, but the
set in rsyslog is a bit restricted currently.

All text in the template
is used literally, except for things within percent signs. These are 
properties and allow you access to the contents of the syslog message.
Properties are accessed via the property replacer (nice name, huh) and
it can do cool things, too. For example, it can pick a substring or
do date-specific formatting. More on this is below, on some lines of the
property replacer.

The <options> part is optional. It carries options influenceing the
template as whole. See details below. Be sure NOT to mistake template
options with property options - the later ones are processed by the
property replacer and apply to a SINGLE property, only (and not the
whole template).

Template options are case-insensitive. Currently defined are:
.nf
sql - format the string suitable for a SQL statement. This will replace
      single quotes ("'") by two single quotes ("''") inside each
      field. This option MUST be specified when a template is used for
      writing to a database, otherwise SQL injection might occur.
.fi

Please note that the database writer *checks* that the sql option is
present in the template. If it is not present, the write database action
is disabled. This is to guard you against accidential forgetting it and
then becoming vulnerable to SQL injection.
The sql option can also be useful with files - especially if you want
to import them into a database on another machine for performance reasons.
However, do NOT
use it if you do not have a real need for it - among others, it takes
some toll on the processing time. Not much, but on a really busy system
you might notice it ;)

.nf
To escape:
% = \\%
\\ = \\\\  --> '\\' is used to escape (as in C)
$template TraditionalFormat,%timegenerated% %HOSTNAME% %syslogtag%%msg%\\n"
.fi

Properties can be accessed by the property replacer. They are accessed
inside the template by putting them between percent signs. Properties
can be modifed by the property replacer. The full syntax is as follows:

%propname:fromChar:toChar:options%

propname is the name of the property to access. This IS case-sensitive!
Currently supported are:

.nf
msg             the MSG part of the message (aka "the message" ;))
rawmsg          the message excactly as it was received from the
                socket. Should be useful for debugging.
UxTradMsg       will disappear soon - do NOT use!
HOSTNAME        hostname from the message
source          alias for HOSTNAME
syslogtag       TAG from the message
PRI             PRI part of the message - undecoded (single value)
IUT             the monitorware InfoUnitType - used when talking
                to a MonitorWare backend (also for phpLogCon)
syslogfacility  the facility from the message - in numerical form
syslogpriority  the priority (actully severity!) from the
                message - in numerical form
timegenerated   timestamp when the message was RECEIVED. Always in
                high resolution
timereported    timestamp from the message. Resolution depends on
                what was provided in the message (in most cases,
                only seconds)
TIMESTAMP       alias for timereported
.fi

FromChar and toChar are used to build substrings. They specify the
offset within the string that should be copied. Offset counting
starts at 1, so if you need to obtain the first 2 characters of the
message text, you can use this syntax: "%msg:1:2%".
If you do not whish to specify from and to, but you want to
specify options, you still need to include the colons. For example,
if you would like to convert the full message text to lower case,
use "%msg:::lowercase%".

.nf
property options are case-insensitive, currently defined are:
uppercase      convert property to lowercase only
lowercase      convert property text to uppercase only
drop-last-lf   The last LF in the message (if any), is dropped. 
               Especially useful for PIX.
date-mysql     format as mysql date
date-rfc3164   format as RFC 3164 date
date-rfc3339   format as RFC 3339 date
escape-cc      NOT yet implemented
.fi

.SH Output Channels
.B Output Channels
are a new concept first introduced in rsyslog 0.9.0. As of this writing, it
is still unclear if they will stay in rsyslog or go away. So if you use
them, be prepared to change you configuration file syntax when you
upgrade to a later release.

The idea behind output channel definitions is that it shall provide an
umbrella for any type of output that the user might want. In essence, this
is the "file" part of selector lines (and this is why we are not sure
output channel syntax will stay after the next review). There is a difference,
though: selector channels both have filter conditions (currently facility and
severity) as well as the output destination. Output channels define the output
defintion, only. As of this build, they can only be used to write to files - not
pipes, ttys or whatever else. If we stick with output channels, this will change
over time.

In concept, an output channel includes everything needed to know about
an output actions. In practice, the current implementation only carries
a filename, a maximum file size and a command to be issued when this
file size is reached. More things might be present in future version, which
might also change the syntax of the directive.

Output channels are defined via an $outchannel directive. It's syntax is
as follows:

$outchannel name,file-name,max-size,action-on-max-size

name is the name of the output channel (not the file), file-name is
the file name to be written to, max-size the maximum allowed size
and action-on-max-size a command to be issued when the max size is reached.

Please note that max-size is queried BEFORE writing the log message to
the file. So be sure to set this limit reasonably low so that any message
might fit. For the current release, setting it 1k lower than you expected
is helpful. The max-size must always be specified in bytes - there are no
special symbols (like 1k, 1m,...) at this point of development.

Keep in mind that $outchannel just defines a channel with "name". It
does not activate it. To do so, you must use a selector line (see below).
That selector line includes the channel name plus an $ sign in front of
it. A sample might be:

*.* $mychannel

In its current form, output channels primarily provide the ability to
size-limit an output file. To do so, specify a maximum size. When this
size is reachead, rsyslogd will execute the action-on-max-size command
and then reopen the file and retry. The command should be something like
a log rotation script or a similar thing.

.B WARNING:

The current command logic is a quick hack. It simply issues the command
via a system() call, which is very dirty. Don't make rsyslogd a suid
binary and use action-on-max-size commands - this will mess up things.
Fixing this is on top of the todo list and the fix will hopefully
appear soon.

If there is no action-on-max-size command or the command did not resolve
the situation, the file is closed and never reopened by rsyslogd (except,
of course, by huping it). This logic was integrated when we first experienced
severe issues with files larger 2gb, which could lead to rsyslogd dumping
core. In such cases, it is more appropriate to stop writing to a single
file. Meanwhile, rsyslogd has been fixed to support files larger 2gb, but
obviously only on file systems and operating system versions that do so.
So it can still make sense to enforce a 2gb file size limit.

.SH SELECTORS
The selector field itself again consists of two parts, a
.I facility
and a 
.IR priority ,
separated by a period (``.'').
Both parts are case insensitive and can also be specified as decimal
numbers, but don't do that, you have been warned.  Both facilities and
priorities are described in 
.BR rsyslog (3).
The names mentioned below correspond to the similar 
.BR LOG_ -values
in
.IR /usr/include/rsyslog.h .

The
.I facility
is one of the following keywords:
.BR auth ", " authpriv ", " cron ", " daemon ", " kern ", " lpr ", "
.BR mail ", " mark ", " news ", " security " (same as " auth "), "
.BR rsyslog ", " user ", " uucp " and " local0 " through " local7 .
The keyword 
.B security
should not be used anymore and
.B mark
is only for internal use and therefore should not be used in
applications.  Anyway, you may want to specify and redirect these
messages here.  The
.I facility
specifies the subsystem that produced the message, i.e. all mail
programs log with the mail facility
.BR "" ( LOG_MAIL )
if they log using rsyslog.

Please note that the upcoming next syslog-RFC specifies many more
facilities. Support for them will be added in a future version of
rsyslog, which might require changes to existing configuration files.

The
.I priority
is one of the following keywords, in ascending order: 
.BR debug ", " info ", " notice ", " warning ", " warn " (same as "
.BR warning "), " err ", " error " (same as " err "), " crit ", "
.BR alert ", " emerg ", " panic " (same as " emerg ).
The keywords
.BR error ", " warn " and " panic
are deprecated and should not be used anymore.  The
.I priority
defines the severity of the message

The behavior of the original BSD syslogd is that all messages of the
specified priority and higher are logged according to the given
action.  This
.BR rsyslogd (8)
behaves the same, but has some extensions.

In addition to the above mentioned names the
.BR rsyslogd (8)
understands the following extensions: An asterisk (``*'') stands for
all facilities or all priorities, depending on where it is used
(before or after the period).  The keyword
.B none
stands for no priority of the given facility.

You can specify multiple facilities with the same priority pattern in
one statement using the comma (``,'') operator.  You may specify as
much facilities as you want.  Remember that only the facility part from
such a statement is taken, a priority part would be skipped.

Multiple selectors may be specified for a single
.I action
using the semicolon (``;'') separator.  Remember that each selector in
the 
.I selector
field is capable to overwrite the preceding ones.  Using this
behavior you can exclude some priorities from the pattern.

.BR Rsyslogd (8)
has a syntax extension to the original BSD source, that makes its use
more intuitively.  You may precede every priority with an equation sign
(``='') to specify only this single priority and not any of the
above.  You may also (both is valid, too) precede the priority with an
exclamation mark (``!'') to ignore all that priorities, either exact
this one or this and any higher priority.  If you use both extensions
than the exclamation mark must occur before the equation sign, just
use it intuitively.

.SH ACTIONS
The action field of a rule describes what to do with the message.
In general, message content is written to a kind of "logfile". But
also other actions might be done, like writing to a database table
or forwarding to another host.

Templates can be used with all actions. If used, the specified template
is used to generate the message content (instead of the default
template). To specify a template, write a semicolon after the action
value immediately followed by the template name.

.B Beware:
templates MUST be defined BEFORE they are used. It is OK to define
some templates, then use them in selector lines, define more templates
and use use them in the following selector lines. But it is NOT permitted
to use a template in a selectore line that is above its definition. If you
do this, the selector line will be ignored.

.SS Regular File
Typically messages are logged to real files.  The file has to be
specified with full pathname, beginning with a slash ``/''.

You may prefix each entry with the minus ``-'' sign to omit syncing
the file after every logging.  Note that you might lose information if
the system crashes right behind a write attempt.  Nevertheless this
might give you back some performance, especially if you run programs
that use logging in a very verbose manner.

If your system is connected to a reliable UPS and you receive lots of
log data (e.g. firewall logs), it might be a very good idea to turn
of syncing by specifying the "-" in front of the file name.

.SS Named Pipes
This version of
.BR rsyslogd (8)
has support for logging output  to
named pipes (fifos).  A fifo or named pipe can be used as
a destination for log messages by prepending a pipe symbol (``|'') to
the name of the file.  This is handy for debugging.  Note that the fifo
must be created with the  
.BR mkfifo (1)
command  before
.BR rsyslogd (8)
is started.

.SS Terminal and Console
If the file you specified is a tty, special tty-handling is done, same
with
.IR /dev/console .

.SS Remote Machine
.BR Rsyslogd (8)
provides full remote logging, i.e. is able to send messages to a
remote host running 
.BR rsyslogd (8)
and to receive messages from remote hosts.  The remote
host won't forward the message again, it will just log them
locally.  To forward messages to another host, prepend the hostname
with the at sign (``@'').

Using this feature you're able to control all syslog messages on one
host, if all other machines will log remotely to that.  This tears down
administration needs.

Please note that this version of rsyslogd by default does NOT forward messages
it has received from the network to another host. Specify the -h
option to enable this.

.SS List of Users
Usually critical messages are also directed to ``root'' on that
machine.  You can specify a list of users that shall get the message by
simply writing the login.  You may specify more than one user by
separating them with commas (``,'').  If they're logged in they
get the message.  Don't think a mail would be sent, that might be too
late.

.SS Everyone logged on
Emergency messages often go to all users currently online to notify
them that something strange is happening with the system.  To specify
this
.IR wall (1)-feature
use an asterisk (``*'').

.SS Database Table
This allows logging of the message to a database table. Currently, only
MySQL databases are supported. By default, a MonitorWare-compatible schema
is required for this to work. You can create that schema with the
createDB.SQL file that came with the rsyslog package. You can also
use any other schema of your liking - you just need to define a proper
template and assign this template to the action.

The database writer is called by specifying a greater-then sign (">")
in front of the database connect information. Immediately after that
sign the database host name must be given, a comma, the database name,
another comma, the database user, a comma and then the user's password.
If a specific template is to be used, a semicolong followed by the
template name can follow the connect information. This is as follows:

.nf
    >dbhost,dbname,dbuser,dbpassword;dbtemplate
.fi

.SS Output Channel
Binds an output channel definition (see there for details) to this action.
Output channel actions must start with a $-sign, e.g. if you would like
to bind your output channel definition "mychannel" to the action, use 
"$mychannel". Output channels support template definitions like all all other
actions.

.SH TEMPLATE NAME
Every ACTION can be followed by a template name. If so, that template is used
for message formatting. If no name is given, a hardcoded default template is
used for the action.
There can only be one template name for each given action.
The default template is specific to each action. For a 
description of what a template is and what you can do with it, see
"TEMPLATES" at the top of this document.

.SH EXAMPLES
Below are example for templates and selector lines. I hope they are
self-explanatory. If not, please see www.monitorware.com/rsyslog/ for
advise.
.SS TEMPLATES
Please note that
the samples are split across multiple lines. A template MUST NOT actually
be split across multiple lines.

A template that resambles traditional syslogd file output:
.br
.nf
$template TraditionalFormat,"%timegenerated% %HOSTNAME%
%syslogtag%%msg:::drop-last-lf%\\n"
.fi

A template that tells you a little more about the message:
.br
.nf
$template precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,
%syslogtag%,%msg%\\n"
.fi

A template for RFC 3164 format:
.br
.nf
$template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag%%msg%"
.fi

A template for the format traditonally used for user messages:
.br
.nf
$template usermsg," XXXX%syslogtag%%msg%\\n\\r"
.fi

And a template with the traditonal wall-message format:
.br
.nf
$template wallmsg,"\\r\\n\\7Message from syslogd@%HOSTNAME% at %timegenerated%
...\\r\\n %syslogtag%%msg%\\n\\r"
.fi

A template that can be used for the database write (please note the SQL template
option)
.br
.nf
$template MySQLInsert,"insert iut, message, receivedat values
('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')
into systemevents\\r\\n", SQL
.fi

The following template emulates winsyslog format (it's a Adiscon format, you 
do not feel bad if you don't know it ;)). It's interesting to see how it
takes different parts out of the date stamps. What happens is that the date
stamp is split into the actual date and time and the these two are combined
with just a comma in between them.

.nf
$template WinSyslogFmt,"%HOSTNAME%,%timegenerated:1:10:date-rfc3339%,
%timegenerated:12:19:date-rfc3339%,%timegenerated:1:10:date-rfc3339%,
%timegenerated:12:19:date-rfc3339%,%syslogfacility%,%syslogpriority%,
%syslogtag%%msg%\\n"
.fi

.SS SELECTOR LINES
.IP
.nf
# Store critical stuff in critical
#
*.=crit;kern.none            /var/adm/critical
.fi
.LP
This will store all messages with the priority
.B crit
in the file
.IR /var/adm/critical ,
except for any kernel message.

.IP
.nf
# Kernel messages are first, stored in the kernel
# file, critical messages and higher ones also go
# to another host and to the console. Messages to
# the host finlandia are forwarded in RFC 3164
# format (using the template defined above).
#
kern.*                       /var/adm/kernel
kern.crit                    @finlandia;RFC3164fmt
kern.crit                    /dev/console
kern.info;kern.!err          /var/adm/kernel-info
.fi
.LP
The first rule direct any message that has the kernel facility to the
file
.IR /var/adm/kernel .

The second statement directs all kernel messages of the priority
.B crit
and higher to the remote host finlandia.  This is useful, because if
the host crashes and the disks get irreparable errors you might not be
able to read the stored messages.  If they're on a remote host, too,
you still can try to find out the reason for the crash.

The third rule directs these messages to the actual console, so the
person who works on the machine will get them, too.

The fourth line tells the rsyslogd to save all kernel messages that
come with priorities from
.BR info " up to " warning
in the file
.IR /var/adm/kernel-info .
Everything from
.I err
and higher is excluded.

.IP
.nf
# The tcp wrapper loggs with mail.info, we display
# all the connections on tty12
#
mail.=info                   /dev/tty12
.fi
.LP
This directs all messages that uses 
.BR mail.info " (in source " LOG_MAIL " | " LOG_INFO )
to
.IR /dev/tty12 , 
the 12th console.  For example the tcpwrapper
.BR tcpd (8)
uses this as it's default.

.IP
.nf
# Store all mail concerning stuff in a file
#
mail.*;mail.!=info           /var/adm/mail
.fi
.LP
This pattern matches all messages that come with the
.B mail
facility, except for the
.B info
priority.  These will be stored in the file
.IR /var/adm/mail .

.IP
.nf
# Log all mail.info and news.info messages to info
#
mail,news.=info              /var/adm/info
.fi
.LP
This will extract all messages that come either with
.BR mail.info " or with " news.info 
and store them in the file
.IR /var/adm/info .

.IP
.nf
# Log info and notice messages to messages file
#
*.=info;*.=notice;\\
	mail.none  /var/log/messages
.fi
.LP
This lets
.B rsyslogd
log all messages that come with either the
.BR info " or the " notice
facility into the file
.IR /var/log/messages ,
except for all messages that use the
.B mail
facility.

.IP
.nf
# Log info messages to messages file
#
*.=info;\\
	mail,news.none       /var/log/messages
.fi
.LP
This statement causes
.B rsyslogd
to log all messages that come with the
.B info
priority to the file
.IR /var/log/messages .
But any message coming either with the
.BR mail " or the " news
facility will not be stored.

.IP
.nf
# Emergency messages will be displayed using wall
#
*.=emerg                     *
.fi
.LP
This rule tells the
.B rsyslogd
to write all emergency messages to all currently logged in users.  This
is the wall action.

.IP
.nf
# Messages of the priority alert will be directed
# to the operator
#
*.alert                      root,rgerhards
.fi
.LP
This rule directs all messages with a priority of
.B alert
or higher to the terminals of the operator, i.e. of the users ``root''
and ``rgerhards'' if they're logged in.

.IP
.nf
*.*                          @finlandia
.fi
.LP
This rule would redirect all messages to a remote host called
finlandia.  This is useful especially in a cluster of machines where
all syslog messages will be stored on only one machine.

In the format shown above, UDP is used for transmitting the message. The
destination port is set to the default auf 514. Rsyslog is also capable of
using much more secure and reliable TCP sessions for message forwarding.
Also, the destination port can be specified. To select TCP, simply
add one additional @ in front of the host name (that is, @host is UPD,
@@host is TCP). For example:

.IP
.nf
*.*                          @@finlandia
.fi
.LP
To specify the destination port on the remote machine, use a colon followed
by the port number after the machine name. The following forwards to port
1514 on finlandia:

.IP
.nf
*.*                          @@finlandia:1514
.fi
.LP
This syntax works both with TCP and UDP based syslog. However, you will
probably primarily need it for TCP, as there is no well-accepted port
for this transport (it is non-standard). For UDP, you can usually stick
with the default auf 514, but might want to modify it for security reasons.
If you would like to do that, it's quite easy:

.IP
.nf
*.*                          @finlandia:1514
.fi
.LP

.IP
.fi
*.*            >dbhost,dbname,dbuser,dbpassword;dbtemplate
.nf
.LP
This rule writes all message to the database "dbname" hosted on "dbhost".
The login is done with user "dbuser" and password "dbpassword". The
actual table that is updated is specified within the template (which
contains the insert statement). The template is called "dbtemplate" 
in this case.

.SH CONFIGURATION FILE SYNTAX DIFFERENCES
.B Rsyslogd
uses a slightly different syntax for its configuration file than
the original BSD sources.  Originally all messages of a specific priority
and above were forwarded to the log file.  The modifiers ``='', ``!''
and ``-'' were added to make
.B rsyslogd
more flexible and to use it in a more intuitive manner.

The original BSD rsyslogd doesn't understand spaces as separators between
the selector and the action field.

When compared to syslogd from sysklogd package,
.B rsyslogd
offers template support. For obvious reasons, the syntax for
template definitions is available in rsyslogd, only. The same
applies to the write database action.
.SH FILES
.PD 0
.TP
.I /etc/rsyslog.conf
Configuration file for
.B rsyslogd

.SH BUGS
The effects of multiple selectors are sometimes not intuitive.  For
example ``mail.crit,*.err'' will select ``mail'' facility messages at
the level of ``err'' or higher, not at the level of ``crit'' or
higher.

This is an early release. So be sure to check the file BUGS that came with
the package for all the fun it offers ;)
.SH SEE ALSO
.BR syslogd (8),
.BR logger (1),
.BR syslog (3)

.SH AUTHORS
The
.B rsyslogd
is taken from sysklogd sources, which have been heavily modified
by Rainer Gerhards (rgerhards@adiscon.com) and others.