Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

25.3.3. Templates

Any output that is generated by rsyslog can be modified and formatted according to your needs with the use of templates. To create a template use the following syntax in /etc/rsyslog.conf: 
$template TEMPLATE_NAME,"text %PROPERTY% more text", [OPTION]
where:
  • $template is the template directive that indicates that the text following it, defines a template.
  • TEMPLATE_NAME is the name of the template. Use this name to refer to the template.
  • Anything between the two quotation marks ("…") is the actual template text. Within this text, special characters, such as \n for new line or \r for carriage return, can be used. Other characters, such as % or ", have to be escaped if you want to use those characters literally.
  • The text specified between two percent signs (%) specifies a property that allows you to access specific contents of a syslog message. For more information on properties, see the section called “Properties”.
  • The OPTION attribute specifies any options that modify the template functionality. The currently supported template options are sql and stdsql, which are used for formatting the text as an SQL query.

    Note

    Note that the database writer checks whether the sql or stdsql options are specified in the template. If they are not, the database writer does not perform any action. This is to prevent any possible security threats, such as SQL injection.
    See section Storing syslog messages in a database in Section 25.3.2, “Actions” for more information.

Generating Dynamic File Names

Templates can be used to generate dynamic file names. By specifying a property as a part of the file path, a new file will be created for each unique property, which is a convenient way to classify syslog messages.
For example, use the timegenerated property, which extracts a time stamp from the message, to generate a unique file name for each syslog message: 
$template DynamicFile,"/var/log/test_logs/%timegenerated%-test.log"
Keep in mind that the $template directive only specifies the template. You must use it inside a rule for it to take effect. In /etc/rsyslog.conf, use the question mark (?) in an action definition to mark the dynamic file name template: 
*.* ?DynamicFile

Properties

Properties defined inside a template (between two percent signs (%)) enable access various contents of a syslog message through the use of a property replacer. To define a property inside a template (between the two quotation marks ("…")), use the following syntax: 
%PROPERTY_NAME[:FROM_CHAR:TO_CHAR:OPTION]%
where:
  • The PROPERTY_NAME attribute specifies the name of a property. A list of all available properties and their detailed description can be found in the rsyslog.conf(5) manual page under the section Available Properties.
  • FROM_CHAR and TO_CHAR attributes denote a range of characters that the specified property will act upon. Alternatively, regular expressions can be used to specify a range of characters. To do so, set the letter R as the FROM_CHAR attribute and specify your desired regular expression as the TO_CHAR attribute.
  • The OPTION attribute specifies any property options, such as the lowercase option to convert the input to lowercase. A list of all available property options and their detailed description can be found in the rsyslog.conf(5) manual page under the section Property Options.
The following are some examples of simple properties:
  • The following property obtains the whole message text of a syslog message: 
    %msg%
  • The following property obtains the first two characters of the message text of a syslog message: 
    %msg:1:2%
  • The following property obtains the whole message text of a syslog message and drops its last line feed character: 
    %msg:::drop-last-lf%
  • The following property obtains the first 10 characters of the time stamp that is generated when the syslog message is received and formats it according to the RFC 3999 date standard. 
    %timegenerated:1:10:date-rfc3339%

Template Examples

This section presents a few examples of rsyslog templates.
Example 25.8, “A verbose syslog message template” shows a template that formats a syslog message so that it outputs the message's severity, facility, the time stamp of when the message was received, the host name, the message tag, the message text, and ends with a new line.

Example 25.8. A verbose syslog message template

$template verbose, "%syslogseverity%, %syslogfacility%, %timegenerated%, %HOSTNAME%, %syslogtag%, %msg%\n"
Example 25.9, “A wall message template” shows a template that resembles a traditional wall message (a message that is send to every user that is logged in and has their mesg(1) permission set to yes). This template outputs the message text, along with a host name, message tag and a time stamp, on a new line (using \r and \n) and rings the bell (using \7).

Example 25.9. A wall message template

$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME% at %timegenerated% ...\r\n %syslogtag% %msg%\n\r"
Example 25.10, “A database formatted message template” shows a template that formats a syslog message so that it can be used as a database query. Notice the use of the sql option at the end of the template specified as the template option. It tells the database writer to format the message as an MySQL SQL query.

Example 25.10. A database formatted message template

$template dbFormat,"insert into SystemEvents (Message, Facility, FromHost, Priority, DeviceReportedTime, ReceivedAt, InfoUnitID, SysLogTag) values ('%msg%', %syslogfacility%, '%HOSTNAME%', %syslogpriority%, '%timereported:::date-mysql%', '%timegenerated:::date-mysql%', %iut%, '%syslogtag%')", sql
rsyslog also contains a set of predefined templates identified by the RSYSLOG_ prefix. These are reserved for the syslog's use and it is advisable to not create a template using this prefix to avoid conflicts. The following list shows these predefined templates along with their definitions.
RSYSLOG_DebugFormat
A special format used for troubleshooting property problems. 
"Debug line with all properties:\nFROMHOST: '%FROMHOST%', fromhost-ip: '%fromhost-ip%', HOSTNAME: '%HOSTNAME%', PRI: %PRI%,\nsyslogtag '%syslogtag%', programname: '%programname%', APP-NAME: '%APP-NAME%', PROCID: '%PROCID%', MSGID: '%MSGID%',\nTIMESTAMP: '%TIMESTAMP%', STRUCTURED-DATA: '%STRUCTURED-DATA%',\nmsg: '%msg%'\nescaped msg: '%msg:::drop-cc%'\nrawmsg: '%rawmsg%'\n\n\"
RSYSLOG_SyslogProtocol23Format
The format specified in IETF's internet-draft ietf-syslog-protocol-23, which is assumed to become the new syslog standard RFC. 
"%PRI%1 %TIMESTAMP:::date-rfc3339% %HOSTNAME% %APP-NAME% %PROCID% %MSGID% %STRUCTURED-DATA% %msg%\n\"
RSYSLOG_FileFormat
A modern-style logfile format similar to TraditionalFileFormat, but with high-precision time stamps and time zone information. 
"%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n\"
RSYSLOG_TraditionalFileFormat
The older default log file format with low-precision time stamps. 
"%TIMESTAMP% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n\"
RSYSLOG_ForwardFormat
A forwarding format with high-precision time stamps and time zone information. 
"%PRI%%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag:1:32%%msg:::sp-if-no-1st-sp%%msg%\"
RSYSLOG_TraditionalForwardFormat
The traditional forwarding format with low-precision time stamps. 
"%PRI%%TIMESTAMP% %HOSTNAME% %syslogtag:1:32%%msg:::sp-if-no-1st-sp%%msg%\"