From f22d142a538deaec341317464626c4dece41be7a Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Tue, 26 Feb 2008 09:05:07 +0000 Subject: added some user doc on RainerScript --- doc/Makefile.am | 1 + doc/history.html | 8 ++++-- doc/rainerscript.html | 78 ++++++++++++++++++++++++++++++++------------------- doc/rscript_abnf.html | 43 ++++++++++++++++++++++++++++ 4 files changed, 99 insertions(+), 31 deletions(-) create mode 100644 doc/rscript_abnf.html (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index 31481a96..aa4e8a7d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 \ diff --git a/doc/history.html b/doc/history.html index ba6b6fc6..43db0852 100644 --- a/doc/history.html +++ b/doc/history.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.

On January, 31st 2008 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.

Be sure to visit Rainer's syslog blog +more than a year.

End of February 2008 +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.

Be sure to visit Rainer's syslog blog 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 rsyslog forums.

@@ -118,4 +122,4 @@ Don't be shy to post to either the blog or the

the rsyslog change log

- + \ No newline at end of file diff --git a/doc/rainerscript.html b/doc/rainerscript.html index 6ffd4c37..ef0e41cb 100644 --- a/doc/rainerscript.html +++ b/doc/rainerscript.html @@ -1,37 +1,57 @@ -RainerScript ABNF +RainerScript -

RainerScript ABNF

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.

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.

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).

Formal Definition

Below is the formal language definitionin ABNF (RFC 2234) -format:
-

; all of this is a working document and may change! -- rgerhards, 2008-02-24

script    := *stmt
stmt      := (if_stmt / block / vardef / run_s / load_s)
vardef    := "var" ["scope" = ("global" / "event")] 
block     := "begin" stmt "end"
load_s    := "load" constraint ("module") modpath params ; load mod only if expr is true
run_s     := "run" constraint ("input") name
constraint:= "if" expr ; constrains some one-time commands
modpath   := expr
params    := ["params" *1param *("," param) "endparams"]
param     := paramname) "=" expr
paramname := [*(obqualifier ".") name]
modpath:= ; path to module
?line? := cfsysline / cfli
cfsysline:= BOL "$" *char EOL ; how to handle the first line? (no EOL in front!)
BOL := ; Begin of Line - implicitely set on file beginning and after each EOL
EOL := 0x0a ;LF
if_stmt := "if" expr "then"
old_filter:= BOL facility "." severity ; no whitespace allowed between BOL and facility!
facility := "*" / "auth" / "authpriv" / "cron" / "daemon" / "kern" / "lpr" / 
 "mail" / "mark" / "news" / "security" / "syslog" / "user" / "uucp" / 
 "local0" .. "local7" / "mark"
	; The keyword security should not be used anymore
	; mark is just internal
severity := TBD ; not really relevant in this context

; and now the actual expression
expr := e_and *("or" e_and)
e_and := e_cmp *("and" e_cmp)
e_cmp := val 0*1(cmp_op val)
val := term *(("+" / "-" / "&") term)
term := factor *(("*" / "/" / "%") factor)
factor := ["not"] ["-"] terminal
terminal := var / constant / function / ( "(" expr ")" )
function := name "(" *("," expr) ")"
var := "$" varname
varname := msgvar / sysvar
msgvar := name
sysvar := "$" name
name := alpha *(alnum)
constant := string / number
string := simpstr / tplstr ; tplstr will be implemented in next phase
simpstr := "'" *char "'" ; use your imagination for char ;)
tplstr := '"' template '"' ; not initially implemented
number := ["-"] 1*digit ; 0nn = octal, 0xnn = hex, nn = decimal
cmp_op := "==" / "!=" / "<>" / "<" / ">" / "<=" / ">=" / "contains" / "startswith"
digit := %x30-39
alpha := "a" ... "z" # all letters
alnum :* alpha / digit / "_"

Samples

Some samples of RainerScript:

define function IsLinux
begin
if $environ contains "linux" then return true else return false
end

load if IsLinux() 'imklog.so' params name='klog' endparams /* load klog under linux only */
run if IsLinux() input 'klog'
load 'ommysql.so'

if $message contains "error" then
action
type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,
action.dbname='events', action.dbuser='uid',
- [?action.template='templatename'?] or [?action.sql='insert into -table... values('&$facility&','&$severity&...?]
endaction

... or ...

define action writeMySQL
type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,
action.dbname='events', action.dbuser='uid',
[?action.template='templatename'?] or [?action.sql='insert into table... values(' & $facility & ',' & $severity &...?]
endaction

if $message contains "error" then action writeMySQL

ALTERNATE APPROACH

define function IsLinux(
if $environ contains "linux" then return true else return false
)

load if IsLinux() 'imklog.so' params name='klog' endparams /* load klog under linux only */
run if IsLinux() input 'klog'
load 'ommysql.so'

if $message contains "error" then
action(
type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,
action.dbname='events', action.dbuser='uid',
- [?action.template='templatename'?] or [?action.sql='insert into -table... values('&$facility&','&$severity&...?]
)

... or ...

define action writeMySQL(
type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,
action.dbname='events', action.dbuser='uid',
- [?action.template='templatename'?] or [?action.sql='insert into -table... values('&$facility&','&$severity&...?]
)

if $message contains "error" then action writeMySQL(action.dbname='differentDB')

[rsyslog.conf overview] +

RainerScript

RainerScript is a scripting language specifically +designed and well-suited +for processing network events and configuring event processors +(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.

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.

A formal definition of the language can be found in RainerScript ABNF. 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.

Data Types

+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.
+

Expressions

+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.
+

expressions in parenthesis
not, unary minus
*, /, % (modulus, as in C)
+, -, & (string concatenation)
==, !=, <>, <, >, <=, >=, contains (strings!), startswith (strings!)
and
or

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. +

[rsyslog.conf overview] [manual index] [rsyslog site]

This documentation is part of the rsyslog diff --git a/doc/rscript_abnf.html b/doc/rscript_abnf.html new file mode 100644 index 00000000..6ffd4c37 --- /dev/null +++ b/doc/rscript_abnf.html @@ -0,0 +1,43 @@ + + +RainerScript ABNF + + + +

RainerScript ABNF

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.

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.

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).

Formal Definition

Below is the formal language definitionin ABNF (RFC 2234) +format:
+

; all of this is a working document and may change! -- rgerhards, 2008-02-24

script    := *stmt
stmt      := (if_stmt / block / vardef / run_s / load_s)
vardef    := "var" ["scope" = ("global" / "event")] 
block     := "begin" stmt "end"
load_s    := "load" constraint ("module") modpath params ; load mod only if expr is true
run_s     := "run" constraint ("input") name
constraint:= "if" expr ; constrains some one-time commands
modpath   := expr
params    := ["params" *1param *("," param) "endparams"]
param     := paramname) "=" expr
paramname := [*(obqualifier ".") name]
modpath:= ; path to module
?line? := cfsysline / cfli
cfsysline:= BOL "$" *char EOL ; how to handle the first line? (no EOL in front!)
BOL := ; Begin of Line - implicitely set on file beginning and after each EOL
EOL := 0x0a ;LF
if_stmt := "if" expr "then"
old_filter:= BOL facility "." severity ; no whitespace allowed between BOL and facility!
facility := "*" / "auth" / "authpriv" / "cron" / "daemon" / "kern" / "lpr" / 
 "mail" / "mark" / "news" / "security" / "syslog" / "user" / "uucp" / 
 "local0" .. "local7" / "mark"
	; The keyword security should not be used anymore
	; mark is just internal
severity := TBD ; not really relevant in this context

; and now the actual expression
expr := e_and *("or" e_and)
e_and := e_cmp *("and" e_cmp)
e_cmp := val 0*1(cmp_op val)
val := term *(("+" / "-" / "&") term)
term := factor *(("*" / "/" / "%") factor)
factor := ["not"] ["-"] terminal
terminal := var / constant / function / ( "(" expr ")" )
function := name "(" *("," expr) ")"
var := "$" varname
varname := msgvar / sysvar
msgvar := name
sysvar := "$" name
name := alpha *(alnum)
constant := string / number
string := simpstr / tplstr ; tplstr will be implemented in next phase
simpstr := "'" *char "'" ; use your imagination for char ;)
tplstr := '"' template '"' ; not initially implemented
number := ["-"] 1*digit ; 0nn = octal, 0xnn = hex, nn = decimal
cmp_op := "==" / "!=" / "<>" / "<" / ">" / "<=" / ">=" / "contains" / "startswith"
digit := %x30-39
alpha := "a" ... "z" # all letters
alnum :* alpha / digit / "_"

Samples

Some samples of RainerScript:

define function IsLinux
begin
if $environ contains "linux" then return true else return false
end

load if IsLinux() 'imklog.so' params name='klog' endparams /* load klog under linux only */
run if IsLinux() input 'klog'
load 'ommysql.so'

if $message contains "error" then
action
type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,
action.dbname='events', action.dbuser='uid',
+ [?action.template='templatename'?] or [?action.sql='insert into +table... values('&$facility&','&$severity&...?]
endaction

... or ...

if $message contains "error" then action writeMySQL

ALTERNATE APPROACH

define function IsLinux(
if $environ contains "linux" then return true else return false
)

load if IsLinux() 'imklog.so' params name='klog' endparams /* load klog under linux only */
run if IsLinux() input 'klog'
load 'ommysql.so'

if $message contains "error" then
action(
type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,
action.dbname='events', action.dbuser='uid',
+ [?action.template='templatename'?] or [?action.sql='insert into +table... values('&$facility&','&$severity&...?]
)

... or ...

define action writeMySQL(
type='ommysql.so', queue.mode='disk', queue.highwatermark = 300,
action.dbname='events', action.dbuser='uid',
+ [?action.template='templatename'?] or [?action.sql='insert into +table... values('&$facility&','&$severity&...?]
)

if $message contains "error" then action writeMySQL(action.dbname='differentDB')

[rsyslog.conf overview] +[manual index] [rsyslog site]

This documentation is part of the +rsyslog +project.
+Copyright � 2008 by Rainer +Gerhards and +Adiscon. +Released under the GNU GPL version 3 or higher.

+ \ No newline at end of file -- cgit