# 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 missing 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`:

- Source project: rsyslog project README.

- Documentation: rsyslog-doc project README

Copyright 2008-2020 Rainer Gerhards (Großrinderfeld), and Others.