File: //usr/share/doc/rsyslog/html/rainerscript/include.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The rsyslog include() object — rsyslog 8.2006.0 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/rsyslog.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '8.2006.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Actions" href="../configuration/actions.html" />
<link rel="prev" title="global() configuration object" href="global.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../configuration/actions.html" title="Actions"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="global.html" title="global() configuration object"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">rsyslog 8.2006.0 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../configuration/index.html" >Configuration</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" accesskey="U">RainerScript</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="the-rsyslog-include-object">
<h1>The rsyslog include() object<a class="headerlink" href="#the-rsyslog-include-object" title="Permalink to this headline">¶</a></h1>
<p>The <code class="docutils literal"><span class="pre">include()</span></code> object is used to include configuration snippets
stored elsewhere into the configuration.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 8.33.0.</span></p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This configuration option deprecates the older <code class="docutils literal"><span class="pre">$IncludeConfig</span></code>
<code class="docutils literal"><span class="pre">obsolete</span> <span class="pre">legacy</span></code> format directive.</p>
</div>
<div class="section" id="how-it-works">
<h2>How it Works<a class="headerlink" href="#how-it-works" title="Permalink to this headline">¶</a></h2>
<p>The rsyslog include object is modelled after the usual “include” directive
in programming and script languages (e.g. #include in C).</p>
<p>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.</p>
<p>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.</p>
<p>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 <cite>stop</cite>. If given at the wrong spot, they will not work as
intended.</p>
<p>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.</p>
</div>
<div class="section" id="parameters">
<h2>Parameters<a class="headerlink" href="#parameters" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Parameter names are case-insensitive.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Only one of the <code class="docutils literal"><span class="pre">file</span></code> or <code class="docutils literal"><span class="pre">text</span></code> parameters may be specified for each
<code class="docutils literal"><span class="pre">include()</span></code> object.</p>
</div>
<div class="section" id="file">
<h3>file<a class="headerlink" href="#file" title="Permalink to this headline">¶</a></h3>
<p>Name of file to be included. May include wildcards, in which case all
matching files are included (in order of file name sort order).</p>
</div>
<div class="section" id="text">
<h3>text<a class="headerlink" href="#text" title="Permalink to this headline">¶</a></h3>
<p>Text to be included. This is most useful when using backtick string
constants.</p>
</div>
<div class="section" id="mode">
<h3>mode<a class="headerlink" href="#mode" title="Permalink to this headline">¶</a></h3>
<p>Affects how missing files are to be handled:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">abort-if-missing</span></code>, with rsyslog aborting when the file is not present</li>
<li><code class="docutils literal"><span class="pre">required</span></code> <em>(default)</em>, with rsyslog emitting an error message but otherwise
continuing when the file is not present</li>
<li><code class="docutils literal"><span class="pre">optional</span></code>, which means non-present files will be skipped without notice</li>
</ul>
</div>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="section" id="include-a-required-file">
<h3>Include a required file<a class="headerlink" href="#include-a-required-file" title="Permalink to this headline">¶</a></h3>
<div class="highlight-none"><div class="highlight"><pre><span></span>include(file="/path/to/include.conf")
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Unless otherwise specified, files referenced by an <code class="docutils literal"><span class="pre">include()</span></code> object
must be present, otherwise an error will be generated.</p>
</div>
</div>
<div class="section" id="include-an-optional-file">
<h3>Include an optional file<a class="headerlink" href="#include-an-optional-file" title="Permalink to this headline">¶</a></h3>
<p>The referenced file will be used if found, otherwise no errors or warnings
will be generated regarding its absence.</p>
<div class="highlight-none"><div class="highlight"><pre><span></span>include(
file="/path/to/include.conf"
<span class="hll"> mode="optional"
</span>)
</pre></div>
</div>
</div>
<div class="section" id="include-multiple-files">
<h3>Include multiple files<a class="headerlink" href="#include-multiple-files" title="Permalink to this headline">¶</a></h3>
<div class="highlight-none"><div class="highlight"><pre><span></span>include(file="/etc/rsyslog.d/*.conf")
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Unless otherwise specified, files referenced by an <code class="docutils literal"><span class="pre">include()</span></code> object
must be present, otherwise an error will be generated.</p>
</div>
</div>
<div class="section" id="include-an-environment-variable-as-configuration">
<h3>Include an environment variable as configuration<a class="headerlink" href="#include-an-environment-variable-as-configuration" title="Permalink to this headline">¶</a></h3>
<div class="highlight-none"><div class="highlight"><pre><span></span>include(text=`echo $ENV_VAR`)
</pre></div>
</div>
</div>
<div class="section" id="include-a-file-specified-via-an-environment-variable">
<h3>Include a file specified via an environment variable<a class="headerlink" href="#include-a-file-specified-via-an-environment-variable" title="Permalink to this headline">¶</a></h3>
<div class="highlight-none"><div class="highlight"><pre><span></span>include(file=`echo $ENV_VAR`)
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Unless otherwise specified, files referenced by an <code class="docutils literal"><span class="pre">include()</span></code> object
must be present, otherwise an error will be generated.</p>
</div>
</div>
<div class="section" id="include-an-optional-file-specified-via-an-environment-variable">
<h3>Include an optional file specified via an environment variable<a class="headerlink" href="#include-an-optional-file-specified-via-an-environment-variable" title="Permalink to this headline">¶</a></h3>
<div class="highlight-none"><div class="highlight"><pre><span></span>include(
file=`echo $ENV_VAR`
<span class="hll"> mode="optional"
</span>)
</pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p>Help with configuring/using <code class="docutils literal"><span class="pre">Rsyslog</span></code>:</p>
<ul class="last simple">
<li><a class="reference external" href="http://lists.adiscon.net/mailman/listinfo/rsyslog">Mailing list</a> - best route for general questions</li>
<li>GitHub: <a class="reference external" href="https://github.com/rsyslog/rsyslog/">rsyslog source project</a> - detailed questions, reporting issues
that are believed to be bugs with <code class="docutils literal"><span class="pre">Rsyslog</span></code></li>
<li>Stack Exchange (<a class="reference external" href="https://stackexchange.com/filters/327462/rsyslog">View</a>, <a class="reference external" href="https://serverfault.com/questions/ask?tags=rsyslog">Ask</a>)
- experimental support from rsyslog community</li>
</ul>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p>Contributing to <code class="docutils literal"><span class="pre">Rsyslog</span></code>:</p>
<ul class="last simple">
<li>Source project: <a class="reference external" href="https://github.com/rsyslog/rsyslog/blob/master/README.md">rsyslog project README</a>.</li>
<li>Documentation: <a class="reference external" href="https://github.com/rsyslog/rsyslog-doc/blob/master/README.md">rsyslog-doc project README</a></li>
</ul>
</div>
<p>Copyright 2008-2020 <a class="reference external" href="https://rainer.gerhards.net/">Rainer Gerhards</a>
(<a class="reference external" href="https://www.rainer-gerhards.de/grossrinderfeld/">Großrinderfeld</a>),
and Others.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">The rsyslog include() object</a><ul>
<li><a class="reference internal" href="#how-it-works">How it Works</a></li>
<li><a class="reference internal" href="#parameters">Parameters</a><ul>
<li><a class="reference internal" href="#file">file</a></li>
<li><a class="reference internal" href="#text">text</a></li>
<li><a class="reference internal" href="#mode">mode</a></li>
</ul>
</li>
<li><a class="reference internal" href="#examples">Examples</a><ul>
<li><a class="reference internal" href="#include-a-required-file">Include a required file</a></li>
<li><a class="reference internal" href="#include-an-optional-file">Include an optional file</a></li>
<li><a class="reference internal" href="#include-multiple-files">Include multiple files</a></li>
<li><a class="reference internal" href="#include-an-environment-variable-as-configuration">Include an environment variable as configuration</a></li>
<li><a class="reference internal" href="#include-a-file-specified-via-an-environment-variable">Include a file specified via an environment variable</a></li>
<li><a class="reference internal" href="#include-an-optional-file-specified-via-an-environment-variable">Include an optional file specified via an environment variable</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="global.html"
title="previous chapter">global() configuration object</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../configuration/actions.html"
title="next chapter">Actions</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/rainerscript/include.rst.txt"
rel="nofollow">Show Source</a></li>
<li><a href="https://github.com/rsyslog/rsyslog-doc/edit/master/source/rainerscript/include.rst"
rel="nofollow">Edit on GitHub</a></li>
</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../configuration/actions.html" title="Actions"
>next</a> |</li>
<li class="right" >
<a href="global.html" title="global() configuration object"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">rsyslog 8.2006.0 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../configuration/index.html" >Configuration</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" >RainerScript</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
</div>
</body>
</html>