mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-16 20:20:41 +01:00
added some user doc on RainerScript
This commit is contained in:
Rainer Gerhards
parent
b33a62b92c
commit
f22d142a53
@ -38,6 +38,7 @@ html_files = \
|
||||
queueWorkerLogic.jpg \
|
||||
queueWorkerLogic_small.jpg \
|
||||
rainerscript.html \
|
||||
rscript_abnf.html \
|
||||
rsconf1_actionexeconlywhenpreviousissuspended.html \
|
||||
rsconf1_actionresumeinterval.html \
|
||||
rsconf1_allowedsender.html \
|
||||
|
||||
@ -110,7 +110,11 @@ quite a while. Config file changes are required and some command line options do
|
||||
no longer work due to the new design.</p><p>On <span style="font-weight: bold;">January, 31st 2008</span>
|
||||
the new massively-multithreaded queue engine was released for the first
|
||||
time. It was a major milestone, implementing a feature I dreamed of for
|
||||
more than a year.</p><p>Be sure to visit Rainer's <a href="http://rgerhards.blogspot.com/">syslog blog</a>
|
||||
more than a year.</p><p>End of <span style="font-weight: bold;">February 2008</span>
|
||||
saw the first note about RainerScript, a way to configure rsyslogd via
|
||||
a script-language like configuration format. This effort evolved out of
|
||||
the need to have complex expression support, which was also the first
|
||||
use case.</p><p>Be sure to visit Rainer's <a href="http://rgerhards.blogspot.com/">syslog blog</a>
|
||||
to get some more insight into the development and futures of rsyslog and syslog in general.
|
||||
Don't be shy to post to either the blog or the
|
||||
<a href="http://www.rsyslog.com/PNphpBB2.phtml">rsyslog forums</a>.</p>
|
||||
@ -118,4 +122,4 @@ Don't be shy to post to either the blog or the
|
||||
<ul>
|
||||
<li><a href="http://www.rsyslog.com/Topic4.phtml">the rsyslog change log</a></li>
|
||||
</ul>
|
||||
</body></html>
|
||||
</body></html>
|
||||
@ -1,37 +1,57 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html><head>
|
||||
<meta http-equiv="Content-Language" content="en"><title>RainerScript ABNF</title>
|
||||
<meta http-equiv="Content-Language" content="en"><title>RainerScript</title>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<h1>RainerScript ABNF</h1>
|
||||
<p>This is the formal definition of RainerScript, as supported by
|
||||
rsyslog configuration. Please note that this currently is working
|
||||
document and the actual implementation may be quite different.</p>
|
||||
<p>The
|
||||
first glimpse of RainerScript will be available as part of rsyslog
|
||||
3.12.0 expression support. However, the 3.12. series of rsyslog will
|
||||
have a partial script implementaiton, which will not necessariy be
|
||||
compatible with the later full implementation. So if you use it, be
|
||||
prepared for some config file changes as RainerScript evolves.</p>
|
||||
<p>C-like comments (/* some comment */) are supported in all pure
|
||||
RainerScript lines. However, legacy-mapped lines do not support them.
|
||||
All lines support the hash mark "#" as a comment initiator. Everything
|
||||
between the hash and the end of line is a comment (just like // in C++
|
||||
and many other languages).</p>
|
||||
<h2>Formal Definition</h2>
|
||||
<p>Below is the formal language definitionin ABNF (RFC 2234)
|
||||
format: <br>
|
||||
</p>
|
||||
<pre>; <span style="font-weight: bold;">all of this is a working document and may change!</span> -- rgerhards, 2008-02-24<br><br>script := *stmt<br>stmt := (if_stmt / block / vardef / run_s / load_s)<br>vardef := "var" ["scope" = ("global" / "event")] <br>block := "begin" stmt "end"<br>load_s := "load" constraint ("module") modpath params ; load mod only if expr is true<br>run_s := "run" constraint ("input") name<br>constraint:= "if" expr ; constrains some one-time commands<br>modpath := expr<br>params := ["params" *1param *("," param) "endparams"]<br>param := paramname) "=" expr<br>paramname := [*(obqualifier ".") name]<br>modpath:= ; path to module<br>?line? := cfsysline / cfli<br>cfsysline:= BOL "$" *char EOL ; how to handle the first line? (no EOL in front!)<br>BOL := ; Begin of Line - implicitely set on file beginning and after each EOL<br>EOL := 0x0a ;LF<br>if_stmt := "if" expr "then"<br>old_filter:= BOL facility "." severity ; no whitespace allowed between BOL and facility!<br>facility := "*" / "auth" / "authpriv" / "cron" / "daemon" / "kern" / "lpr" / <br> "mail" / "mark" / "news" / "security" / "syslog" / "user" / "uucp" / <br> "local0" .. "local7" / "mark"<br> ; The keyword security should not be used anymore<br> ; mark is just internal<br>severity := TBD ; not really relevant in this context<br><br>; and now the actual expression<br>expr := e_and *("or" e_and)<br>e_and := e_cmp *("and" e_cmp)<br>e_cmp := val 0*1(cmp_op val)<br>val := term *(("+" / "-" / "&") term)<br>term := factor *(("*" / "/" / "%") factor)<br>factor := ["not"] ["-"] terminal<br>terminal := var / constant / function / ( "(" expr ")" )<br>function := name "(" *("," expr) ")"<br>var := "$" varname<br>varname := msgvar / sysvar<br>msgvar := name<br>sysvar := "$" name<br>name := alpha *(alnum)<br>constant := string / number<br>string := simpstr / tplstr ; tplstr will be implemented in next phase<br>simpstr := "'" *char "'" ; use your imagination for char ;)<br>tplstr := '"' template '"' ; not initially implemented<br>number := ["-"] 1*digit ; 0nn = octal, 0xnn = hex, nn = decimal<br>cmp_op := "==" / "!=" / "<>" / "<" / ">" / "<=" / ">=" / "contains" / "startswith"<br>digit := %x30-39<br>alpha := "a" ... "z" # all letters<br>alnum :* alpha / digit / "_"<br></pre>
|
||||
<h2>Samples</h2>
|
||||
<p>Some samples of RainerScript:</p><p>define function IsLinux<br>begin<br> if $environ contains "linux" then return true else return false<br>end</p><p>load if IsLinux() 'imklog.so' params name='klog' endparams /* load klog under linux only */<br>run if IsLinux() input 'klog'<br>load 'ommysql.so'</p><p>if $message contains "error" then<br> action<br> type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,<br> action.dbname='events', action.dbuser='uid',<br>
|
||||
[?action.template='templatename'?] or [?action.sql='insert into
|
||||
table... values('&$facility&','&$severity&...?]<br> endaction<br><br>... or ...</p><p>define action writeMySQL<br> type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,<br> action.dbname='events', action.dbuser='uid',<br> [?action.template='templatename'?] or [?action.sql='insert into table... values('<span style="font-family: monospace;"> &</span> $facility & ',' & $severity &...?]<br> endaction</p><p>if $message contains "error" then action writeMySQL</p><p>ALTERNATE APPROACH</p><p>define function IsLinux(<br> if $environ contains "linux" then return true else return false<br>)</p><p>load if IsLinux() 'imklog.so' params name='klog' endparams /* load klog under linux only */<br>run if IsLinux() input 'klog'<br>load 'ommysql.so'</p><p>if $message contains "error" then<br> action(<br> type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,<br> action.dbname='events', action.dbuser='uid',<br>
|
||||
[?action.template='templatename'?] or [?action.sql='insert into
|
||||
table... values('&$facility&','&$severity&...?]<br> )<br><br>... or ...</p><p>define action writeMySQL(<br> type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,<br> action.dbname='events', action.dbuser='uid',<br>
|
||||
[?action.template='templatename'?] or [?action.sql='insert into
|
||||
table... values('&$facility&','&$severity&...?]<br> )</p><p>if $message contains "error" then action writeMySQL(action.dbname='differentDB')</p><p></p><p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
|
||||
<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>
|
||||
<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.
|
||||
<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>
|
||||
|
||||
43
doc/rscript_abnf.html
Normal file
43
doc/rscript_abnf.html
Normal file
@ -0,0 +1,43 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html><head>
|
||||
<meta http-equiv="Content-Language" content="en"><title>RainerScript ABNF</title>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<h1>RainerScript ABNF</h1>
|
||||
<p>This is the formal definition of RainerScript, as supported by
|
||||
rsyslog configuration. Please note that this currently is working
|
||||
document and the actual implementation may be quite different.</p>
|
||||
<p>The
|
||||
first glimpse of RainerScript will be available as part of rsyslog
|
||||
3.12.0 expression support. However, the 3.12. series of rsyslog will
|
||||
have a partial script implementaiton, which will not necessariy be
|
||||
compatible with the later full implementation. So if you use it, be
|
||||
prepared for some config file changes as RainerScript evolves.</p>
|
||||
<p>C-like comments (/* some comment */) are supported in all pure
|
||||
RainerScript lines. However, legacy-mapped lines do not support them.
|
||||
All lines support the hash mark "#" as a comment initiator. Everything
|
||||
between the hash and the end of line is a comment (just like // in C++
|
||||
and many other languages).</p>
|
||||
<h2>Formal Definition</h2>
|
||||
<p>Below is the formal language definitionin ABNF (RFC 2234)
|
||||
format: <br>
|
||||
</p>
|
||||
<pre>; <span style="font-weight: bold;">all of this is a working document and may change!</span> -- rgerhards, 2008-02-24<br><br>script := *stmt<br>stmt := (if_stmt / block / vardef / run_s / load_s)<br>vardef := "var" ["scope" = ("global" / "event")] <br>block := "begin" stmt "end"<br>load_s := "load" constraint ("module") modpath params ; load mod only if expr is true<br>run_s := "run" constraint ("input") name<br>constraint:= "if" expr ; constrains some one-time commands<br>modpath := expr<br>params := ["params" *1param *("," param) "endparams"]<br>param := paramname) "=" expr<br>paramname := [*(obqualifier ".") name]<br>modpath:= ; path to module<br>?line? := cfsysline / cfli<br>cfsysline:= BOL "$" *char EOL ; how to handle the first line? (no EOL in front!)<br>BOL := ; Begin of Line - implicitely set on file beginning and after each EOL<br>EOL := 0x0a ;LF<br>if_stmt := "if" expr "then"<br>old_filter:= BOL facility "." severity ; no whitespace allowed between BOL and facility!<br>facility := "*" / "auth" / "authpriv" / "cron" / "daemon" / "kern" / "lpr" / <br> "mail" / "mark" / "news" / "security" / "syslog" / "user" / "uucp" / <br> "local0" .. "local7" / "mark"<br> ; The keyword security should not be used anymore<br> ; mark is just internal<br>severity := TBD ; not really relevant in this context<br><br>; and now the actual expression<br>expr := e_and *("or" e_and)<br>e_and := e_cmp *("and" e_cmp)<br>e_cmp := val 0*1(cmp_op val)<br>val := term *(("+" / "-" / "&") term)<br>term := factor *(("*" / "/" / "%") factor)<br>factor := ["not"] ["-"] terminal<br>terminal := var / constant / function / ( "(" expr ")" )<br>function := name "(" *("," expr) ")"<br>var := "$" varname<br>varname := msgvar / sysvar<br>msgvar := name<br>sysvar := "$" name<br>name := alpha *(alnum)<br>constant := string / number<br>string := simpstr / tplstr ; tplstr will be implemented in next phase<br>simpstr := "'" *char "'" ; use your imagination for char ;)<br>tplstr := '"' template '"' ; not initially implemented<br>number := ["-"] 1*digit ; 0nn = octal, 0xnn = hex, nn = decimal<br>cmp_op := "==" / "!=" / "<>" / "<" / ">" / "<=" / ">=" / "contains" / "startswith"<br>digit := %x30-39<br>alpha := "a" ... "z" # all letters<br>alnum :* alpha / digit / "_"<br></pre>
|
||||
<h2>Samples</h2>
|
||||
<p>Some samples of RainerScript:</p><p>define function IsLinux<br>begin<br> if $environ contains "linux" then return true else return false<br>end</p><p>load if IsLinux() 'imklog.so' params name='klog' endparams /* load klog under linux only */<br>run if IsLinux() input 'klog'<br>load 'ommysql.so'</p><p>if $message contains "error" then<br> action<br> type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,<br> action.dbname='events', action.dbuser='uid',<br>
|
||||
[?action.template='templatename'?] or [?action.sql='insert into
|
||||
table... values('&$facility&','&$severity&...?]<br> endaction<br><br>... or ...</p><p>define action writeMySQL<br> type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,<br> action.dbname='events', action.dbuser='uid',<br> [?action.template='templatename'?] or [?action.sql='insert into table... values('<span style="font-family: monospace;"> &</span> $facility & ',' & $severity &...?]<br> endaction</p><p>if $message contains "error" then action writeMySQL</p><p>ALTERNATE APPROACH</p><p>define function IsLinux(<br> if $environ contains "linux" then return true else return false<br>)</p><p>load if IsLinux() 'imklog.so' params name='klog' endparams /* load klog under linux only */<br>run if IsLinux() input 'klog'<br>load 'ommysql.so'</p><p>if $message contains "error" then<br> action(<br> type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,<br> action.dbname='events', action.dbuser='uid',<br>
|
||||
[?action.template='templatename'?] or [?action.sql='insert into
|
||||
table... values('&$facility&','&$severity&...?]<br> )<br><br>... or ...</p><p>define action writeMySQL(<br> type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,<br> action.dbname='events', action.dbuser='uid',<br>
|
||||
[?action.template='templatename'?] or [?action.sql='insert into
|
||||
table... values('&$facility&','&$severity&...?]<br> )</p><p>if $message contains "error" then action writeMySQL(action.dbname='differentDB')</p><p></p><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 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>
|
||||
Loading…
x
Reference in New Issue
Block a user