Page Comparison

...

'script' => {
	'traceroute_node' => {
		arguments => '--max-hops=20 node.host',
		exec => '/bin/traceroute',
		output => 'save'
	},
 	'ping_node' => {
		arguments => '-c 5 node.host',
		exec => '/bin/ping',
 		output => 'save'
 	},
    # supported since the 2016-11-01 rerelease of version 2.0.6
	'future_proof' => { 
		exec => [ "/usr/local/bin/someprogram", "--first-fixed-arg", "no substitution happens here" ],
        arguments => [ "event.node", "event.event", "--extra", "event.details" ],
        output => "save",
        stderr => "save",
        exitcode => "save",
        max_tries => 2, 
    },
 }

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 any script.<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 and node.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 example

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

• 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 (and exec), 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 or exec, but then opEvents will perform the necessary word-splitting and minimal  amendments for backwards-compatibility only:
    If your arguments 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" verbiatim), escape the "." with a backslash.
    As a much better alternative you can also put verbatim arguments in the exec list, because only the arguments 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 add exitcode => '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 property output covers STDOUT, the property stderr STDERR. stderr defaults to the value of output, if not given explicitely.
    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 the exec and set the arguments to your liking, but
    please note that this is substantially less secure than direct execution if  event.X or node.Y substitutions are involved.
• opEvents version 2.2.2 and newer also supports the max_tries parameter which determines how often a failed script action may be retried; if max_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.

Configuration for email()

...