mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-21 12:30:42 +01:00
165 lines
9.5 KiB
HTML
165 lines
9.5 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html><head>
|
|
<meta http-equiv="Content-Language" content="en"><title>RainerScript</title>
|
|
|
|
</head>
|
|
<body>
|
|
<h1>RainerScript</h1>
|
|
<p><b>RainerScript is a scripting language specifically
|
|
designed and well-suited
|
|
for processing network events and configuring event processors</b>
|
|
(with the most prominent sample being syslog). While RainerScript is
|
|
theoritically usable with various softwares, it currently is being
|
|
used, and developed for, rsyslog. Please note that RainerScript may not
|
|
be abreviated as rscript, because that's somebody elses trademark.</p>
|
|
<p>RainerScript is currently under development. It has its first
|
|
appearance in rsyslog 3.12.0, where it provides complex expression
|
|
support. However, this is only a very partial implementatio of the
|
|
scripting language. Due to technical restrictions, the final
|
|
implementation will have a slightly different syntax. So while you are
|
|
invited to use the full power of expresssions, you unfortunatley need
|
|
to be prepared to change your configuration files at some later points.
|
|
Maintaining backwards-compatibility at this point would cause us to
|
|
make too much compromise. Defering the release until everything is
|
|
perfect is also not a good option. So use your own judgement.</p>
|
|
<p>A formal definition of the language can be found in <a href="rscript_abnf.html">RainerScript ABNF</a>. The
|
|
rest of this document describes the language from the user's point of
|
|
view. Please note that this doc is also currently under development and
|
|
can (and will) probably improve as time progresses. If you have
|
|
questions, use the rsyslog forum. Feedback is also always welcome.</p>
|
|
<h2>Data Types</h2>
|
|
RainerScript is a typeless language. That doesn't imply you don't need
|
|
to care about types. Of course, expressions like "A" + "B" will not
|
|
return a valid result, as you can't really add two letters (to
|
|
concatenate them, use the concatenation operator &).
|
|
However, all type conversions are automatically done by the
|
|
script interpreter when there is need to do so.<br>
|
|
<h3>Constant Strings</h3>
|
|
<p>String constants are necessary in many places: comparisons,
|
|
configuration parameter values and function arguments, to name a
|
|
few important ones.
|
|
<p>In constant strings, special characters are escape by prepending a
|
|
backslash in front of them -- just in the same way this is done in the
|
|
C programming language or PHP.
|
|
<p>If in doubt how to properly escape, use the
|
|
<a href="http://www.rsyslog.com/rainerscript-constant-string-escaper/">RainerScript
|
|
String Escape Online Tool</a>.
|
|
<h2>Variable (Property) types</h2>
|
|
<p>All rsyslog properties (see the <a href="property_replacer.html">property
|
|
replacer</a> page for a list) can be used in RainerScript. In addition, it also
|
|
supports local variables. Local variables are local to the current message, but are
|
|
NOT message properties (e.g. the "$!" all JSON property does not contain
|
|
them).
|
|
<p>Only message json (CEE/Lumberjack) properties can be modified by
|
|
the "set" and "unset" statements, not any other message property. Obviously,
|
|
local variables are also modifieable.
|
|
<p>Message JSON property names start with "$!" where the bang character
|
|
represents the root.
|
|
<p>Local variables names start with "$.", where the dot denotes the root.
|
|
<p>Both JSON properties as well as local variables may contain an arbitrary
|
|
deep path before the final element. The bang character is always used as path
|
|
separator, no matter if it is a message property or a local variable. For example
|
|
"$!path1!path2!varname" is a three-level deep message property where as
|
|
the very similar looking "$.path1!path2!varname" specifies a three-level
|
|
deep local variable.
|
|
The bang or dot character immediately following the
|
|
dollar sign is used by rsyslog to separate the different types.
|
|
<h2>configuration objects</h2>
|
|
<h3>main_queue()</h3>
|
|
<p><i>This object is available since 7.5.3.</i>
|
|
This permits to specify parameters for the main message queue. Note that
|
|
only <a href="queue_parameters.html">queue-parameters</a> are permitted for this
|
|
config object. This permits to set the same options like in ruleset and action
|
|
queues. A special statement is needed for the main queue, because it is a
|
|
different object and cannot be configured via any other object.
|
|
<p>Note that when the main_queue() object is configured, the legacy
|
|
$MainMsgQ... statements are ignored.
|
|
<p>Example:</p>
|
|
<textarea rows="2" cols="60">main_queue(queue.size="100000" queue.type="LinkedList")
|
|
</textarea>
|
|
<h3>action()</h3>
|
|
The <a href="rsyslog_conf_actions.html">action</a> object is the primary
|
|
means of describing actions to be carried out.
|
|
<h3>global()</h3>
|
|
<p>This is used to set global configuration parameters. For details, please
|
|
see the <a href="global.html">rsyslog global configuration object</a>.
|
|
<h2>Expressions</h2>
|
|
The language supports arbitrary complex expressions. All usual
|
|
operators are supported. The precedence of operations is as follows
|
|
(with operations being higher in the list being carried out before
|
|
those lower in the list, e.g. multiplications are done before additions.<br>
|
|
<ul>
|
|
<li>expressions in parenthesis</li><li>not, unary minus</li><li>*, /, % (modulus, as in C)</li><li>+, -, & (string concatenation)</li><li>==, !=, <>, <, >, <=, >=, contains (strings!), startswith (strings!)</li><li>and</li><li>or</li>
|
|
</ul>For example, "not a == b" probably returns not what you intended.
|
|
The script processor will first evaluate "not a" and then compare the
|
|
resulting boolean to the value of b. What you probably intended to do
|
|
is "not (a == b)". And if you just want to test for inequality, we
|
|
highly suggest to use "!=" or "<>". Both are exactly the same and
|
|
are provided so that you can pick whichever you like best. So inquality
|
|
of a and b should be tested as "a <> b". The "not" operator
|
|
should be reserved to cases where it actually is needed to form a
|
|
complex boolean expression. In those cases, parenthesis are highly
|
|
recommended.
|
|
<h2>Lookup Tables</h2>
|
|
<p><a href="lookup_tables.html">Lookup tables</a> are a powerful construct
|
|
to obtain "class" information based on message content (e.g. to build
|
|
log file names for different server types, departments or remote
|
|
offices).
|
|
<h2>Functions</h2>
|
|
<p>RainerScript supports a currently quite limited set of functions:
|
|
<ul>
|
|
<li>getenv(str) - like the OS call, returns the value of the environment
|
|
variable, if it exists. Returns an empty string if it does not exist.
|
|
<li>strlen(str) - returns the length of the provided string
|
|
<li>tolower(str) - converts the provided string into lowercase
|
|
<li>cstr(expr) - converts expr to a string value
|
|
<li>cnum(expr) - converts expr to a number (integer)
|
|
<li>re_match(expr, re) - returns 1, if expr matches re, 0 otherwise
|
|
<li>re_extract(expr, re, match, submatch, no-found) - extracts
|
|
data from a string (property) via a regular expression match.
|
|
POSIX ERE regular expressions are used. The variable "match" contains
|
|
the number of the match to use. This permits to pick up more than the
|
|
first expression match. Submatch is the submatch to match (max 50 supported).
|
|
The "no-found" parameter specifies which string is to be returned in case when
|
|
the regular expression is not found. Note that match and submatch start with
|
|
zero. It currently is not possible to extract more than one submatch with
|
|
a single call.
|
|
<li>field(str, delim, matchnbr) - returns a field-based substring. str is the string
|
|
to search, delim is the delimiter and matchnbr is the match to search
|
|
for (the first match starts at 1). This works similar as the field based
|
|
property-replacer option.
|
|
Versions prior to 7.3.7 only support a single character as delimiter character.
|
|
Starting with version 7.3.7, a full string can be used as delimiter. If a single
|
|
character is being used as delimiter, delim is the numerical ascii value of the
|
|
field delimiter character (so that non-printable characters can by specified). If a
|
|
string is used as delmiter, a multi-character string (e.g. "#011") is to be
|
|
specified. Samples:<br>
|
|
set $!usr!field = field($msg, 32, 3); -- the third field, delimited by space<br>
|
|
set $!usr!field = field($msg, "#011", 3); -- the third field, delmited by "#011"<br>
|
|
Note that when a single character is specified as string [field($msg, ",", 3)] a
|
|
string-based extraction is done, which is more performance intense than the
|
|
equivalent single-character [field($msg, 44 ,3)] extraction.
|
|
<li>prifilt(constant) - mimics a traditional PRI-based filter (like "*.*" or
|
|
"mail.info"). The traditional filter string must be given as a <b>constant string</b>.
|
|
Dynamic string evaluation is not permitted (for performance reasons).
|
|
<li>exec_template(templateName) -- executes a template and returns the string generated
|
|
by it. Note that templateName must be a constant string. This is primarily for performance
|
|
reasons. If there is a valid use case for dynamic template names, please let us know
|
|
and we will re-consider the decision. TemplateName can be any template name, including the
|
|
predefined ones.
|
|
</ul>
|
|
<p>The following example can be used to build a dynamic filter based on some environment
|
|
variable:
|
|
<pre>
|
|
if $msg contains getenv('TRIGGERVAR') then /path/to/errfile
|
|
</pre>
|
|
<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
|
|
[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
|
|
<p><font size="2">This documentation is part of the
|
|
<a href="http://www.rsyslog.com/">rsyslog</a>
|
|
project.<br>
|
|
Copyright © 2008-2013 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
|
|
<a href="http://www.adiscon.com/">Adiscon</a>.
|
|
Released under the GNU GPL version 3 or higher.</font></p>
|
|
</body></html>
|