...
The IF expression is basically any arbitrary Perl expression, but tokens of the form event
.name or node
.name are substituted with the respective event or node property value. The special wildcards event.any
and node.any
are replaced by a logical true value. Furthermore, tokens that match extdb.queryname.column
will be substituted with the result of an external enrichment query. The IF expression can include "AND" as well as "and" but does not support "OR" or "or".
If your IF expression does require text that could be misinterpreted as a substitution token (e.g. the "Nr.1"
in "IF" : "event.details eq "NTP Server Nr.1""
), then you should escape the dotted expression with a backslash (e.g. "NTP Server Nr\.1"
). Please note that in versions before 2.2.2, any misidentified unparseable tokens were flagged as errors and were not included in the final expression to be tested.
...
- No policy actions are performed for events with the property
action_checked
set to 1 or for events that are (already) acknowledged.
The former can be controlled by custom parser rules, the latter is mostly affected by the configuration optionsopevents_auto_acknowledge
andopevents_auto_acknowledge_up
:
With auto-acknowledge enabled, a stateful down event is automatically acknowledged when the corresponding up event arrives. In that case, the up event itself is also automatically acknowledged if and only ifopevents_auto_acknowledge_up
is set. - If the configuration option
opevents_no_action_on_flap
is set to true inconf/opCommon.nmisjson
, then no actions are performed on the down event that is involved in a flap event, and the down event is acknowledged. This is the default behaviour. - Policy action handling is delayed by
state_flap_window
seconds for all stateful events, so that state flaps can be detected before any actions are performed. - Policy action handling is delayed for synthetic events, if the event creation rule sets the property
delayedaction
.
...
The script action lets you execute a program of your choice, and optionally captures and saves that program's output with the event. As usual, the section script
of conf/EventActions.json
contains the required configuration directives:
Code Block | ||
---|---|---|
| ||
{ "script" : { "traceroute_node" : { "outputexec" : "save/bin/traceroute", "arguments" : "--max-hops=20 node.configuration.host", "execoutput" : "traceroutesave" }, "pingfuture_nodeproof" : { "execmax_tries" : "/bin/ping"2, "argumentsoutput" : "-c 5 node.configuration.hostsave", "outputstderr" : "save" , }, "ping_neighborexitcode" : {"save", "exec" : "/bin/ping",[ "output" : "save "/usr/local/bin/someprogram", "--first-fixed-arg", "no substitution happens here" ], "arguments" : [ "event.node", "event.event", "--extra", "event.details" ] }, "ping_node" : { "output" : "save", "exec" : "/bin/ping", "arguments" : "-c 5 event.element"node.host" } } }, |
The path to the program file must be given in the exec
option. Arguments can be passed to the program; simply add them to the arguments
option. Any tokens of the form event.
name or node.name
will be replaced by the named event or node property, respectively. If the option output
is set to save
, then the output of the program execution is captured and saved with the event in question; otherwise the output is discarded.
...
- opEvents versions up to 2.0.3 do not support long-running programs in script actions, and opeventsd blocks until the action program terminates.
- From version 2.0.4 onwards,
script
action handling is asynchronous and parallel, and the event status gets updated whenever processing of a script action completes.
Because of the asynchronous processing your action policy does not have access to anyscript.<scriptname>
event properties. - Up to version 2.0.6, script actions are excuted using the system shell.
- As a consequence you have to ensure your script
arguments
are shell-safe, ie. that spaces are escaped or suitably quoted, that quotes line up and that the arguments do not contain unescaped shell metacharacters (",',`,!, &...). - The exit code of the external program is not captured, only its output on STDOUT (and STDERR, unless the
exec
argument disposes of STDERR explicitely with a "2>..." construct). Argument substitution for
event
.name andnode
.name may need to be disabled (if your arguments need to contain a verbatim "event.sometext" string.
This can be done by escaping the "." with an (escaped) backslash. For exampleCode Block arguments => 'node.host event\\.event ...and other stuff to feed the program'
will cause the argument to contain the unsubstituted text 'event.event'. Node the use of single quotes.
- As a consequence you have to ensure your script
- Since the refresh of opEvents 2.0.6 on 2016-11-01, script actions are no longer executed using a shell, but directly by
opeventsd
instead.
This is much safer from a security perspective, and also generally faster.- It is recommended (but not required) that you change your script configuration to use the new list format for
arguments
(andexec
), as shown in the example above (see "future_proof").
If you use the list format, then each token is analysed for potential property substitution and then passed on to your program, separate from all other tokens.
Spaces, backticks or other shell metacharacters are thus no longer problematic in an event or node property. - You can continue using the single-string
arguments
orexec
, but then opEvents will perform the necessary word-splitting and minimal amendments for backwards-compatibility only:
If yourarguments
string contains quoted tokens like"--some_program_arg=event.event"
, the surrounding double (or single) quotes are stripped.
Please note that this is not performed for quotes anywhere else in your arguments string.
I.e. with an arguments string like--weird_argument=don't
, the single quote will be passed through to your program as-is. - If you need to disable substitution (to pass in strings like "event.sometext" verbatim), escape the "." with a backslash.
As a much better alternative you can also put verbatim arguments in theexec
list, because only thearguments
list is subject to substitution. - It is now possible to select whether the script exitcode should be captured and saved with the event.
This is enabled by default, unless you addexitcode
=> 'false
' to your script configuration. - It is now also possible to select which combination of STDOUT and STDERR output of a script should be captured and saved.
The config propertyoutput
covers STDOUT, the propertystderr
STDERR.stderr
defaults to the value ofoutput
, if not given explicitly.
Adding"2>&1
" to your script arguments is no longer supported. - Should you absolutely require shell features in your script action, simply use
/bin/sh
as theexec
and set thearguments
to your liking, but
please note that this is substantially less secure than direct execution ifevent.X
ornode.Y
substitutions are involved.
- It is recommended (but not required) that you change your script configuration to use the new list format for
- opEvents version 2.2.2 and newer also supports the
max_tries
parameter which determines how often a failed script action may be retried; ifmax_tries
is not set, then the default value 3 is used, i.e. up to three attempts to perform the action. Please note that action failure in this context means a script exceeding the maximum configured runtime or opEvents encountering a problem with starting the script, but not a script returning a nonzero exit code. - Make sure you double check the path to your executable if a script does not run. For example, the default location for ping_node is /bin/ping but on some instances of linux it can be found in /usr/bin/ping. In this case, you would need to update the path to the ping command when you call it in using the exec command.
Configuration for email()
...