/usr/share/doc/rsyslog-doc/html/rainerscript.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 &amp;).
&nbsp;However, all type conversions are automatically done by the
script interpreter when there is need to do so.<br>
<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>+, -, &amp; (string concatenation)</li><li>==, !=, &lt;&gt;, &lt;, &gt;, &lt;=, &gt;=, 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 "&lt;&gt;". 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 &lt;&gt; 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).
</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 &copy; 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>
rsyslog-doc 7.4.4-1ubuntu2 / usr / share / doc / rsyslog-doc / html / rainerscript.html
