1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
****************************
The rsyslog include() object
****************************
The ``include()`` object is used to include configuration snippets
stored elsewhere into the configuration.
.. versionadded:: 8.33.0
.. note::
This configuration option deprecates the older ``$IncludeConfig``
|FmtObsoleteName| 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
-----------------------
.. code-block:: none
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.
.. code-block:: none
:emphasize-lines: 3
include(
file="/path/to/include.conf"
mode="optional"
)
Include multiple files
----------------------
.. code-block:: none
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
------------------------------------------------
.. code-block:: none
include(text=`echo $ENV_VAR`)
Include a file specified via an environment variable
----------------------------------------------------
.. code-block:: none
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
--------------------------------------------------------------
.. code-block:: none
:emphasize-lines: 3
include(
file=`echo $ENV_VAR`
mode="optional"
)
|
