path: root/rsyslog.conf.5

RSYSLOG.CONF(5)                    Linux System Administration                    RSYSLOG.CONF(5)

NAME
       rsyslog.conf - rsyslogd(8) configuration file

DESCRIPTION
       The rsyslog.conf file is the main configuration file for the rsyslogd(8) which logs system
       messages on *nix systems.  This file specifies rules for logging.   For  special  features
       see the 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 selector field and an 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.

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 tem-
       plate.  "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:
       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.

       Please note that the database writer *checks* that the sql option is present in  the  tem-
       plate.  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 data-
       base 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 ;)

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

       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  sup-
       ported are:

       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

       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  in-
       clude the colons. For example, if you would like to convert the full message text to lower
       case, use "%msg:::lowercase%".

       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

SELECTORS
       The selector field itself again consists of two parts, a facility and  a  priority,  sepa-
       rated  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  rsyslog(3).   The  names  mentioned  below  correspond  to the similar
       LOG_-values in /usr/include/rsyslog.h.

       The facility is one of the following keywords: auth, authpriv, cron,  daemon,  kern,  lpr,
       mail,  mark, news, security (same as auth), rsyslog, user, uucp and local0 through local7.
       The keyword security should not be used anymore and mark is  only  for  internal  use  and
       therefore  should  not be used in applications.  Anyway, you may want to specify and redi-
       rect these messages here.  The facility specifies the subsystem that produced the message,
       i.e. all mail programs log with the mail facility (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  priority  is  one of the following keywords, in ascending order: debug, info, notice,
       warning, warn (same as warning), err, error (same as err), crit, alert, emerg, panic (same
       as  emerg).  The keywords error, warn and panic are deprecated and should not be used any-
       more.  The 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 rsyslogd(8) behaves the same,
       but has some extensions.

       In addition to the above mentioned names the rsyslogd(8) understands the following  exten-
       sions: An asterisk (``*'') stands for all facilities or all priorities, depending on where
       it is used (before or after the period).  The keyword 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 action using the semicolon (``;'')  sepa-
       rator.  Remember that each selector in the selector field is capable to overwrite the pre-
       ceding ones.  Using this behavior you can exclude some priorities from the pattern.

       Rsyslogd(8) has a syntax extension to the original BSD source, that makes its use more in-
       tuitively.   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.

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 gener-
       ate 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.

       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.

   Regular File
       Typically messages are logged to real files.  The file has to be specified with full path-
       name, 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. fire-
       wall logs), it might be a very good idea to turn of syncing by specifying the "-" in front
       of the file name.

   Named Pipes
       This version of 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 sym-
       bol (``|'') to the name of the file.  This is handy for debugging.   Note  that  the  fifo
       must be created with the mkfifo(1) command  before rsyslogd(8) is started.

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

   Remote Machine
       Rsyslogd(8)  provides  full remote logging, i.e. is able to send messages to a remote host
       running rsyslogd(8) and to receive messages from remote hosts.  The remote host won't for-
       ward  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 rsyslog 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 does NOT forward messages it has received from
       the network to another host. So it can NOT work as a relay. If you need  this  functional-
       ity,  either  ask  rgerhards@adiscon.com or wait until it is configurable in the next ver-
       sion.

   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.

   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  wall(1)-feature  use  an  asterisk
       (``*'').

   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  tem-
       plate 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  tem-
       plate name can follow the connect information. This is as follows:

           >dbhost,dbname,dbuser,dbpassword;dbtemplate

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 spe-
       cific 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.

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.

   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:
       $template TraditionalFormat,"%timegenerated% %HOSTNAME%
       %syslogtag%%msg:::drop-last-lf%\n"

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

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

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

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

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

       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.

       $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"

   SELECTOR LINES
              # Store critical stuff in critical
              #
              *.=crit;kern.none            /var/adm/critical

       This will store all messages with the priority crit in the file /var/adm/critical,  except
       for any kernel message.

              # 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

       The  first  rule direct any message that has the kernel facility to the file /var/adm/ker-
       nel.

       The second statement directs all kernel messages of the priority crit and  higher  to  the
       remote  host finlandia.  This is useful, because if the host crashes and the disks get ir-
       reparable errors you might not be able to read the stored messages.  If they're on  a  re-
       mote 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  info up to warning in the file /var/adm/kernel-info.  Everything from err and higher
       is excluded.

              # The tcp wrapper loggs with mail.info, we display
              # all the connections on tty12
              #
              mail.=info                   /dev/tty12

       This directs all  messages  that  uses  mail.info  (in  source  LOG_MAIL  |  LOG_INFO)  to
       /dev/tty12,  the  12th  console.  For example the tcpwrapper tcpd(8) uses this as it's de-
       fault.

              # Store all mail concerning stuff in a file
              #
              mail.*;mail.!=info           /var/adm/mail

       This pattern matches all messages that come with the mail facility, except  for  the  info
       priority.  These will be stored in the file /var/adm/mail.

              # Log all mail.info and news.info messages to info
              #
              mail,news.=info              /var/adm/info

       This will extract all messages that come either with mail.info or with news.info and store
       them in the file /var/adm/info.

              # Log info and notice messages to messages file
              #
              *.=info;*.=notice;\
                   mail.none  /var/log/messages

       This lets rsyslogd log all messages that come with either the info or the notice  facility
       into the file /var/log/messages, except for all messages that use the mail facility.

              # Log info messages to messages file
              #
              *.=info;\
                   mail,news.none       /var/log/messages

       This statement causes rsyslogd to log all messages that come with the info priority to the
       file /var/log/messages.  But any message coming either with the mail or the news  facility
       will not be stored.

              # Emergency messages will be displayed using wall
              #
              *.=emerg                     *

       This  rule  tells  the rsyslogd to write all emergency messages to all currently logged in
       users.  This is the wall action.

              # Messages of the priority alert will be directed
              # to the operator
              #
              *.alert                      root,joey

       This rule directs all messages with a priority of alert or higher to the terminals of  the
       operator, i.e. of the users ``root'' and ``joey'' if they're logged in.

              *.*                          @finlandia

       This  rule  would redirect all messages to a remote host called finlandia.  This is useful
       especially in a cluster of machines where all rsyslog messages will be stored on only  one
       machine.

              *.*            >dbhost,dbname,dbuser,dbpassword;dbtemplate

       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.

CONFIGURATION FILE SYNTAX DIFFERENCES
       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 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, rsyslogd offers template support. For ob-
       vious reasons, the syntax for template definitions is available  in  rsyslogd,  only.  The
       same applies to the write database action.

FILES
       /etc/rsyslog.conf
              Configuration file for rsyslogd

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 ;)
SEE ALSO
       syslogd(8), logger(1), syslog(3)

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

Version 0.8                                 2005-03-17                            RSYSLOG.CONF(5)