summaryrefslogtreecommitdiffstats
path: root/doc/rsyslog_conf_templates.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rsyslog_conf_templates.html')
-rw-r--r--doc/rsyslog_conf_templates.html497
1 files changed, 396 insertions, 101 deletions
diff --git a/doc/rsyslog_conf_templates.html b/doc/rsyslog_conf_templates.html
index b97f6609..0c189100 100644
--- a/doc/rsyslog_conf_templates.html
+++ b/doc/rsyslog_conf_templates.html
@@ -3,7 +3,7 @@
<body>
<p>This is a part of the rsyslog.conf - documentation.</p>
<a href="rsyslog_conf.html">back</a>
-<h2>Templates</h2>
+<h1>Templates</h1>
<p>Templates are a key feature of rsyslog. They allow to specify
any
format a user might want. They are also used for dynamic file name
@@ -16,67 +16,200 @@ compatible with the stock syslogd formats are hardcoded into rsyslogd.
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.</p>
-<p>Starting with 5.5.6, there are actually two differnt types of template:
+<p>Templates are specified by template() statements. They can also be specified
+via $Template legacy statements. Note that these are scheduled for removal in
+later versions of rsyslog, so it is probably a good idea to avoid them
+for new uses.
+<h2>The template() statement</h2>
+<p>The template() statement is used to define templates. Note that it is a
+<b>static</b> statement, that means all templates are defined when rsyslog
+reads the config file. As such, templates are not affected by if-statements
+or config nesting.
+<p>The basic structure of the template statement is as follows:
+<br><br>
+<code>template(parameters)</code>
+<br><br>
+In addition to this simpler syntax, list templates (to be described below)
+support an extended syntax:
+<br><br>
+<code>template(parameters) { list-descriptions }</code>
+<p>Each template has a parameter <b>name</b>, which specifies the templates
+name, and a parameter <b>type</b>, which specifies the template type. The name
+parameter must be unique, and behaviour is unpredictable if it is not. The <b>type</b>
+parameter specifies different template types. Different types simply enable
+different ways to specify the template content. The template type <b>does not</b>
+affect what an (output) plugin can do with it. So use the type that best fits your
+needs (from a config writing point of view!). The following types are available:
<ul>
-<li>string based
-<li>string-generator module based
+<li>list
+<li>subtree
+<li>string
+<li>plugin
</ul>
-<p><a href="rsyslog_conf_modules.html#sm">String-generator module</a> based templates
-have been introduced in 5.5.6. They permit a string generator, actually a C "program",
-the generate a format. Obviously, it is more work required to code such a generator,
-but the reward is speed improvement. If you do not need the ultimate throughput, you
-can forget about string generators (so most people never need to know what they are).
-You may just be interested in learning that for the most important default formats,
-rsyslog already contains highly optimized string generators and these are called
-without any need to configure anything. But if you have written (or purchased) a
-string generator module, you need to know how to call it. Each such module has a name,
-which you need to know (look it up in the module doc or ask the developer). Let's assume
-that "mystrgen" is the module name. Then you can define a template for that strgen
-in the following way:
+The various types are described below.
-<blockquote><code>template(name="MyTemplateName" type="plugin" string="mystrgen")</code></blockquote>
-<p>Legacy example:</p>
-<blockquote><code>$template MyTemplateName,=mystrgen</code></blockquote>
-(Of course, you must have first loaded the module via $ModLoad).
-<p>The important part is the equal sign in the legacy format: it tells the rsyslog config parser that
-no string follows but a strgen module name.
-<p>There are no additional parameters but the module name supported. This is because
-there is no way to customize anything inside such a "template" other than by
-modifying the code of the string generator.
+<h3>list</h3>
+<p>In this case, the template is generated by a list of constant and
+variable statements. These follow the template spec in curly braces. This type is
+also primarily meant for use with structure-aware outputs, like ommongodb. However,
+it also works perfectly with text-based outputs. We recommend to use this mode
+if more complex property substitutions needs to be done. In that case, the list-based
+template syntax is much clearer than the simple string-based one.
+<p>The list template contains the template header (with <b>type="list"</b>) and is followed
+by <b>constant</b> and <b>property</b> statements, given in curly braces to signify
+the template statement they belong to. As the name says, <b>constant</b> statements
+describe constant text and <b>property</b> describes property access. There are many options
+to <b>property</b>, described further below. Most of these options are used to extract
+only partial property contents or to modify the text obtained (like to change its case
+to upper or lower case, only).
+<p>To grasp the idea, an actual sample is:
+<br><pre><code>template(name="tpl1" type="list") {
+ constant(value="Syslog MSG is: '")
+ property(name="msg")
+ constant(value="', ")
+ property(name="timereported" dateFormat="rfc3339" caseConversion="lower")
+ constant(value="\n")
+ }
+</code></pre>
+<br>This sample is probably primarily targeted at the usual file-based output.</p>
-<p>So for most use cases, string-generator module based templates are <b>not</b>
-the route to take. Usually, we use <b>string based templates</b> instead.
-This is what the rest of the documentation now talks about.
-<p>A template consists of a template directive, a name, the
-actual template text and optional options. A sample is:</p>
-<blockquote><code>template(name="MyTemplateName" type="string" string="Example: Text %property% some more text\n" options)</code></blockquote>
-<p>Legacy example:</p>
-<blockquote><code>$template MyTemplateName,"\7Text
-%property% some more text\n",&lt;options&gt;</code></blockquote>
-<p>The "template" (legacy: $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 "string" 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.
-</p>
-<p>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
-<a href="property_replacer.html">property replacer</a>
-(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.<br>
-<br>
+<h4>constant statement</h4>
+<p>This provides a way to specify constant text. The text is used literally. It is
+primarily intended for text-based output, so that some constant text can be included. For
+example, if a complex template is build for file output, one usually needs to finish it
+by a newline, which can be introduced by a constant statement. Here is an actual sample
+of that use case from the rsylsog testbench:
+<br><pre><code>template(name="outfmt" type="list") {
+ property(name="$!usr!msgnum")
+ constant(value="\n")
+}</code></pre>
+The following escape sequences are recogniced inside the constant text:
+<ul>
+<li>\\ - single backslash
+<li>\n - LF
+<li>\ooo - (three octal digits) - represents character with this numerical value (e.g. \101
+equals "A"). Note that three
+octal digits must be given (in contrast to some languagues, where between one and three are valid).
+While we support octal notation, we recommend to use hex notation as this is better known.
+<li>\xhh - (where h is a hex digit) - represents character with this numerical value (e.g. \x41
+equals "A"). Note that two hexadecimal digits must be given (in contrast to some languagues
+where one or two are valid).
+<li>... some others ... list needs to be extended
+</ul>
+<p>Note: if an unsupported character follows a backslash, this is treated as an error. Behaviour
+is unpredictable in this case.
+<p>To aid usage of the same template both for text-based outputs and structured ones, constant
+text without an "outname" parameter will be ignored when creating the name/value tree
+for structured outputs. So if you want to supply some constant text e.g. to mongodb, you must
+include an outname, as can be seen here:
+<br><pre><code>template(name="outfmt" type="list") {
+ property(name="$!usr!msgnum")
+ constant(value="\n" <b>outname="IWantThisInMyDB"</b>)
+}</code></pre>
+
+The "constant" statement supports the following parameters:
+<ul>
+<li>value - the constant value to use
+<li>outname - output field name (for structured outputs)
+</ul>
+
+
+<h4>property statement</h4>
+<p>This statement is used to include property text. It can access all properties. Also,
+options permit to specify picking only part of a property or modifying it.
+It supports the following parameters:
+<ul>
+<li>name - the name of the property to access
+<li>outname - output field name (for structured outputs)
+<li>dateformat - date format to use (only for date-related properties)
+<li>caseconversion - permits to convert case of the text. supported values are
+"lower" and "upper"
+<li>controlcharacters - specifies how to handle control characters. Supported values are
+"escape", which escapes them, "space", which replaces them by a single space, and
+"drop", which simply removes them from the string.
+<li>securepath - used for creating pathnames suitable for use in dynafile templates
+<li>format - specifiy format on a field basis. Supported values are "csv", for use when
+csv-data is generated, "json", which formats proper json content (but without a field
+header) and "jsonf", which formats as a complete json field.
+<li>position.from - obtain substring starting from this position (1 is the first position)
+<li>position.to - obtain substring up to this position
+<li>field.number - obtain this field match
+<li>field.delimiter - decimal value of delimiter character for field extraction
+<li>regex.expression - expression to use
+<li>regex.type - either ERE or BRE
+<li>regex.nomatchmode - what to do if we have no match
+<li>regex.match - match to use
+<li>regex.submatch - submatch to use
+<li>droplastlf - drop a trailing LF, if it is present
+<li>mandatory - signifies a field as mandatory. If set to "on", this field will always
+be present in data passed to structured outputs, even if it is empty. If "off" (the default)
+empty fields will not be passed to structured outputs. This is especially useful for outputs
+that support dynamic schemas (like ommongodb).
+<li>spifno1stsp - expert options for RFC3164 template processing
+</ul>
+
+
+<h3>subtree</h3>
+<p>Available since rsyslog 7.1.4
+<p>
+In this case, the template is generated based on a complete
+(CEE) subtree. This type of template is most useful for outputs that know how to
+process hierarchical structure, like ommongodb. With that type, the parameter
+<b>subtree</b> must be specified, which tells which subtree to use. For example
+template(name="tpl1" type="subtree" subtree="$!") includes all CEE data, while
+template(name="tpl2" type="subtree" subtree="$!usr!tpl2") includes only the
+subtree starting at $!usr!tpl2. The core idea when using this type of template
+is that the actual data is prefabricated via set and unset script statements,
+and the resulting strucuture is then used inside the template. This method MUST
+be used if a complete subtree needs to be placed <i>directly</i> into the
+object's root. With all other template types, only subcontainers can be generated.
+Note that subtree type can also be used with text-based outputs, like omfile. HOWEVER,
+you do not have any capability to specify constant text, and as such cannot include
+line breaks. As a consequence, using this template type for text outputs is usually
+only useful for debugging or very special cases (e.g. where the text is interpreted
+by a JSON parser later on).
+<h4>Use case</h4>
+<p>A typical use case is to first create a custom subtree and then include it into
+the template, like in this small example:
+<br><blockquote><code>set $!usr!tpl2!msg = $msg;
+<br>set $!usr!tpl2!dataflow = field($msg, 58, 2);
+<br>template(name="tpl2" type="subtree" subtree="$!usr!tpl2")
+</code></blockquote>
+<p>Here, we assume that $msg contains various fields, and the data from a field
+is to be extracted and stored - together with the message - as field content.
+<h3>string</h3>
+<p>This closely resembles the legacy template statement. It
+has a mandatory parameter <b>string</b>, which holds the template string to be
+applied. A template string is a mix of constant text and replacement variables
+(see property replacer). These variables are taken from message or other dynamic
+content when the final string to be passed to a plugin is generated. String-based
+templates are a great way to specify textual content, especially if no complex
+manipulation to properties is necessary. Full details on how to specify template
+text can be found below.
+<br>Config example:
+<br><blockquote><code>template(name="tpl3" type="string" string="%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n")
+</code></blockquote>
+<h3>plugin</h3>
+In this case, the template is generated by a plugin (which
+is then called
+a "strgen" or "string generator"). The format is fix as it is coded. While this
+is inflexible, it provides superior performance, and is often used for that
+reason (not that "regular" templates are slow - but in very demanding environments
+that "last bit" can make a difference). Refer to the plugin's documentation
+for further details. For this type, the paramter <b>plugin</b> must be specified and
+must contain the name of the plugin as it identifies itself. Note that the
+plugin must be loaded prior to being used inside a template.
+<br>Config example:
+<br><blockquote><code>template(name="tpl4" type="plugin" plugin="mystrgen")
+</code></blockquote>
+
+<h3>options</h3>
The &lt;options&gt; 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 latter ones are
-processed by the property replacer and apply to a SINGLE property, only
-(and not the whole template).<br>
+influencing the template as whole and is part of the template parameters.
+See details below. Be sure NOT to mistake template options with property
+options - the latter ones are processed by the property replacer and
+apply to a SINGLE property, only (and not the whole template).<br>
<br>
Template options are case-insensitive. Currently defined are: </p>
<p><b>option.sql</b> - format the string suitable for a SQL
@@ -127,50 +260,102 @@ option. Otherwise you will become vulnerable to SQL injection. <br>
To escape:<br>
% = \%<br>
\ = \\ --&gt; '\' is used to escape (as in C)<br>
-$template TraditionalFormat,"%timegenerated% %HOSTNAME% %syslogtag%%msg%\n"<br>
+template (name="TraditionalFormat" type="string" string="%timegenerated% %HOSTNAME% %syslogtag%%msg%\n"<br>
<br>
-Properties can be accessed by the <a href="property_replacer.html">property
-replacer</a> (see there for details).</p>
-<p>Templates can be used in the form of a <b>list</b> as well. This has been
-introduced with <b>6.5.0</b> The list consists of two parts which are either
-a <b>constant</b> or a <b>property</b>. The constants
-are taking the part of "text" that you usually enter in string-based templates.
-The properties stay variable, as they are a substitute for different values of a
-certain type. This type of template is extremely useful for complicated cases,
-as it helps you to easily keep an overview over the template. Though, it has
-the disadvantage of needing more effort to create it.</p>
-<br>Config example:
-<br><blockquote><code>template(name="MyTemplate" type="list" option.json="off") {
- <br>constant(value="Test: ")
- <br>property(name="msg" outname="mymessage")
- <br>constant(value=" --!!!-- ")
- <br>property(name="timereported" dateFormat="rfc3339" caseConversion="lower")
- <br>constant(value="\n")
- <br>}
-</code></blockquote>
-<p>First, the general template option will be defined. The values of the template
-itself get defined in the curly brackets. As it can be seen, we have constants
-and properties in exchange. Whereas constants will be filled with a value and probably
-some options, properties do direct to a property and the options that could be needed
-additional format definitions.</p>
-<p>We suggest to use separate lines for all constants and properties. This
-helps to keep a good overview over the different parts of the template.
-Though, writing it in a single line will work, it is much harder to debug
-if anything goes wrong with the template. </p>
+<h3>Examples</h3>
+<h4>Standard Template for Writing to Files</h4>
+<p><pre><code>template(name="FileFormat" type="list") {
+ property(name="timestamp" dateFormat="rfc3339")
+ constant(value=" ")
+ property(name="hostname")
+ constant(value=" ")
+ property(name="syslogtag")
+ constant(value=" ")
+ property(name="msg" spifno1stsp="on" )
+ property(name="msg" droplastlf="on" )
+ constant(value="\n")
+ }
+</code></pre>
+<p>The equivalent string template looks like this:
+<br><pre><code>template(name="FileFormat" type="string"
+ string= "%TIMESTAMP% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n"
+)</code></pre>
+Note that the template string itself must be on a single line.
-<p><b>Please note that templates can also be
-used to generate selector lines with dynamic file names.</b> 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:</p>
-<blockquote><code>template (name="DynFile" type="string" string="/var/log/system-%HOSTNAME%.log")</code></blockquote>
-<p>Legacy example:</p>
-<blockquote><code>$template
-DynFile,"/var/log/system-%HOSTNAME%.log"</code></blockquote>
-<p>This template can then be used when defining an output
-selector line. It will result in something like
-"/var/log/system-localhost.log"</p>
+<h4>Standard Template for Forwarding to a Remote Host (RFC3164 mode)</h4>
+<p><pre><code>template(name="ForwardFormat" type="list") {
+ constant(value="&lt;")
+ property(name="PRI")
+ constant(value="&lt;")
+ property(name="timestamp" dateFormat="rfc3339")
+ constant(value=" ")
+ property(name="hostname")
+ constant(value=" ")
+ property(name="syslogtag" position.from="1" position.to="32")
+ constant(value=" ")
+ property(name="msg" spifno1stsp="on" )
+ }
+</code></pre>
+<p>The equivalent string template looks like this:
+<br><pre><code>template(name="forwardFormat" type="string"
+ string="<%PRI%>%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag:1:32%%msg:::sp-if-no-1st-sp%%msg%"
+)</code></pre>
+Note that the template string itself must be on a single line.
+
+<h4>Standard Template for write to the MySQL database</h4>
+<p><pre><code>template(name="StdSQLformat" type="list" option.sql="on") {
+ constant(value="insert into SystemEvents (Message, Facility, FromHost, Priority, DeviceReportedTime, ReceivedAt, InfoUnitID, SysLogTag)")
+ constant(value=" values ('")
+ property(name="msg")
+ constant(value="', ")
+ property(name="syslogfacility")
+ constant(value=", '")
+ property(name="hostname")
+ constant(value="', ")
+ property(name="syslogpriority")
+ constant(value=", '")
+ property(name="timereported" dateFormat="mysql")
+ constant(value="', '")
+ property(name="timegenerated" dateFormat="mysql")
+ constant(value="', ")
+ property(name="iut")
+ constant(value=", '")
+ property(name="syslogtag")
+ constant(value="')")
+ }
+</code></pre>
+<p>The equivalent string template looks like this:
+<br><pre><code>template(name="stdSQLformat" type="string" option.sql="on"
+ string="insert into SystemEvents (Message, Facility, FromHost, Priority, DeviceReportedTime, ReceivedAt, InfoUnitID, SysLogTag) values ('%msg%', %syslogfacility%, '%HOSTNAME%', %syslogpriority%, '%timereported:::date-mysql%', '%timegenerated:::date-mysql%', %iut%, '%syslogtag%')"
+)</code></pre>
+Note that the template string itself must be on a single line.
+
+<h2>legacy format</h2>
+<p>In pre v6-versions of rsyslog, you need to use the <code>$template</code>
+statement to configure templates. They provide the equivalent to string- and
+plugin-based templates. The legacy syntax continous to work in v7, however
+we recommend to avoid legacy format for newly written config files. Legacy and
+current config statements can coexist within the same config file.
+<p>The general format is
+<br><br><code>$template name,param[,options]</code></br></br>
+where "name" is the template name and "param" is a single parameter
+that specifies template content. The optional "options" part is used to
+set template options.
+<h3>string</h3>
+The parameter is the same string that with the current-style format you
+specify in the <b>string</b> parameter, for example:
+<br><br><code>$template strtpl,"PRI: %pri%, MSG: %msg%\n"</code>
+<p>Note that list templates are not available in legacy format, so you need
+to use complex property replacer constructs to do complex things.
+
+<h3>plugin</h3>
+This is equivalent to the "plugin"-type template directive. Here, the
+parameter is the plugin name, with an equal sign prepended. An example
+is:
+<br><br><code>$template plugintpl,=myplugin</code>
+
+<h2>Reserved Template Names</h2>
<p>Template
names beginning with "RSYSLOG_" are reserved for rsyslog use. Do NOT
use them if, otherwise you may receive a conflict in the future (and
@@ -210,12 +395,122 @@ out, but this may happen.</li>
is meant to be written to a log file. Do <b>not</b> use for production or remote
forwarding.</li>
</ul>
+
+<h2>The following is legacy documentation soon to be integrated.</h2>
+
+<!--<table>
+<tr><td>param name</td><td>meaning</td></tr>
+<tr><td>name</td><td>name of the template</td></tr>
+</table>
+-->
+
+<p>Starting with 5.5.6, there are actually two different types of template:
+<ul>
+<li>string based
+<li>string-generator module based
+</ul>
+<p><a href="rsyslog_conf_modules.html#sm">String-generator module</a> based templates
+have been introduced in 5.5.6. They permit a string generator, actually a C "program",
+the generate a format. Obviously, it is more work required to code such a generator,
+but the reward is speed improvement. If you do not need the ultimate throughput, you
+can forget about string generators (so most people never need to know what they are).
+You may just be interested in learning that for the most important default formats,
+rsyslog already contains highly optimized string generators and these are called
+without any need to configure anything. But if you have written (or purchased) a
+string generator module, you need to know how to call it. Each such module has a name,
+which you need to know (look it up in the module doc or ask the developer). Let's assume
+that "mystrgen" is the module name. Then you can define a template for that strgen
+in the following way:
+
+<blockquote><code>template(name="MyTemplateName" type="plugin" string="mystrgen")</code></blockquote>
+<p>Legacy example:</p>
+<blockquote><code>$template MyTemplateName,=mystrgen</code></blockquote>
+(Of course, you must have first loaded the module via $ModLoad).
+<p>The important part is the equal sign in the legacy format: it tells the rsyslog config parser that
+no string follows but a strgen module name.
+<p>There are no additional parameters but the module name supported. This is because
+there is no way to customize anything inside such a "template" other than by
+modifying the code of the string generator.
+
+<p>So for most use cases, string-generator module based templates are <b>not</b>
+the route to take. Usually, we use <b>string based templates</b> instead.
+This is what the rest of the documentation now talks about.
+
+<p>A template consists of a template directive, a name, the
+actual template text and optional options. A sample is:</p>
+<blockquote><code>template(name="MyTemplateName" type="string" string="Example: Text %property% some more text\n" options)</code></blockquote>
+<p>Legacy example:</p>
+<blockquote><code>$template MyTemplateName,"\7Text
+%property% some more text\n",&lt;options&gt;</code></blockquote>
+<p>The "template" (legacy: $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 "string" 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.
+</p>
+<p>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
+<a href="property_replacer.html">property replacer</a>
+(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.<br>
+<br>
+
+<br>
+Properties can be accessed by the <a href="property_replacer.html">property
+replacer</a> (see there for details).</p>
+<p>Templates can be used in the form of a <b>list</b> as well. This has been
+introduced with <b>6.5.0</b> The list consists of two parts which are either
+a <b>constant</b> or a <b>property</b>. The constants
+are taking the part of "text" that you usually enter in string-based templates.
+The properties stay variable, as they are a substitute for different values of a
+certain type. This type of template is extremely useful for complicated cases,
+as it helps you to easily keep an overview over the template. Though, it has
+the disadvantage of needing more effort to create it.</p>
+<br>Config example:
+<br><blockquote><code>template(name="MyTemplate" type="list" option.json="off") {
+ <br>constant(value="Test: ")
+ <br>property(name="msg" outname="mymessage")
+ <br>constant(value=" --!!!-- ")
+ <br>property(name="timereported" dateFormat="rfc3339" caseConversion="lower")
+ <br>constant(value="\n")
+ <br>}
+</code></blockquote>
+<p>First, the general template option will be defined. The values of the template
+itself get defined in the curly brackets. As it can be seen, we have constants
+and properties in exchange. Whereas constants will be filled with a value and probably
+some options, properties do direct to a property and the options that could be needed
+additional format definitions.</p>
+<p>We suggest to use separate lines for all constants and properties. This
+helps to keep a good overview over the different parts of the template.
+Though, writing it in a single line will work, it is much harder to debug
+if anything goes wrong with the template. </p>
+
+<p><b>Please note that templates can also be
+used to generate selector lines with dynamic file names.</b> 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:</p>
+<blockquote><code>template (name="DynFile" type="string" string="/var/log/system-%HOSTNAME%.log")</code></blockquote>
+<p>Legacy example:</p>
+<blockquote><code>$template
+DynFile,"/var/log/system-%HOSTNAME%.log"</code></blockquote>
+<p>This template can then be used when defining an output
+selector line. It will result in something like
+"/var/log/system-localhost.log"</p>
<h3>Legacy String-based Template Samples</h3>
-<p>This section provides some sample of what the default formats would
-look as a text-based template. Hopefully, their description is self-explanatory.
+<p>This section provides some default templates in legacy format, as used in rsyslog
+previous to version 6. Note that this format is still supported, so there is no hard need
+to upgrade existing configurations. However, it is strongly recommended that the legacy
+constructs are not used when crafting new templates.
Note that each $Template statement is on a <b>single</b> line, but probably broken
accross several lines for display purposes by your browsers. Lines are separated by
-empty lines.
+empty lines. Keep in mind, that line breaks are important in legacy format.
<p><code>
$template FileFormat,"%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n"
<br><br>
@@ -233,7 +528,7 @@ $template StdSQLFormat,"insert into SystemEvents (Message, Facility, FromHost, P
[<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
<p><font size="2">This documentation is part of the
<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
-Copyright &copy; 2008 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
+Copyright &copy; 2008-2012 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL
version 2 or higher.</font></p>
</body>