Rsyslog的模板template详解

一、 Template功能

• 根据用户需求指定任意格式
• 动态生成文件名
• 每个输出都使用了一些模板，包括针对文件的，针对用户消息等

备注：

• 旧版本：$template
• 新版本：template()

V6之前是旧格式

V7版本，传统语法与最新配置可在配置文件中混合使用，我们下面学习的是新格式。

二、Template()声明

1.作用

用来定义模板，是一种静态声明，表示所有的模板都会在rsyslog读取配置文件的时候被定义。template不会受到if语句或嵌入配置的影响。

2.基本声明结构

template(parameters)

list templates则是一种扩展的支持   template(parameters) {list-descriptions}

3.template的类型

类型参数指定不同的template类型，不同类型就可以使用不同的方法来定义template的内容，类型不会影响插件工作，合适的template类型会很好的匹配需求。

• List
• Subtree
• String
• Plugin

下面具体讲一下每种类型

三、四种类型的学习

1. list类型

List template是由一系列反复出现的内容和变量语句生成的，内容通过“{}”包含起来，这种类型一般用于已知输出结构的情况，比如，ommongodb。建议在有复杂属性替换的情况下使用这种类型，比较清晰

List template包含template头部（type = "list"）和紧接着的用”{}”括起来的constant和property部分。

• constant：不变的，对反复出现的文本进行描述
• property：描述属性。对于property有多种可用的选项，大多数选项被用来提取部分的属性内容或者用来修改文本（比如将大写字母转换为小写字母）

举例：

template(name="tpl1" type="list"){
constant(value="Syslog MSG is: '")

property(name="msg")

constant(value="', ")

property(name="timereported" dataFormat="rfc3339" caseConversion="lower")

constant(value="
")

}

备注：这个示例可能会被用于定位常见的文件输出

（1）常量的声明（constant statement）

一种指定常量文本的方法。常量主要用于基于文本的输出。

举例：

template(name="outfmt" type="list"){

    property(name="$!user!msgnum")

    constant(value+"
")

    }

下面是常量文本中可被识别的一系列转义字符的含义： 

	单个反斜线
	换行（line feed）
00	三位八进制数-数字值对应的字符（101代表字母A），三个数是必须的，但是建议使用十六进制
xhh	十六进制数-表示数字值对应的字符（x41代表A），注意两个数都是必须给定的

如果反斜线后面跟了一个不支持的字符，那么将会被当做一个威胁报错，这种情况会导致不可知的动作

为结构化输出创建name/value树的时候，没有outname参数的常量（constant text）会被忽略掉。

template(name="outfmt" type="list"){

property(name="$!usr!msgnum")

constant(value="
" outname="IWantThisInMyDB")

}

常量声明时可使用以下参数            

value	常量的值
outname	结构化输出中的字段名

（2）property的声明

property声明用于包含属性文本，可以用于所有的属性。选项options用来指定提取或修改属性的某些部分，对于property支持以下参数：                         

name	要访问的属性名
outname	结构化输出中的字段名
dateformat	用于指定日期相关属性的日期格式
caseconversion	将文本字母转换成大写或小写，支持的value有“lower”和“upper”
controlcharacters	指定如何处理控制字符，value：转义字符（escape），空格（用一个空格替换），从字符串中移除（drop）
securepath	在dynafile templates中用来创建pathnames
format	指定字段格式。csv（csv），json（没有字段头field header的json格式），jsonf（完整的json段），jsonr（没有双反斜线，但是可将其作为安全的json字段），jsonfr（jsonf和jsonr的结合格式）
position.from	从这个位置开始包含子字符串（1是第一个位置）
position.to	一直到这个位置开始包含子字符串
position.relativetoend	From和to的位置与字符串的结尾有关
field.number	包含此字段的匹配
field.delimiter	字段提取的分隔符的十进制值
regex.expression	使用的正则表达式
regex.type	要么ERE，要么BRE
regex.nomatchmode	如果没有匹配该怎么做
regex.match	所使用的匹配
regex.submatch	所使用的子匹配
droplastLf	如果有一串换行符（LF）则丢弃
mandatory	表示字段的强制性，如果设置为”on”，那么就算为空，这个字段也会在结构化输出的时候一直存在。如果设置为”off”（默认值），那么当为空得时候，这个字段就不会传给结构化输出。这个选项在支持动态结构的输出中很有用（比如ommongodb）
spifno1stsp	用于处理RFC3164 template的专用选项

2.子树（subtree）

（1）概念

　　从rsyslog 7.1.4开始启用的内容。subtree主要用来生成基于完整（CEE）subtree的template。这种模板主要用于知道如何处理层级结构的输出，比如ommongodb，对于这种类型，参数subtree必须被指定以告知要使用哪个subtree。例如template(name="tpl1" type="subtree" subtree="$1")表示包含所有CEE数据，而template(name="tpl2" type="subtree" subtree="$!usr!tpl2")则只包含以"$!usr!tpl2"开头的subtree。使用这种模板的核心理念是，真实地数据是通过set和unset脚本语句预生成的，同时结果的结构会再模板内部被使用。如果一个完整的subtree需要被直接放到对象的根部（object’s root），则必须使用这种类型。相对于其他所有的模板类型，只有subcontainers能够被生成。注意subtree类型同样可以用于基本文本的输出，如omfile。不过，这种情况下，你是无法指定常量的，因此就无法包含换行符。由此，对于文本输出使用subtree同样被用于做调试或者一些特殊的场合（比如文本将会被JSON解释器所解析）

（2）用例

subtree的典型用例：先创建一个自定义的subtree然后再template中使用，比如：

set $!usr!tpl2!msg = $msg;

set $!usr!tpl2!dataflow = fied($msg, 58, 2);

template(name="tpl2" type="subtree" subtree="$!usr!tpl2")

这里，我们假设$msg包含不同的字段，来自某字段的数据将会被提取出来并存储用以与message一起作为字段的内容

3.字符串（string）

包含一个强制的参数string，用来包含要使用的模板字符串，模板字符串是常量和replacement变量的混合字符串。这种变量来自于message或者当最后的字符串到达插件时候生成的动态内容。基于字符串的模板是制定文本内容的一种很好的方法，特别是当对于属性没有复杂操作的情况下，特别适用。

template(name="tpl3" type="string"

string="%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%
"

) 

上例中，百分号之间的文本将会被rsyslog的property replacer所解释。在nutshell中，它包含了将要使用的属性以及格式化所需的选项和其他处理，这与list模板中的property对象的功能类似（实际上仅仅是使用不同的语言来描述同样地事情）

所有百分号外的内容都是常量，这上例中，在属性值中间主要含有一些空格，在字符串的最后，使用了一个转义字符。

转义字符允许指定那些无法打印的字符，这与C以及其他语言中得转义字符相似，他们是以一个反斜线引出并在其后跟上一个或多个字符来表示特定的字符，比如“7”在US-ASCII中代表BEL（响铃），“ ”代表新行。总之与C和perl语言支持的相似，但会有一些限制

4. 插件（plugin）

使用plugin类型的时候，模板是由一个插件（或者被称为”strgen”或者”string generator”）来生成。它的格式是固定的，就像他被编码时候一样。然而这种类型并不灵活，由于它提供了很高的性能（并不是说其他类型的模板很缓慢，而是指在那些对实时性要求很高的环境中），所以会被使用。在这种类型中，plugin参数必须被指定，并且要包含插件名用来识别它。注意在模板中，插件必须要被实现加载好，例如：

template(name="tpl4" type="plugin" plugin="mystrgen")

五、选项（options）

选项是可选的，注意不要混淆模板的选项和属性的选项-属性选项会被属性替换器（property replacer）处理并用于单个属性而非整个模板。模板选项是大小写敏感的，目前模板属性有：

• option.sql - 用于为MySQL将字符串格式化为SQL语句，其中的单引号（’）和反斜线()会被对应的转义字符替换（即“’”和“”）。注意在MySQL配置中，必须禁用NO_BACKSLASH_ESCAPES模式（默认就是禁用的）
• option.stdsql - 将字符串格式化为SQL语句以发送给表在哪混的sql服务器。这种方式会将字段中的单引号(‘)用两个单引号来替换(’‘)，如果MySQL配置文件中NO_BACKSLASH_ESCAPES设置为on那么就必须使用这个stdsql选项
• option.json - 将字符串格式化为JSON形式，这种方式会讲字段中的单引号(‘)用两个单引号(’‘)来替换。

不管什么时候，绝对不要同时使用多个模板选项，因为会引起未知的故障和逻辑错误

当模板是用以写入数据库的时候，则必须指定要么为sql选项要么为stdsql选项，否则有可能出现SQL注入的问题。需要注意的是，由于在现实情况，有的厂商并不遵守标准的sql规则而引入自己的转义方法，所以一种选项并不能满足所有的工作，因此你必须确保你使用的是正确地格式。如果格式错误，仍然有可能遭遇sql注入的威胁。数据库写入程序会检查模板中存在的SQL选项，如果不存在，那么数据库写入操作就会被禁用，这也主要是为了防止由于你忘记配置sql选项而导致的SQL注入问题。SQL选项对于文件也很有用，特别是在出于性能考虑，你想要将文件导出到另外一台机器的数据库中得情况。对于其他的情况，如果没有特别需要，建议不要使用，因为这会带来一些处理时间上的开销，虽然不多，但是对于某些在这方面敏感的系统来说，这就显得尤为重要了。对于写入数据库动作来说，默认情况下使用的是sql选项，由于当前我们只支持MySQL并且sql选项也兼容了MySQL默认的配置，所以这就是个最佳选择了。当然如果你将NO_BACKSLASH_ESCAPES设置为on的话，则就需要使用stdsql选项以避免SQL注意的威胁。

六、备注（附加）

1.为omfile创建动态文件名

template(name="DynFile" type="string" string="/var/log/system-%HOSTNAME%.log")

2.传统格式

传统语法格式如下：

$template name,param[,options] 

name:模板名

param：指定模板内容的参数

options：设置模板选项

3.预留的模板名

• 以”RSYSLOG_”开头的模板名是位rsyslog预留使用的，自定义的模板不要使用这些名字，否则有可能产生冲突导致未知故障。下面就是一直预留共使用的系统模板
• RSYSLOG_TraditionalFileFormat - 传统风格的使用不怎么精确的时间戳的默认日志文件格式
• RSYSLOG_FileFormat - “现代风格”的日志文件格式，与TraditionalFileFormat类似，但是使用的是更高精度的时间戳和时区信息
• RSYSLOG_TraditionalForwardFormat - 传统风格的转发格式，时间戳精度低，通常用于将日志消息转发给其他的syslogd或者低于3.12.5版本的rsyslogd
• RSYSLOG_SysklogdFileFormat - sysklogd兼容的日志格式。如果使用选项$SpaceLFOnReceive on，$EscapeControlCharactersOnReceive off和$DropTrailingLFOnReception off，那么日志格式就会遵从sysklogd的日志格式
• RSYSLOG_ForwardFormat - 类似传统的风格，但是有更高精度的时间戳和时区信息。建议在将日志消息转发给3.12.5或更高的rsyslog版本的时候使用
• RSYSLOG_SyslogProtocol23Format - 在IETF的internet-draft ietf-syslog-protocol-23中指定的格式，可能会成为新的RFC日志标准格式。这种格式加入了一些改进。rsyslog的消息分析程序（message parser）可以读懂这种格式，所以它可以在最近版本的rsyslog中使用，对于不支持的syslog版本可能会直接拒绝这种格式，所以使用之前最好检查一下。【注】在最终的RFC标准出台的时候，格式可能不会发生改变，但也有可能会发生一些变化
• RSYSLOG_DebugFormat - 一种特殊的用于调试property故障的格式，不要在生产环境或者远程转发的情况下使用这种格式