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

Output Channels
       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 pre-
       pared 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  re-
       view).  There is a difference, though: selector channels both have filter conditions (cur-
       rently 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 fu-
       ture 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 is-
       sued 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 re-
       lease, setting it 1k lower than you expected is helpful. The max-size must always be spec-
       ified  in bytes - there are no special symbols (like 1k, 1m,...) at this point of develop-
       ment.

       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 chan-
       nel 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.

       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  ob-
       viously  only  on  file systems and operating system versions that do so.  So it can still
       make sense to enforce a 2gb file size limit.

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 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 re-
       ceived from the network to another host. Specify the -h option to enable this.

   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

   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 defi-
       nition "mychannel" to the action, use "$mychannel". Output channels support template defi-
       nitions like all all other actions.

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,rgerhards

       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 ``rgerhards'' 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 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 reli-
       able 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:

              *.*                          @@finlandia

       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:

              *.*                          @@finlandia:1514

       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-stan-
       dard).  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:

              *.*                          @finlandia:1514

              *.*            >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.9                                 2005-07-20                            RSYSLOG.CONF(5)