From 2876bb6118e96a83a9078e426f4995cab15323e2 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Wed, 19 Sep 2012 12:06:39 +0200 Subject: doc: begin rewrite of template doc --- doc/rsyslog_conf_templates.html | 199 +++++++++++++++++++++++++++++++--------- 1 file changed, 157 insertions(+), 42 deletions(-) diff --git a/doc/rsyslog_conf_templates.html b/doc/rsyslog_conf_templates.html index b97f6609..4360c691 100644 --- a/doc/rsyslog_conf_templates.html +++ b/doc/rsyslog_conf_templates.html @@ -3,7 +3,7 @@

This is a part of the rsyslog.conf - documentation.

back -

Templates

+

Templates

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,7 +16,161 @@ 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.

-

Starting with 5.5.6, there are actually two differnt types of template: +

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. +

The template() statement

+

The template() statement is used to define templates. Note that it is a +static 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. +

The basic structure of the template statement is as follows: +

+template(parameters) +

+In addition to this simpler syntax, list templates (to be described below) +support an extended syntax: +

+template(parameters) { list-descriptions } +

Each template has a parameter name, which specifies the templates +name, and a parameter type, which specifies the template type. The name +parameter must be unique, and behaviour is unpredictable if it is not. The type +parameter specifies different template types. Different types simply enable +different ways to specify the template content. The template type does not +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: +

+The various types are described below. + +

list

+

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. +subtree 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 directly 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). + +

subtree

+

Available since rsyslog 7.1.4 +

+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 + +

string

+

This closely resembles the legacy template statement. It +has a mandatory parameter string, 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. + +

plugin

+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 plugin 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. + +

legacy format

+

In pre v6-versions of rsyslog, you need to use the $template +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. +

The general format is +

$template name,param[,options]

+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. +

string

+The parameter is the same string that with the current-style format you +specify in the string parameter, for example: +

$template strtpl,"PRI: %pri%, MSG: %msg%\n" +

Note that list templates are not available in legacy format, so you need +to use complex property replacer constructs to do complex things. + +

plugin

+This is equivalent to the "plugin"-type template directive. Here, the +parameter is the plugin name, with an equal sign prepended. An example +is: +

$template plugintpl,=myplugin + +

Reserved Template Names

+

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 +quite unpredictable behaviour). There is a small set of pre-defined +templates that you can use without the need to define it:

+ + +

The following is legacy documentation soon to be integrated.

+ + + +

Starting with 5.5.6, there are actually two different types of template: