# 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<br>(imudp, imtcp, imkafka)"]
       B["Parser (mmjsonparse,<br>mmleefparse)"]
       C["Template<br>list (mapping)"]
       D["Action<br>(omfile, omelasticsearch)"]
       A --> B --> C --> D

    %% Alternative when a prepared tree exists:
       E["Prepared tree<br>($!ecs)"] --> F["Template<br>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.

## See also

- How to bind a template

- Adding the BOM to a message

- How to separate log files by host name of the sending device

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project

© 2008–2025 Rainer Gerhards and others. Licensed under the Apache License 2.0.