execphandler.h File Reference

Detailed Description

The execphandler will execute an external program for each event received. You may supply a command line and optional text to write to stdin of process. Both the command line and optional text may have special characters that are macro replaced with event data before the process is executed. This handler is useful for integration with other programs. You can use this to trigger your own custom programs or interface with messaging programs. The macro processing replaces the following special symbols with their associated event data:

Symbol	Type
$v	event's value
$v[0-9]	the nth column where value is interpreted as a '\|' delimited string
$n	event's name
$s	event's source
$p	event's priority
$t	event's timestamp as date string
$i	event's timestamp as int

You may associate regex's to match the output lines of the command and generate events. You may have multiple regex's, each generating its own events. You may optionally specify a subsitution string that behaves similar to 'sed' to customize the generated events. If you supply a substitution string, rather than copying the original complete matching string, the substitution string is used, replacing all occurances of the special charcters \[0-9] with the associated substring matches. Note: \0 matches the whole expression, while \1,\2 through \9 are substring matches 1, 2 through 9. Substituion strings will be macro expanded for macros before event generation. Regex's are POSIX 1003.2 "extended" form. An optional 'complete:' directive will generate an event after a program has finished executing.

Wire keywords (standard handler keywords documented in Wire )

cmd: program + args (program to execute)
input: event input string (optional, macro expand input using event info and write to stdin)
complete: event (optional)
match: match-event nomatch-event regexp subst send match-event if regex matches, else send nomatch-event, if either match-event or nomatch-event are empty strings they are ignored (optional)
maxline: int (optional, max line size in bytes for input string)
timeout: int (optional, units == seconds, defaults to no timeout)

Email example:


// Send email alerts

// make the handler, assumes you have bound 'events' to list of events you care about.
create handler execp { 
 cmd: "mail -s \"alert: \$n\" sysadmin"
 input: "Something strange happened \$n \$v at \$t\n\n"
 regevent: $events 
 elogger: $hlogger 
}

SNMP trap example:


// Send trap using net-snmp 'snmptrap' command. Needs properly configured SNMP environment

// make the handler, assumes you have bound 'events' to list of events you care about.
create handler execp { 
 cmd: "snmptrap -v 2c -c public localhost '' NOTIFICATION-ALERT-MIB::severe-notif  SNMPv2-MIB::sysLocation.0 s \"\$n: \$v\" "
 regevent: $events 
 elogger: $hlogger 
}

Numeric pager example:


// Send numeric page using kermit , assumes you have setup the kermit commandfile
// See http://www.columbia.edu/kermit/faq-c-npg.html

// make the handler, assumes you have bound 'events' to list of events you care about.
create handler execp { 
 cmd: "kermit /usr/share/mon/pagesysadmin"
 regevent: $events 
 elogger: $hlogger 
}

Smbclient example:


// Send PopUP window alerts on Windows machines

// make the handler, assumes you have bound 'events' to list of events you care about.
create handler execp { 
 cmd: "smbclient -M sysadminLaptop"
 input: "Something strange happened \$n \$v\n\n"
 regevent: $events 
 elogger: $hlogger 
}

Reboot example:


// Do a shutdown -r when you recieve an event

// NOTE: this one is real dangerous...just here for illustration!

// make the handler, assumes you have bound 'events' to list of events you care about.
create handler execp { 
 cmd: "/sbin/shutdown -r now \$v"
 regevent: $events 
 elogger: $hlogger 
}

NOTE: careful with the execute permisions associated with the program exec'd. Events Accepted:

Event Name	Type	Description
event	any	For every event, execute 'cmd'.

Complete Events Generated:

Event Name	Type	Description
complete	AW_EVENT_TYPE_STRING	Generate event on successful process execution, value is cmd: after event macro expanding

Match Events Generated:

Event Name	Type	Description
match	AW_EVENT_TYPE_STRING	Regex match in line of stdout, send string of matching line or substitution
nomatch	AW_EVENT_TYPE_STRING	No regex match in any line of stdout, send string of "cmd"

#include <stdio.h>
#include "monitor.h"
#include "wire.h"
#include "regexmatch.h"

Go to the source code of this file.

Data Structures

struct aw_execphandler_events_t

Events generated. More...

struct aw_execphandler_regex_t

Specifies a regex and associated events. More...

struct aw_execphandler_revents_t

Events generated for regex matching. More...

struct aw_execphandler_state_t

State of probe during probing. More...

struct aw_execphandler_t

Execp handler object. More...

struct aw_execphandler_watcher_t

Compiled regex, associated events and state. More...

Functions

aw_execphandler_t * aw_create_execphandler (const byte_t *cmd, const byte_t *input, u_int32_t max_line_len, u_int32_t timeout, const aw_execphandler_events_t *events, u_int32_t nregexs, const aw_execphandler_regex_t *regexs, int32_t(*regevent)(aw_handler_t *h, aw_address_t *eventid, u_int32_t index), int32_t(*regmaskevent)(aw_handler_t *h, aw_address_t *eventid, u_int32_t index), const aw_alarm_sched_t *sched, aw_logger_t *aware_logger)

Create a execphandler.

void aw_free_execphandler (aw_execphandler_t *h)

Free handler and all associated resources.

aw_handler_t * aw_wire_execphandler (aw_wire_mkhandler_args_t *args)

Create a execphandler using "wire". See header doc for keyword documentation.

Function Documentation

aw_execphandler_t* aw_create_execphandler ( const byte_t * cmd,

const byte_t * input,

u_int32_t max_line_len,

u_int32_t timeout,

const aw_execphandler_events_t * events,

u_int32_t nregexs,

const aw_execphandler_regex_t * regexs,

int32_t(* regevent)(aw_handler_t *h, aw_address_t *eventid, u_int32_t index),

int32_t(* regmaskevent)(aw_handler_t *h, aw_address_t *eventid, u_int32_t index),

const aw_alarm_sched_t * sched,

aw_logger_t * aware_logger

)

Create a execphandler.

Parameters:

cmd Cmd string to exec after macro expanding

input String to write to stdin of new process after macro expanding, may be NULL

max_line_len Size of max line cmd or input, may be 0 for default

timeout Timeout for process to run , 0 means no timeout

events Complete event

nregexs How many regex strings

regexs Array of regex strings/events

regevent Function pointer for event registration

regmaskevent Function pointer for event mask registration

sched Run schedule

aware_logger Aware logger object

Returns:
Handler object

void aw_free_execphandler ( aw_execphandler_t * h )

Free handler and all associated resources.

Parameters:

h The handler

aw_handler_t* aw_wire_execphandler ( aw_wire_mkhandler_args_t * args )

Create a execphandler using "wire". See header doc for keyword documentation.


Data Structures
struct	aw_execphandler_events_t
	Events generated. More...
struct	aw_execphandler_regex_t
	Specifies a regex and associated events. More...
struct	aw_execphandler_revents_t
	Events generated for regex matching. More...
struct	aw_execphandler_state_t
	State of probe during probing. More...
struct	aw_execphandler_t
	Execp handler object. More...
struct	aw_execphandler_watcher_t
	Compiled regex, associated events and state. More...
Functions
aw_execphandler_t *	aw_create_execphandler (const byte_t cmd, const byte_t input, u_int32_t max_line_len, u_int32_t timeout, const aw_execphandler_events_t events, u_int32_t nregexs, const aw_execphandler_regex_t regexs, int32_t(regevent)(aw_handler_t h, aw_address_t eventid, u_int32_t index), int32_t(regmaskevent)(aw_handler_t h, aw_address_t eventid, u_int32_t index), const aw_alarm_sched_t sched, aw_logger_t aware_logger)
	Create a execphandler.
void	aw_free_execphandler (aw_execphandler_t *h)
	Free handler and all associated resources.
aw_handler_t *	aw_wire_execphandler (aw_wire_mkhandler_args_t *args)
	Create a execphandler using "wire". See header doc for keyword documentation.