1 files changed, 55 insertions, 0 deletions

diff --git a/doc/rainerscript.html b/doc/rainerscript.html
index 7cbbfa9f..3eb08eff 100644
--- a/doc/rainerscript.html
+++ b/doc/rainerscript.html
@@ -34,6 +34,61 @@ 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>
+<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 and global variables. Local variables are local to the current message, but are
+NOT message properties (e.g. the "$!" all JSON property does not contain
+them). Global variables have a truely global scope and are NOT bound to
+a specifc message. Thus they can be used to persist values across
+multiple messages (for things like counters). Please note that rsyslog
+ensures proper synchronization for global variables (which also means
+they are slower than the others). HOWEVER, in a highly multithreaded
+configuration operations like<br>
+set $/var = $/var + 1;</br>
+are <b>not</b> atomic, so some updates to the counter variable may be missing. The
+classical sample for this is in a two-thread environment: Variable $/var is set
+to 1 at the start. Now the following happens in the following order:
+<ol>
+<li>Thread A reads 1 from $/var and adds 1, result is 2, but not yet stored
+<li>Thread B reads 1 from $/var and adds 1, result is 2, but not yet stored
+<li>Thread A stores its result of 2
+<li>Thread B stores its result of 2
+</ol>
+After this sequence, $/var contains the value two, which is probably not what was
+expected. Rsyslog does <b>not</b> provide looking primitives for individual variables,
+as this can lead to serious configuration problems if not used 100% correctly.
+However, rsyslog provides (or will in the future provide) special function which
+provide guaranteed atomic updates (in the sample, the end result would be three
+no matter what the scheduling order is).
+<p>Only message json (CEE/Lumberjack) properties can be modified by
+the "set" and "unset" statements, not any other message property. Obviously,
+local and global 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. Similarly,
+global variables start with "$/".
+<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 similar global variables is named "$/path1!path2!varname".
+The bang, slash, 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>
 <h2>Expressions</h2>
 The language supports arbitrary complex expressions. All usual
 operators are supported. The precedence of operations is as follows