Linux之rsyslog(3)模板配置

Linux之rsyslog(3)模板配置

Author：Once Day Date：2025年11月4日

全系列文章请查看专栏: Linux Shell基础_Once_day的博客-CSDN博客。

漫漫长路，有人对你微笑过嘛…

参考文档：

• Beginner Tutorials - rsyslog 8.2510.0 documentation

1. 字符串生成模块

rsyslog 的字符串生成模块（String Generator Modules）是一种用于根据消息内容生成字符串的模块，目前与模板系统紧密耦合。以下是对它的详细介绍：

• 功能与作用：其主要用途是通过为模板生成提供本地 C 接口来加速模板处理。自 rsyslog 5.5.6 版本起，该模块就已存在。使用字符串生成模块生成默认文件格式时，大约可提供 5% 的速度提升，对于更复杂的字符串，尤其是包含多个正则表达式的字符串，速度提升可能会更高。
• 接口特点：字符串生成模块的编写接口相当简单，但需要注意的是，它们通过低级接口访问 rsyslog 消息对象，而该接口的稳定性无法保证。因此，如果接口发生变化，可能需要修改字符串生成模块。
• 内置模块：rsyslog 附带了一组核心的内置字符串生成模块，用于提供那些被认为对时间要求严格的默认模板，具体如下：
  • smfile：rsyslog 的默认文件格式。
  • smfwd：rsyslog 的默认（网络）转发格式。
  • smtradfile：传统的 syslog 文件格式。
  • smfwd：传统的 syslog（网络）转发格式。
• 性能影响：如果用自定义字符串替换这些默认模板，将会损失一些性能（大约 5%）。对于典型系统来说，这可能并不重要，但对于高性能系统而言，这可能非常关键。为解决此问题，可以从提供的默认生成器中选择一个，为自定义格式创建一个新的字符串生成模块。如果自己无法完成此操作，可以联系 Adiscon，他们提供价格低廉的字符串生成器定制开发服务。
• 加载方式：字符串生成模块可以动态加载，但提供的默认模块非常重要，因此它们直接内置在可执行文件中。不过，也可以将其设置为动态加载。

2. 模板

2.1 概述

模板定义了 rsyslog 在输出前转换数据的方式。它们将解析后的字段映射到模式中、格式化记录，并生成动态目标地址。

模板是 rsyslog 的核心概念，作用于解析后的消息转换为最终结构的环节。其功能包括：

• 流水线中的模式映射：将解析后的字段标准化或重命名，转换为结构化模式（如 ECS JSON）。
• 输出生成：创建自定义消息格式或动态文件名。
• 文本传输格式：向 syslog 或其他基于行的传输目标发送数据时添加头部信息。

rsyslog 的所有输出（从文件到 Elasticsearch，再到远程 syslog）都依赖模板。若未明确绑定模板，rsyslog 会使用与传统 syslog 兼容的内置默认模板。

模板位于解析和操作之间，定义了向前传递的数据内容：

选择模板类型：

• 列表模板（List）：逐个映射字段（重命名键、添加或删除字段、注入常量），使用jsonf或jsonftree安全构建 JSON。
• 子树模板（Subtree）：序列化已准备好的 JSON 树（例如，JSON 结构化内容提取模块（mmjsonparse）或 LEEF 结构化内容提取模块（mmleefparse）填充$!ecs之后）。
• 字符串模板（String）：用于简单文本记录（传统 syslog 行、CSV 或其他纯文本格式）。
• 插件模板（Plugin）：用于模块提供的特殊编码格式。

现代流水线应优先使用结构化 JSON，推荐方法如下：

• 通过option.jsonf="on"启用 JSON 安全编码。若希望点分隔的输出名称段自动成为嵌套 JSON 对象，可改用option.jsonftree="on"。
• 对每个字段，使用property()或constant()并指定format="jsonf"。
• 对于已标准化的数据，使用子树模板序列化完整子树（如$!ecs）。

这种方式可确保正确转义，避免手动拼接 JSON 带来的问题。详细示例请参阅各模板类型的对应页面。

当目标传输方式要求文本记录时（如传统 syslog 接收器、基于行的文件格式或 CSV），模板必须包含传输头部。这是接收器解析消息边界和元数据的必要条件。

典型场景：

• Syslog 协议（RFC5424、RFC3164、protocol-23 草案）：需包含 syslog 头部（时间戳、主机名、标记）。
• 文本文件格式：如RSYSLOG_FileFormat或RSYSLOG_TraditionalFileFormat，会在消息体前添加头部。
• 自定义纯文本记录：模板明确构建字段以空格、逗号或制表符分隔的行。

rsyslog 提供了RSYSLOG_ForwardFormat或RSYSLOG_SyslogProtocol23Format等预定义保留模板，可满足上述场景需求。

若输出为结构化 JSON 流水线（如发送至 Elasticsearch 或 JSON 文件），则无需添加任何文本头部。

模板通过template()对象定义，这是一种静态结构，在 rsyslog 读取配置时进行处理。基本语法如下：

template(name="..." type="...")

列表模板（List）还支持块形式：

template(name="..." type="list" option.jsonftree="on") {property(outname="field" name="msg" format="jsonf")constant(outname="@version" value="1" format="jsonf")
}

模板类型：

主题	概述
列表模板（List）	由一系列常量（constant）和属性（property）语句构建输出。适合需要逐个添加字段的模式映射场景。
子树模板（Subtree）	从完整的 JSON 子树（CEE）生成输出。最适合已完成模式重映射且存在合适变量树的场景。
字符串模板（String）	使用混合常量和替换变量的单个模板字符串。适合需简单处理的文本输出场景。
插件模板（Plugin）	将字符串生成委托给插件以获得最佳性能。通过名称选择插件进行配置。

模板语句：

主题	概述
常量语句（Constant）	输出文本常量。支持转义序列，指定outname和format时还支持 JSON 字段格式化。
属性语句（Property）	提取并可选转换消息属性。支持子字符串、大小写转换、正则表达式、JSON 格式化等功能。

其他主题：

主题	概述
模板选项（Template options）	应用于模板的全局修饰符。包括 SQL 和 JSON 辅助功能、大小写敏感性控制等。
模板示例（Template examples）	适用于文件、转发、数据库、JSON 输出和动态文件名的实用模板。
保留模板名称（Reserved template names）	以RSYSLOG_开头的名称为保留名。以下预定义模板可直接使用，无需显式定义。
旧式$template语句（Legacy $template statement）	仅支持字符串模板的历史语法。为兼容旧配置而保留。

保留模板名称概述，这些名称提供的预定义格式主要用于兼容性。对于现代 JSON 流水线，建议使用自定义列表模板或子树模板。

名称	用途
RSYSLOG_TraditionalFileFormat	旧式日志文件格式
RSYSLOG_FileFormat	带高精度时间戳的现代日志文件格式
RSYSLOG_TraditionalForwardFormat	带低精度时间戳的传统转发格式
RSYSLOG_SysklogdFileFormat	与 sysklogd 兼容的格式
RSYSLOG_ForwardFormat	高精度转发格式
RSYSLOG_SyslogProtocol23Format	IETF 草案 syslog-protocol-23 中定义的格式
RSYSLOG_DebugFormat	列出所有属性的故障排除格式
RSYSLOG_WallFmt	包含主机、时间、标记和消息的格式
RSYSLOG_StdUsrMsgFmt	包含 syslog 标记和消息的格式
RSYSLOG_StdDBFmt	MariaDB/MySQL 的插入命令格式
RSYSLOG_StdPgSQLFmt	PostgreSQL 的插入命令格式
RSYSLOG_spoofadr	仅包含发送者 IP 地址的格式
RSYSLOG_StdJSONFmt	消息属性的 JSON 结构格式

旧式 $template 语句，对于历史配置，rsyslog 仍支持旧式$template语法。详情请参见《Legacy 》（旧式template 语句）。

2.2 列表模板类型（List template type）

列表模板通过一系列常量（constant）和属性（property）语句构建输出。当需要逐个添加字段进行模式映射时，它们是理想选择。

列表模板类型通过大括号内的一系列常量语句和属性语句生成输出。需要逐字段构建结构化输出或执行显式模式映射时，可使用这种模板。

• 属性语句（Property statement）：将 rsyslog 的属性或变量值输出到结果中。
• 常量语句（Constant statement）：设置固定值或将文本常量注入输出中。

列表模板适用于以下场景：

• 模式映射：逐个分配每个输出字段。
• 支持结构化输出的模块：如 MongoDB 输出模块（ommongodb）或 Elasticsearch 输出模块（omelasticsearch）。
• 需要常量文本的文本输出：如文件输出模块（omfile）中需要换行符等常量文本的场景。

与子树模板类型相比，列表模板更繁琐但控制力更强。尚未拥有完整模式树时（例如从零开始构建 ECS 映射），优先选择列表模板。通用数据流水线，列表模板是模式映射的关键数据流水线步骤：

简单 ECS 映射(jsonftree)：一个最小化的列表模板，以 JSON 格式输出选定的 ECS 字段。启用option.jsonftree="on"，使点分隔的outname值成为嵌套对象而非扁平字符串：

template(name="ecs_min" type="list" option.jsonftree="on") {property(outname="@timestamp"     name="timereported"format="jsonf" dateFormat="rfc3339")property(outname="event.original" name="msg" format="jsonf")property(outname="host.hostname"  name="hostname" format="jsonf")property(outname="log.level"      name="syslogseverity-text" format="jsonf")
}

这将生成有效的 JSON，无需手动处理引号或大括号。

使用常量固定字段(jsonftree)：有时需要设置固定的 JSON 字段(例如版本标记或标签)。使用带有outname和format="jsonf"的常量语句，让编码器统一处理引号：

template(name="ecs_fix" type="list" option.jsonftree="on") {property(outname="@timestamp"     name="timereported"format="jsonf" dateFormat="rfc3339")property(outname="event.original" name="msg" format="jsonf")/* 通过常量设置固定字段，编码为JSON格式 */constant(outname="@version" value="1" format="jsonf")
}

2.3 子树模板类型（Subtree template type）

子树模板从完整的 JSON 子树（CEE）生成输出。最适合已完成模式重映射且存在合适变量树的场景。

子树模板类型通过完整的（CEE/JSON）子树生成输出。这种模板适用于数据流水线中已预先完成模式映射，且存在完整变量树（如$!ecs）的场景。

当需要将整个子树置于生成对象的根节点时，必须使用这种方法。其他模板类型只能生成子容器。子树模板内部无法插入常量文本。

子树模板常与结构化输出模块搭配使用，如 MongoDB 输出模块（ommongodb）、Elasticsearch 输出模块（omelasticsearch），也可用于文件输出模块（omfile）等基于文本的输出场景。

在使用 mmjsonparse、mmaudit 或 mmleefparse 等解析模块完成消息转换后，使用子树模板会特别高效。

典型工作流程是先将消息内容标准化为 ECS 兼容的子树，再通过子树模板导出：

set $!ecs!event!original = $msg;
set $!ecs!host!hostname = $hostname;
set $!ecs!log!level = $syslogseverity-text;
set $!ecs!observer!type = "rsyslog";
template(name="ecs_tpl" type="subtree" subtree="$!ecs")

上述配置先将消息映射到$!ecs下的 ECS 字段，再通过模板将完整的 ECS 子树以 JSON 格式输出。

子树模板是 rsyslog 数据流水线的天然组成部分：

若尚未完成模式树的重映射，可考虑使用列表模板。列表模板支持在导出前逐字段映射构建结构化输出。

2.4 字符串模板类型（String template type）

字符串模板使用混合了常量和替换变量的单个模板字符串。最适合需简单处理的文本输出场景。

字符串模板与旧式$template语句非常相似，必须指定string参数，该参数包含待应用的模板字符串。字符串中混合了常量文本和由属性替换器（property replacer）处理的替换变量。

template(name="tpl3" type="string"string="%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n")

百分号（%）之间的内容由属性替换器解析，它会读取消息属性，并应用格式化和处理选项。

2.5 插件模板类型（Plugin template type）

插件模板将字符串生成委托给插件以实现最高性能。配置通过名称选择插件。

在插件模板中，输出字符串由插件（也称为字符串生成器）生成。格式由插件内部代码固定，以灵活性为代价换取高性能。模板参数plugin指定生成器名称，且插件必须在使用前加载。

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

2.6 常量语句（Constant statement）

常量语句用于输出文本常量。指定outname和format参数时，支持转义序列和可选的 JSON 字段格式化。

该语句用于指定常量文本，主要适用于基于文本的输出场景，可在其中包含换行符等常量片段。测试环境示例如下：

template(name="outfmt" type="list") {property(name="$!usr!msgnum")constant(value="\n")
}

常量文本中支持以下转义序列：

• \\ – 单个反斜杠
• \n – 换行符（LF）
• \ooo – 三位八进制数字表示一个字符（如\101代表 “A”），必须恰好为三位数字
• \xhh – 两位十六进制数字表示一个字符（如\x41代表 “A”），必须恰好为两位数字

若反斜杠后跟随不支持的字符，行为将不可预测。

生成结构化输出时，未指定outname参数的常量文本会被忽略。需在名称 / 值树中包含常量数据时，需指定outname，示例如下：

template(name="outfmt" type="list") {property(name="$!usr!msgnum")constant(value="\n" outname="IWantThisInMyDB")
}

生成常量 JSON 字段时，可使用format参数：

template(name="outfmt" type="list" option.jsonf="on") {property(outname="message" name="msg" format="jsonf")constant(outname="@version" value="1" format="jsonf")
}

上述配置中，常量语句会生成"@version":"1"。value和format参数必须同时指定。

若希望点分隔的outname值以嵌套对象形式输出，需在模板中启用option.jsonftree="on"，而非option.jsonf。

参数说明：

• value – 待输出的常量值
• outname – 结构化输出的字段名
• format – 可选值：空值或jsonf

2.7 属性语句（Property statement）

属性语句用于提取消息属性并可选择性地对其进行转换。支持子字符串、大小写转换、正则表达式、JSON 格式化等多种功能。

该语句用于插入属性值，可访问任意消息属性，并提供众多选项用于选择属性的部分内容或修改其文本格式。

参数说明：

• name：待访问的属性名称。
• outname：结构化输出的字段名。
• dateFormat：日期相关属性的格式。参考属性替换器文档查看可用格式，文档中列出的字符串模板选项需省略date-前缀（例如用year而非date-year）。

需构建自定义日期格式时，可组合多个属性语句：

property(name="timereported" dateFormat="year")
constant(value="-")
property(name="timereported" dateFormat="month")
constant(value="-")
property(name="timereported" dateFormat="day")

其他核心参数：

• date.inUTC：以 UTC 时间显示日期(8.18.0 版本起支持)。

• caseConversion：文本大小写转换，可选值：lower（小写）、upper（大写）。

• controlCharacters：控制字符处理方式，可选值：escape（转义）、space（替换为空格）、drop（丢弃）。

• securePath：为动态文件模板创建安全路径，可选值：drop（丢弃不安全字符）、replace（替换不安全字符）。

• format：字段格式，支持值：

  • csv：生成 CSV 格式数据
  • json：JSON 编码内容（无字段头部）
  • jsonf：完整 JSON 字段
  • jsonr：避免双重转义同时保证 JSON 安全
  • jsonfr：jsonf与jsonr的组合

• position.to：结束位置（8.2302.0 版本起支持负值，从字符串末尾截取）。例如position.from="2" position.to="-1"会移除首尾字符，适合去除括号等包围字符：

  property(name="msg" position.from="2" position.to="-1")
  

  输入[abc]时，输出结果为abc，尤其适用于解析 STRUCTURED-DATA 字段。

• position.relativeToEnd：按字符串末尾解释位置（7.3.10 版本起支持）。

• fixedWidth：字符串长度不足时用空格填充至position.to指定长度，可选值：on、off（默认）（8.13.0 版本起支持）。

• compressSpace：子字符串提取后，将多个空格压缩为单个空格（8.18.0 版本起支持）。

• field.number：选择匹配的字段序号。

• field.delimiter：分隔符字符的十进制值。

• regex.expression：正则表达式。

• regex.type：正则表达式类型，可选值：ERE（扩展正则）、BRE（基础正则）。

• regex.noMatchMode：无匹配时的处理方式。

• regex.match：使用的匹配项。

• regex.subMatch：使用的子匹配项。

• dropLastLf：丢弃末尾的换行符。

• mandatory：设为on时，结构化输出中即使字段为空也始终显示。

• spIfNo1stSp：RFC3164 处理的专家选项。当启用此选项时，rsyslog 会在解析 RFC3164 格式日志时，如果在 TAG 和 MESSAGE 之间没有第一个空格，它会尝试插入一个空格，以便更好地分离 TAG 和 MSG 字段。

• dataType：仅jsonf格式支持，设置 JSON 数据类型（rsyslog 属性默认为字符串，部分接收系统需数字或布尔值），支持值：

  • number：输出数值，空值显示为 0
  • string：输出字符串（默认）
  • auto：整数则输出数值，否则输出字符串
  • bool：非空且非 0 时输出true，否则输出false

• onEmpty：仅jsonf格式支持，空值处理方式，可选值：keep（保留空字符串）、skip（跳过字段）、null（输出null）。

2.8 模板选项(Template options)

模板选项是作用于整个模板的全局修饰符，作为template()对象的参数指定，与仅作用于单个属性的属性选项不同。

可用选项(不区分大小写)：

• option.sql：适用于 MariaDB/MySQL 的格式字符串。将单引号（'）和反斜杠（\\）替换为转义形式（\\'和\\\\）。使用时需确保 MySQL 的NO_BACKSLASH_ESCAPES选项已关闭。
• option.stdsql：适用于符合标准的 SQL 服务器的格式字符串。将单引号替换为双单引号（''）。当 MySQL 启用NO_BACKSLASH_ESCAPES时使用此选项。
• option.json：对数据进行 JSON 适配转义。
• option.jsonf：将模板渲染为 JSON 对象，自动添加大括号并在元素间添加逗号。
• option.jsonftree：与option.jsonf类似，同样渲染为 JSON，但会将点分隔的outname字段（如event.dataset.name）解析为嵌套对象。未开启此选项时，点分隔名称会保留为扁平字符串，以兼容旧有行为。
• option.caseSensitive：属性名称区分大小写。默认情况下，属性名称在定义时会转换为小写。若 JSON（$!*）、本地（!.）或全局（$!）属性中包含大写字母，需启用此选项。

关键注意事项:

• option.sql、option.stdsql、option.json、option.jsonf和option.jsonftree mutually exclusive（互斥），不可同时启用。
• 向数据库写入数据时，必须指定option.sql或option.stdsql以防范 SQL 注入。数据库写入模块会检查这两个选项是否存在，否则将拒绝运行。
• 生成后续需导入数据库的文件时，这些选项也很有用。但无需时请勿启用，以免增加额外的处理开销。

2.9 模板示例（Template examples）

（1）标准文件写入模板：

# 列表模板形式：
template(name="FileFormat" type="list") {property(name="timestamp" dateFormat="rfc3339")constant(value=" ")property(name="hostname")constant(value=" ")property(name="syslogtag")property(name="msg" spIfNo1stSp="on")property(name="msg" dropLastLf="on")constant(value="\n")
}# 等效字符串模板形式：
template(name="FileFormat" type="string"string="%TIMESTAMP% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n")

（2）远程主机转发标准模板（RFC3164）：

# 列表模板形式：
template(name="ForwardFormat" type="list") {constant(value="<")property(name="pri")constant(value=">")property(name="timestamp" dateFormat="rfc3339")constant(value=" ")property(name="hostname")constant(value=" ")property(name="syslogtag" position.from="1" position.to="32")property(name="msg" spIfNo1stSp="on")property(name="msg")
}# 等效字符串模板形式：
template(name="ForwardFormat" type="string"string="<%PRI%>%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag:1:32%%msg:::sp-if-no-1st-sp%%msg%")

（3）MariaDB/MySQL 数据库写入标准模板：

# 列表模板形式：
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="')")
}# 等效字符串模板形式：
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%')")

（4）JSON 格式生成模板，适用于 ElasticSearch 等 RESTful API 场景：

template(name="outfmt" type="list" option.jsonf="on") {property(outname="@timestamp" name="timereported" dateFormat="rfc3339" format="jsonf")property(outname="host" name="hostname" format="jsonf")property(outname="severity" name="syslogseverity" caseConversion="upper" format="jsonf" dataType="number")property(outname="facility" name="syslogfacility" format="jsonf" dataType="number")property(outname="syslog-tag" name="syslogtag" format="jsonf")property(outname="source" name="app-name" format="jsonf" onEmpty="null")property(outname="message" name="msg" format="jsonf")
}

生成的输出示例：

{"@timestamp":"2018-03-01T01:00:00+00:00", "host":"192.0.2.8", "severity":7, "facility":20, "syslog-tag":"tag", "source":"tag", "message":" msgnum:00000000:"}

若source字段为空且设置onEmpty="null"，输出示例：

{"@timestamp":"2018-03-01T01:00:00+00:00", "host":"192.0.2.8", "severity":7, "facility":20, "syslog-tag":"tag", "source":null, "message":" msgnum:00000000:"}

为 omfile 创建动态文件名，模板可生成动态文件名，例如按主机名拆分 syslog 消息：

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

2.10 旧式$template语句

旧式语法仅支持字符串模板，为兼容旧配置而保留。

这种旧式格式功能有限，但仍经常在旧环境中遇到。它仅支持字符串模板，语法如下：

$template myname,<string-template>

其中myname是模板名称（类似于现代格式中的name="myname"），<string-template>与现代模板中的string参数内容一致。

现代模板形式：

template(name="tpl3" type="string"string="%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n")

等效的旧式语句：

$template tpl3,"%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n"