Templates#

Templates define how rsyslog transforms data before output. They map parsed fields into schemas, format records, and generate dynamic destinations.

Overview#

Templates are a central concept in rsyslog. They sit at the point where parsed messages are transformed into their final structure. This includes:

Schema mapping in pipelines — normalize or rename parsed fields into a structured schema (e.g., ECS JSON).
Output generation — create custom message formats or dynamic filenames.
Textual transport formats — add headers when targeting syslog or other line-based transports.

Every output in rsyslog, from files to Elasticsearch to remote syslog, relies on templates. If no explicit template is bound, rsyslog uses built-in defaults compatible with classic syslog.

Message pipeline integration#

Templates appear between parsing and actions. They define what data is sent forward:

flowchart TD A["Input (imudp, imtcp, imkafka)"] B["Parser (mmjsonparse, mmleefparse)"] C["Template list (mapping)"] D["Action (omfile, omelasticsearch)"] A --> B --> C --> D %% Alternative when a prepared tree exists: E["Prepared tree ($!ecs)"] --> F["Template subtree"] --> D A --> E B --> E

Choosing a template type#

Use List template type to map fields one by one (rename keys, add or drop fields, inject constants) and build JSON safely with jsonf or jsonftree.
Use Subtree template type to serialize a prepared JSON tree (for example, after JSON Structured Content Extraction Module (mmjsonparse) or LEEF Structured Content Extraction Module (mmleefparse) populated $!ecs).
Use String template type for simple text records (legacy syslog lines, CSV, or other plain-text formats).
Use Plugin template type for special encodings provided by modules.

Schema mapping with JSONF#

Modern pipelines should prefer structured JSON. The recommended method is:

Enable JSON-safe encoding with option.jsonf="on". Use option.jsonftree="on" instead when you want dotted outname segments to become nested JSON objects automatically.
For each field, use property() or constant() with format="jsonf".
For pre-normalized data, serialize a complete subtree such as $!ecs with a subtree template.

This ensures correct escaping and avoids handcrafted JSON concatenation.

Detailed examples are provided in the template type pages.

Templates for textual transports#

When the target transport expects textual records (for example, classic syslog receivers, line-based file formats, or CSV), the template must include a transport header. This is required so receivers can parse message boundaries and metadata.

Typical cases:

Syslog protocols (RFC5424, RFC3164, protocol-23 draft) Require a syslog header (timestamp, hostname, tag).
Text file formats Such as RSYSLOG_FileFormat or RSYSLOG_TraditionalFileFormat, which prepend headers before the message body.
Custom plain-text records Where a template explicitly builds a line with fields separated by spaces, commas, or tabs.

Predefined reserved templates like RSYSLOG_ForwardFormat or RSYSLOG_SyslogProtocol23Format exist for these purposes.

If your output is a structured JSON pipeline (e.g. to Elasticsearch or a file), you do not need to add any textual header.

The `template()` object#

Templates are defined with the template() object, a static construct processed when rsyslog reads the configuration. Basic syntax:

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

List templates additionally support a block form:

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

See the type-specific subpages for details.

Template types#

Topic	Summary
List template type	List templates build output from a sequence of constant and property statements. They are ideal for schema mapping when fields must be added one by one.
Subtree template type	Builds output from a full JSON subtree (CEE). Best used when the schema has already been remapped and an appropriate variable tree exists.
String template type	Uses a single template string mixing constants and replacement variables. Best suited for textual output with simple manipulation needs.
Plugin template type	Delegates string generation to a plugin for maximum performance. Configuration selects the plugin by name.

Template statements#

Topic	Summary
Constant statement	Outputs literal text. Supports escape sequences and optional JSON field formatting when an outname and format are specified.
Property statement	Extracts and optionally transforms message properties. Supports substring, case, regex, JSON formatting, and more.

Additional topics#

Topic	Summary
Template options	Global modifiers applied to a template. Include SQL and JSON helpers and case sensitivity control.
Template examples	Practical templates for files, forwarding, databases, JSON output, and dynamic file names.
Reserved template names	Names beginning with `RSYSLOG_` are reserved. The following templates are predefined and may be used without explicit definition.
Legacy $template statement	Historic syntax supporting only string templates. Kept for compatibility with older configurations.

Reserved template names overview#

These names provide predefined formats mainly for compatibility. For modern JSON pipelines, prefer custom list or subtree templates.

Name	Purpose
RSYSLOG_TraditionalFileFormat	Old style log file format
RSYSLOG_FileFormat	Modern logfile format with high-precision timestamps
RSYSLOG_TraditionalForwardFormat	Traditional forwarding with low-precision timestamps
RSYSLOG_SysklogdFileFormat	Sysklogd compatible format
RSYSLOG_ForwardFormat	High-precision forwarding format
RSYSLOG_SyslogProtocol23Format	Format from IETF draft syslog-protocol-23
RSYSLOG_DebugFormat	Troubleshooting format listing all properties
RSYSLOG_WallFmt	Host and time followed by tag and message
RSYSLOG_StdUsrMsgFmt	Syslogtag followed by the message
RSYSLOG_StdDBFmt	Insert command for MariaDB/MySQL
RSYSLOG_StdPgSQLFmt	Insert command for PostgreSQL
RSYSLOG_spoofadr	Sender IP address only
RSYSLOG_StdJSONFmt	JSON structure of message properties

Legacy `$template` statement#

For historical configurations, the legacy $template syntax is still recognized. See Legacy $template statement for details.