The rsyslog include() object

The include() object is used to include configuration snippets stored elsewhere into the configuration.

New in version 8.33.0.

Note

This configuration option deprecates the older $IncludeConfig obsolete legacy format directive.

How it Works

The rsyslog include object is modelled after the usual “include” directive in programming and script languages (e.g. #include in C).

If you are not familiar with this, compare it to copy and paste: whenever rsyslog finds an include object, in copies the text from that include file at the exact position where the include is specified and removes the include text.

Now remember that rsyslog’s configuration statements are depending on the position inside the configuration. It is important if a statement occurs before or after another one. This is similar how other configuration files work and also the same concept that almost all programming and script languages have.

If you use includes in rsyslog, you must think about the position at which the include text is inserted. This is especially important if you use statements like stop. If given at the wrong spot, they will not work as intended.

If in doubt, or if you have issues, it probably is best NOT to use includes. This makes it far more obvious to understand what happens. Once solved, you may then change back to includes again.

Parameters

Note

Parameter names are case-insensitive.

Warning

Only one of the file or text parameters may be specified for each include() object.

file

Name of file to be included. May include wildcards, in which case all matching files are included (in order of file name sort order).

text

Text to be included. This is most useful when using backtick string constants.

mode

Affects how mising files are to be handled:

  • abort-if-missing, with rsyslog aborting when the file is not present
  • required (default), with rsyslog emitting an error message but otherwise continuing when the file is not present
  • optional, which means non-present files will be skipped without notice

Examples

Include a required file

include(file="/path/to/include.conf")

Note

Unless otherwise specified, files referenced by an include() object must be present, otherwise an error will be generated.

Include an optional file

The referenced file will be used if found, otherwise no errors or warnings will be generated regarding its absence.

include(
   file="/path/to/include.conf"
   mode="optional"
)

Include multiple files

include(file="/etc/rsyslog.d/*.conf")

Note

Unless otherwise specified, files referenced by an include() object must be present, otherwise an error will be generated.

Include an environment variable as configuration

include(text=`echo $ENV_VAR`)

Include a file specified via an environment variable

include(file=`echo $ENV_VAR`)

Note

Unless otherwise specified, files referenced by an include() object must be present, otherwise an error will be generated.

Include an optional file specified via an environment variable

include(
   file=`echo $ENV_VAR`
   mode="optional"
)

See also

Help with configuring/using Rsyslog:

  • Mailing list - best route for general questions
  • GitHub: rsyslog source project - detailed questions, reporting issues that are believed to be bugs with Rsyslog
  • Stack Exchange (View, Ask) - experimental support from rsyslog community

See also

Contributing to Rsyslog: