Every output in rsyslog uses templates - this holds true for
files, user messages and so on. Templates compatible with the
stock syslogd formats are hardcoded into rsyslogd. 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. The backslash is an escape
character. For example, \7 rings the bell (this is an ASCII
value), \n is a new line. 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 and it can for example pick a substring
or do date-specific formatting. More on this is the PROPERTY
REPLACER section of this manpage.
To escape:
% = \%
\ = \\ --> '\' is used to escape (as in C)
$template TraditionalFormat,"%timegenerated% %HOSTNAME%
%syslogtag%%msg%\n"
Properties can be accessed by the property replacer (see there
for details).
Please note that templates can also by used to generate selector
lines with dynamic file names. For example, if you would like to
split syslog messages from different hosts to different files
(one per host), you can define the following template:
$template DynFile,"/var/log/system-%HOSTNAME%.log"
This template can then be used when defining an output selector
line. It will result in something like "/var/log/system-
localhost.log"
Template options
The <options> part is optional. It carries options influencing
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 in
MySQL format. This will replace single quotes ("'")
and the backslash character by their backslash-
escaped counterpart ("´" and "\") inside each
field. Please note that in MySQL configuration, the
NO_BACKSLASH_ESCAPES mode must be turned off for
this format to work (this is the default).
stdsql format the string suitable for a SQL statement that
is to be sent to a standards-compliant sql server.
This will replace single quotes ("'") by two single
quotes ("''") inside each field. You must use
stdsql together with MySQL if in MySQL
configuration the NO_BACKSLASH_ESCAPES is turned
on.
Either the sql or stdsql option MUST be specified when a template
is used for writing to a database, otherwise injection might
occur. Please note that due to the unfortunate fact that several
vendors have violated the sql standard and introduced their own
escape methods, it is impossible to have a single option doing
all the work. So you yourself must make sure you are using the
right format. If you choose the wrong one, you are still
vulnerable to sql injection.
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
accidental 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 ;)
The default template for the write to database action has the sql
option set.
Template examples
Please note that the samples are split across multiple lines. A
template MUST NOT actually be split across multiple lines.
A template that resembles 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 traditionally used for user messages:
$template usermsg," XXXX%syslogtag%%msg%\n\r"
And a template with the traditional wall-message format:
$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME%
at %timegenerated%"
A template that can be used for writing to a database (please
note the SQL template option)
$template MySQLInsert,"insert iut, message, receivedat
values ('%iut%', '%msg:::UPPERCASE%',
'%timegenerated:::date-mysql%') into systemevents\r\n",
SQL
NOTE 1: This template is embedded into core application
under name StdDBFmt , so you don't need to define it.
NOTE 2: You have to have MySQL module installed to use
this template.
