Rsyslog Parameter String Constants¶

String constants provide values that are evaluated at startup and remain unchanged for the lifetime of the rsyslog process.

Uses¶

String constants are used in comparisons, configuration parameter values, and function arguments, among other places.

Escaping¶

In string constants, special characters are escaped by prepending a backslash, similar to C or PHP.

If in doubt how to escape properly, use the RainerScript String Escape Online Tool.

Types¶

Rsyslog provides different types of string constants, inspired by common shell semantics.

Single quotes¶

Values are used unaltered, except that escape sequences are processed.

Double quotes¶

Equivalent to single quotes; a literal dollar sign must be escaped (\$). If $ is not escaped, a syntax error is raised and rsyslog usually refuses to start.

Backticks¶

Added in version 8.33.0: Initial support for backticks (limited subset).

Changed in version 8.37.0: Multiple environment variable expansions and constant text between them.

Changed in version 8.2508.0: Support for brace-style variables (${VAR}), correct termination of unbraced $VAR at the first non-[A-Za-z0-9_] character, and support for variable text adjacent to static text (e.g., key/value pairs).

Backticks intentionally implement a small, safe subset of shell-like behavior. Currently, only the following forms are supported:

echo … — evaluate simple text with environment variable expansion.
cat <filename> — include the contents of a single file. If the file is unreadable, the result is an empty string.

Any other construct results in a parse error. There must be exactly one space between echo or cat and the following argument.

Environment variable expansion rules¶

Both $VAR and ${VAR} are supported.
For unbraced $VAR, the variable name ends at the first character not in [A-Za-z0-9_]; that character is emitted literally. This makes expressions like $VAR! or $VAR.suffix work as expected.
For braced ${VAR}, expansion ends at the matching }, which naturally supports adjacent static text (e.g., prefix${VAR}suffix).
Unknown variables expand to the empty string (not an error).
Command substitutions and other shell features (e.g., $(pwd)) are not supported by design.

Examples¶

Simple expansion¶

Given SOMEPATH=/var/log/custompath:

param = `echo $SOMEPATH/myfile`
# expands to: /var/log/custompath/myfile

Brace form and adjacent text¶

Given HOSTNAME=myhost:

title = `echo Log-${HOSTNAME}!`
# expands to: Log-myhost!

Key/value pairs (common with module parameters)¶

Given KAFKA_PASSWORD=supersecret and rsyslog >= 8.2508.0:

action(
  type="omkafka"
  broker=["kafka.example.com:9093"]
  confParam=[
    "security.protocol=SASL_SSL",
    "sasl.mechanism=SCRAM-SHA-512",
    "sasl.username=myuser",
    `echo sasl.password=${KAFKA_PASSWORD}`
  ]
)

Conditional enablement of configuration objects via `config.enabled`¶

You can toggle modules, inputs, actions, etc. based on environment variables by setting the generic boolean parameter config.enabled. The example below loads imtcp and starts a TCP listener only if LOAD_IMTCP evaluates to a truthy value.

systemd service (recommended on most distributions)

Use a drop-in to set the environment variable in rsyslog’s service context:

sudo mkdir -p /etc/systemd/system/rsyslog.service.d
sudo tee /etc/systemd/system/rsyslog.service.d/10-imtcp.conf >/dev/null <<'EOF'
[Service]
# Enable
Environment=LOAD_IMTCP=on
EOF

sudo systemctl daemon-reload
sudo systemctl restart rsyslog

Alternatively, you can point to an EnvironmentFile= that contains LOAD_IMTCP=….

# /etc/systemd/system/rsyslog.service.d/10-imtcp.conf
[Service]
EnvironmentFile=-/etc/default/rsyslog

# /etc/default/rsyslog
LOAD_IMTCP=on

Bash / non-systemd service environment

If rsyslog is started from a shell wrapper (e.g., SysV init or container entrypoint):

# enable (any of 1, true, on, yes will do)
export LOAD_IMTCP=on

# or disable
# export LOAD_IMTCP=off

RainerScript (rsyslog.conf)

# Load the module conditionally. If LOAD_IMTCP is unset/empty/0/false,
# the statement is disabled and the module is not loaded.
module(
  load="imtcp"
  config.enabled=`echo ${LOAD_IMTCP}`
)

# Start a TCP input only when enabled. This also works if you prefer
# to always load the module but gate the input itself.
input(
  type="imtcp"
  port="514"
  ruleset="in_tcp"
  config.enabled=`echo ${LOAD_IMTCP}`
)

ruleset(name="in_tcp") {
  action(type="omfile" file="/var/log/remote/tcp.log")
}

Accepted truthy value for config.enabled is on. Any other value, including no value, is treated as false.

Note

In containerized deployments, this pattern is often the simplest way to pass environment-style toggles into a static configuration. For example:

docker run --rm \
  -e LOAD_IMTCP=on \
  -v /path/to/rsyslog.conf:/etc/rsyslog.conf:ro \
  my-rsyslog-image

Including a file’s content¶

token = `cat /etc/rsyslog.d/token.txt`

Compatibility note for older releases¶

On versions before 8.2508.0, backticks did not support ${VAR} or adjacent text reliably. If you need to build a key=value pair, pre-compose it outside rsyslog and expand the already-complete string, e.g.:

In bash or init script:

export KAFKA_PASSWORD='supersecret'
export SASL_PWDPARAM="sasl.password=${KAFKA_PASSWORD}"

In rsyslog conf:

action(
  type="omkafka"
  broker=["kafka.example.com:9093"]
  confParam=[
    "security.protocol=SASL_SSL",
    "sasl.mechanism=SCRAM-SHA-512",
    "sasl.username=myuser",
    `echo $SASL_PWDPARAM`
  ]
)

Rationale¶

Backticks are intended to provide just enough functionality to customize configuration with external data while avoiding the complexity and risks of a general shell interpreter.

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

Contributing: Source & docs: rsyslog source project