aware  0.11.1.src
About: aware-.* Asynchronous Event Framework for Responsive Applications, System Control and Monitoring (let system administrators tune system variables, set monitoring/security alarms, build adaptive distributed systems and more). Beta version.
  Fossies Dox: aware-0.11.1.src.tgz  ("inofficial" and yet experimental doxygen-generated source code documentation)  

Handlers

Data Structures

struct  aw_ip2namehandler_events_t
 
struct  aw_name2iphandler_events_t
 
struct  aw_loadhandler_events_t
 
struct  aw_mysqlhandler_t
 
struct  aw_oraclehandler_t
 
struct  aw_pgsqlhandler_t
 
struct  aw_rrdhandler_t
 
struct  aw_sqlitehandler_t
 
struct  aw_sqlsvrhandler_t
 
struct  aw_andhandler_cevents_t
 
struct  aw_limiterhandler_event_count_t
 
struct  aw_loghandler_t
 
struct  aw_monstathandler_t
 Monstat handler object. More...
 
struct  aw_nothandler_events_t
 
struct  aw_replacechar_tr_filter_t
 
struct  aw_rfilter_range_filter_t
 
struct  aw_sfilter_regex_filter_t
 
struct  aw_stophandler_t
 
struct  aw_timerhandler_events_t
 Events generated. More...
 
struct  aw_dnshandler_events_t
 
struct  aw_httphandler_cevents_t
 
struct  aw_mcrxhandler_cevents_t
 
struct  aw_mctxhandler_cevents_t
 
struct  aw_mdnshandler_events_t
 
struct  aw_pinghandler_events_t
 
struct  aw_tcphandler_events_t
 
struct  aw_tcptxthandler_events_t
 
struct  aw_execphandler_events_t
 
struct  aw_filestathandler_events_t
 
struct  aw_logfilehandler_digest_t
 
struct  aw_memhandler_events_t
 
struct  aw_mounthandler_events_t
 
struct  aw_netifhandler_rxevents_t
 
struct  aw_uptimehandler_events_t
 

Macros

#define AW_DSYNC_DEFAULT_MCAST_GROUP   "239.255.255.228"
 
#define AW_BBRXHANDLER_DEFAULT_PORT   1984
 
#define UPNP_MCAST_GROUP   "239.255.255.250"
 
#define AW_WWWHANDLER_SERVER   "wwwhandler/Aware" AW_VERSION
 
#define AW_USERHANDLER_UTMP_PATH   "/var/run/utmp"
 

Typedefs

typedef aw_tcptxthandler_t aw_citrixhandler_t
 
typedef aw_tcptxthandler_t aw_ftphandler_t
 
typedef aw_tcptxthandler_t aw_imaphandler_t
 
typedef aw_tcptxthandler_t aw_pop3handler_t
 
typedef aw_tcptxthandler_t aw_smtphandler_t
 

Enumerations

enum  aw_hist_flag_t { AW_HIST_RESET_ON_COPY = 0x1 }
 
enum  aw_eventrxhandler_protocol_t { AW_EVENTRXHANDLER_PROTOCOL_UDP, AW_EVENTRXHANDLER_PROTOCOL_TCP, AW_EVENTRXHANDLER_PROTOCOL_MC }
 
enum  aw_eventtxhandler_protocol_t { AW_EVENTTXHANDLER_PROTOCOL_UDP, AW_EVENTTXHANDLER_PROTOCOL_TCP, AW_EVENTTXHANDLER_PROTOCOL_MC }
 
enum  aw_pshandler_flag_t { AW_PSHANDLER_GROUP = 0x1, AW_PSHANDLER_COUNTONCHANGE = 0x2 }
 

Detailed Description

Macro Definition Documentation

◆ AW_BBRXHANDLER_DEFAULT_PORT

#define AW_BBRXHANDLER_DEFAULT_PORT   1984

@header bbrxhandler.h

The bbrxhandler listens for Big Brother ( http://www.bb4.org/ ) network events on the specified port and forwards them using the event id of rx.

This is typically used to receive events from slave agents, especially on Windows.

Wire keywords (standard handler keywords documented in Wire )

  • port: int port (optional, defaults to 1984)
  • bind: ip ip to bind (optional)
  • rx: event

Example:

  set rx create event { name: dummy }
  create handler bbrx { rx: $rx }

Events generated:

Event NameTypeDescription
rx AW_EVENT_TYPE_STRING Big Brother message is the value, name is one of status|page|summary

Definition at line 63 of file bbrxhandler.h.

◆ AW_DSYNC_DEFAULT_MCAST_GROUP

#define AW_DSYNC_DEFAULT_MCAST_GROUP   "239.255.255.228"

@header dsynchandler.h

NOTE: not quite finished...need to account for phase difference of clocks on remote machines

The dsynchandler is like a timerhandler BUT it synchronizes with other dsynchandlers (perhaps on different machines) such that they all emit their events at the same time. This is done without requiring that clocks be sychronized (e.g., NTP). The method used is to adapt the phase of all event emissions such that they converge. Each dsychhandler broadcasts to the other dsychhandlers on the same multicast group.

The is useful for triggering actions that need to be synchronized with each other but not to an absolute time.

NOTE: only the cycletime scheduling keyword is supported (not cron).

Wire keywords (standard handler keywords documented in Wire ):

  • interrupt: event
  • tag: tag, string tag to allow multiple groups of handlers to share same multicast group (optional)
  • onsync: , only emit interrupt events when converged to syncrony with all others in group (optional)
  • mcinterface: interface name, multicast interface (optional, defaults to ANY)
  • mcaddress: ip, valid mutlicast ip group address (optional, defaults to 239.255.255.228)
  • mcport: int, mc port (optional, defaults to 1800)
  • mcinterface: interface name, multicast interface (optional, defaults to ANY)

Example:

  set interrupt create event { name: "dsync(1sec)"  priority: 1 }
  create handler dsync { interrupt: $interrupt cycletime: 1 }

Events generated:

Event NameTypeDescription
interrupt AW_EVENT_TYPE_TIMESTAMP It's time :)

Definition at line 81 of file dsynchandler.h.

◆ AW_USERHANDLER_UTMP_PATH

#define AW_USERHANDLER_UTMP_PATH   "/var/run/utmp"

@header userhandler.h

The userhandler generates events on login, logout and counts the number of users logged into the system.

Wire keywords (standard handler keywords documented in wirePage )

  • login: event (optional)
  • logout: event (optional)
  • nusers: event (optional)

Example:

  // monitor all login/logouts every 5min
  set login  create event { name: "login"  priority: 1 }
  set logout create event { name: "logout"  priority: 1 }
  create handler user { login: $login logout: $logout cycletime: 300 }

Events generated:

Event NameTypeDescription
login AW_EVENT_TYPE_STRING Format: user \t host \t time, where time format is from ctime()
logout AW_EVENT_TYPE_STRING Format: user \t host \t duration_seconds \t time, where time format is from ctime()
nusers AW_EVENT_TYPE_INT32 Count of total logged in users

Events accepted:

TypeDescription
Any Generate an event of type requested

@define AW_USERHANDLER_UTMP_PATH Holds the utmp path for currently logged in users

Definition at line 99 of file userhandler.h.

◆ AW_WWWHANDLER_SERVER

#define AW_WWWHANDLER_SERVER   "wwwhandler/Aware" AW_VERSION

@header wwwhandler.h

The wwwhandler is a simple http server.

Supports these standard requests (which may be disabled):

  • HEAD
  • GET
  • POST

Used as a based class for other handlers.

Events generated:

Event NameTypeDescription
xtn_info AW_EVENT_TYPE_STRING Log file record of the form: action|clientip|url|response_code

Definition at line 56 of file wwwhandler.h.

◆ UPNP_MCAST_GROUP

#define UPNP_MCAST_GROUP   "239.255.255.250"

@header upnphandler.h

The upnphandler will send a Universal Plug-n-Play (UPnP) M-SEARCH message to 239.255.255.250:1900 periodically, as well as listen for 'alive' and 'byebye' messages, to collect a list of all UPnP devices (e.g., personal computers, printers, scanners, etc.) The handler will "watch" for changes to a particular list of active devices who's description matches the specified regex's. Events may be generated when the matching devices are available or unavailable as well as to generate counts of the matching devices. The 'up' and 'down' events are useful to monitor devices to generate notification and/or other response to a device stopping (and starting, but that is less common). The 'count' events are useful if you are interested in alerts when the number of a specific devices gets too high or low and when you are keep stats on activity. You may have multiple regex's, each generating its own events. This avoids doing the network search for each regex, rather it is is read one time for all. 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. For example, say you are watching all the HP printers on your network. You can change the name reported in the event by supplying a subsitution string and specifying substrings in the regex (i.e., regex is "http://(.*)/.*HP.*(uuid:[0-9]*)" and substitution is "HP printer at \1 is down (\2)"). Regex's are POSIX 1003.2 "extended" form. Names reported in events are generated by concatenating the LOCATION, SERVER and USN strings seperated by a \t. This handler implements a control point as per the UPnP1.0 spec.

Wire keywords (standard handler keywords documented in wirePage )

  • match: up-event down-event count-event regexp subst (if either up-event, down-event or count-event are empty strings they are ignored)
  • mcinterface: interface name multicast interface (optional)
  • noloopback: disable loopback on multicast (optional)

You my have multiple match: lines. Matches are applied in the order they are declared.

Example:

// generate events for all UPnP devices coming up/down and report total count
set up create event { name: "up"  priority: 1 }
set down create event { name: "down"  priority: 1 }
set count create event { name: "count"  priority: 1 }
create handler upnp { 
    match: $up $down $count "" ""
    elogger: $plogger 
}

Events generated:

Event NameTypeDescription
up AW_EVENT_TYPE_STRING Device with matching name is up, send name
down AW_EVENT_TYPE_STRING Device with matching name is that was up is now down, send name
count AW_EVENT_TYPE_INT32 The number of devices matching the regex

References:

Definition at line 151 of file upnphandler.h.

Typedef Documentation

◆ aw_citrixhandler_t

@header citrixhandler.h

Derived from tcptxthandler. Attempts to connect() and then does a protocol specific service check.

If no port is provided in URL, the standard port is used.

Wire keywords (standard handler keywords documented in Wire )

  • url: URL (host:[port]) (port is optional and overrides default)
  • connect: event (optional)
  • noconnect: event (optional)
  • service: event (optional)
  • noservice: event (optional)
  • timeout: float units == seconds (optional)

Example:

  set noconnect create event { name: "noconnect"  priority: 1 }
  set noservice create event { name: "noservice"  priority: 1 }
  create handler citrix { 
    url: citrix://citrixserver
    noconnect: $noconnect 
    noservice: $noservice
    timeout: 5
    cycletime: 60
 }

Events generated:

Event NameTypeDescription
connect AW_EVENT_TYPE_STRING Was able to connect, send string of "url"
noconnect AW_EVENT_TYPE_STRING Was NOT able to connect, send string of "url"
service AW_EVENT_TYPE_STRING service check successful, send string of "url"
noservice AW_EVENT_TYPE_STRING service check UNsuccessful, send string of "url"

Definition at line 92 of file citrixhandler.h.

◆ aw_ftphandler_t

@header ftphandler.h

Derived from tcptxthandler. Attempts to connect() and then does a protocol specific service check.

If no port is provided in URL, the standard port is used.

Wire keywords (standard handler keywords documented in Wire )

  • url: URL (host:[port]) (port is optional and overrides default)
  • connect: event (optional)
  • noconnect: event (optional)
  • service: event (optional)
  • noservice: event (optional)
  • timeout: float units == seconds (optional)

Example:

set noconnect create event { name: "noconnect"  priority: 1 }
set noservice create event { name: "noservice"  priority: 1 }
create handler ftp { 
 url: ftp://ftp.mydomain.com
 noconnect: $noconnect
 noservice: $noservice
 timeout: 5
 cycletime: 60
}

Events generated:

Event NameTypeDescription
connect AW_EVENT_TYPE_STRING Was able to connect, send string of "url"
noconnect AW_EVENT_TYPE_STRING Was NOT able to connect, send string of "url"
service AW_EVENT_TYPE_STRING service check successful, send string of "url"
noservice AW_EVENT_TYPE_STRING service check UNsuccessful, send string of "url"

Definition at line 92 of file ftphandler.h.

◆ aw_imaphandler_t

@header imaphandler.h

Derived from tcptxthandler. Attempts to connect() and then does a protocol specific service check.

If no port is provided in URL, the standard port is used.

Wire keywords (standard handler keywords documented in Wire )

  • url: URL (host:[port]) (port is optional and overrides default)
  • connect: event (optional)
  • noconnect: event (optional)
  • service: event (optional)
  • noservice: event (optional)
  • timeout: float units == seconds (optional)

Example:

  set noconnect create event { name: "noconnect"  priority: 1 }
  set noservice create event { name: "noservice"  priority: 1 }
  create handler imap { 
    url: imap://mail.mydomain.com
    noconnect: $noconnect 
    noservice: $noservice
    timeout: 5
    cycletime: 60
 }

Events generated:

Event NameTypeDescription
connect AW_EVENT_TYPE_STRING Was able to connect, send string of "url"
noconnect AW_EVENT_TYPE_STRING Was NOT able to connect, send string of "url"
service AW_EVENT_TYPE_STRING service check successful, send string of "url"
noservice AW_EVENT_TYPE_STRING service check UNsuccessful, send string of "url"

Definition at line 92 of file imaphandler.h.

◆ aw_pop3handler_t

@header pop3handler.h

Derived from tcptxthandler. Attempts to connect() and then does a protocol specific service check.

If no port is provided in URL, the standard port is used.

Wire keywords (standard handler keywords documented in Wire )

  • url: URL (host:[port]) (port is optional and overrides default)
  • connect: event (optional)
  • noconnect: event (optional)
  • service: event (optional)
  • noservice: event (optional)
  • timeout: float units == seconds (optional)

Example:

  set noconnect create event { name: "noconnect"  priority: 1 }
  set noservice create event { name: "noservice"  priority: 1 }
  create handler pop3 { 
    url: pop3://mail.mydomain.com
    noconnect: $noconnect 
    noservice: $noservice
    timeout: 5
    cycletime: 60
 }

Events generated:

Event NameTypeDescription
connect AW_EVENT_TYPE_STRING Was able to connect, send string of "url"
noconnect AW_EVENT_TYPE_STRING Was NOT able to connect, send string of "url"
service AW_EVENT_TYPE_STRING service check successful, send string of "url"
noservice AW_EVENT_TYPE_STRING service check UNsuccessful, send string of "url"

Definition at line 92 of file pop3handler.h.

◆ aw_smtphandler_t

@header smtphandler.h

Derived from tcptxthandler. Attempts to connect() and then does a protocol specific service check.

If no port is provided in URL, the standard port is used.

Wire keywords (standard handler keywords documented in Wire )

  • url: URL (host:[port]) (port is optional and overrides default)
  • connect: event (optional)
  • noconnect: event (optional)
  • service: event (optional)
  • noservice: event (optional)
  • timeout: float units == seconds (optional)

Example:

  set noconnect create event { name: "noconnect"  priority: 1 }
  set noservice create event { name: "noservice"  priority: 1 }
  create handler smtp { 
    url: smtp://mail.mydomain.com
    noconnect: $noconnect 
    noservice: $noservice
    timeout: 5
    cycletime: 60
 }

Events generated:

Event NameTypeDescription
connect AW_EVENT_TYPE_STRING Was able to connect, send string of "url"
noconnect AW_EVENT_TYPE_STRING Was NOT able to connect, send string of "url"
service AW_EVENT_TYPE_STRING service check successful, send string of "url"
noservice AW_EVENT_TYPE_STRING service check UNsuccessful, send string of "url"

Definition at line 92 of file smtphandler.h.

Enumeration Type Documentation

◆ aw_eventrxhandler_protocol_t

@header eventrxhandler.h

The eventrxhandler listens for Aware network events on the specified port and forwards them using the event id of rx.

This is typically used to receive events from slave agents.

Wire keywords (standard handler keywords documented in Wire )

  • port: int port
  • bind: ip ip to bind to (optional for ud,tcp), mutlicast group ip address (required if protocol is mc)
  • rx: event
  • protocol: udp,tcp,mc (optional) Defaults to udp
  • mcinterface: interface name multicast interface (optional, defaults to ANY, mc protocol only)

Example:

  set rx create event { name: dummy }
  create handler eventrx { port: 4321 rx: $rx }

Events generated:

Event NameTypeDescription
rx all Forwarded event with new id

@discussion Type of protocol used

Enumerator
AW_EVENTRXHANDLER_PROTOCOL_UDP 
AW_EVENTRXHANDLER_PROTOCOL_TCP 
AW_EVENTRXHANDLER_PROTOCOL_MC 

Definition at line 68 of file eventrxhandler.h.

◆ aw_eventtxhandler_protocol_t

@header eventtxhandler.h

This handler sends all events registered to the specified hostname and port.

This is typically used to forward events from slave agents to the master agent for logging in the event database and for centralized alert generation.

Wire keywords (standard handler keywords documented in Wire )

  • hostname: [hostname|IP]
  • port: int udp/tcp/mc port
  • protocol: udp,tcp,mc (optional) Defaults to udp
  • mcinterface: interface name multicast interface (optional, defaults to ANY, mc protocol only)

Example:

make the handler, assumes you have bound 'events' to list of events you care about.
create handler eventtx { hostname: sentry.mydomain.net port: 4321 regevent: $events }

Events accepted:

TypeDescription
any Events are translated into network format and sent via specified protocol to host

@discussion Type of protocol used

Enumerator
AW_EVENTTXHANDLER_PROTOCOL_UDP 
AW_EVENTTXHANDLER_PROTOCOL_TCP 
AW_EVENTTXHANDLER_PROTOCOL_MC 

Definition at line 76 of file eventtxhandler.h.

◆ aw_hist_flag_t

@header histhandler.h

Histogram handlers receive events with data that will be histogramed, and max,min,mean calculated. Additionally, they can receive events that:

  • will cause the current histogram to be copied and sent as an event
  • reset
Events accepted:
Event NameTypeDescription
datapt AW_EVENT_TYPE_INT32 |
AW_EVENT_TYPE_INT64 |
AW_EVENT_TYPE_FLOAT32 |
AW_EVENT_TYPE_FLOAT64 |
AW_EVENT_TYPE_TIMESTAMP
Add data point to histogram
copy_cmd ignored Copy histogram an generate a copy event
reset_cmd ignored Reset histogram
Events generated:
Event NameTypeDescription
copy AW_EVENT_TYPE_VALUEPTR Received a copy_cmd event, send copy of histogram

@discussion Flags to set behavior

Enumerator
AW_HIST_RESET_ON_COPY 

Definition at line 86 of file histhandler.h.

◆ aw_pshandler_flag_t

@header pshandler.h

The pshandler will "watch" the system's processes. You can watch for processes creation/destruction, specifying which processes to watch with a regex. You many generate events when processes fall within a specified range of percent memory or percent cpu used. NOTE: a process' percent memory used is calculated by taking the the RSS size and dividing it by the main memory size, so this is a measure of percent RAM used. Swap is NOT included. The 'up' and 'down' events are useful to monitor running programs to generate notification and/or other response to processes stopping (and starting, but that is less common). The 'count' events are useful if you are interested in alerts when the number of a specific processes gets too high or low and when you are keep stats on activity. You may have multiple regex's, each generating its own events. This avoids reading the process table for each regex, rather it is is read one time for all. 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. For example, say you are watching a process with an ugly or uninformatative name, you can change the name reported in the event by supplying a subsitution string and specifying substrings in the regex (i.e., regex is "/usr/local/bin/httpd" and substitution is "Web server is down! (\0)"). Regex's are POSIX 1003.2 "extended" form.

Wire keywords (standard handler keywords documented in wirePage )

  • match: up-event down-event count-event regexp subst if either up-event, down-event or count-event are empty strings they are ignored (optional)
  • mem: mem-event min-percent max-percent if a process is using between [min,max] percent of system memory then generate mem-event (optional)
  • cpu: cpu-event min-percent max-percent if a process is using between [min,max] percent of system cpu then generate cpu-event (optional)

You my have multiple match: lines. Matches are applied in the order they are declared. You may only have 1 mem: line and 1 cpu: line.

Up/down/count example:

// generate events for httpd coming up/down and report total count
set up create event { name: "up"  priority: 1 }
set down create event { name: "down"  priority: 1 }
set count create event { name: "count"  priority: 1 }
create handler ps { 
    match: $up $down $count "httpd" ""
    cycletime: 5 
}

Memory example:

// generate events if for processes using too much memory 
set fatpig create event { name: 'Over 90% mem'  priority: 1 }
create handler ps { 
    mem: $fatpig 90 100
    cycletime: 5 
}

Cpu example:

// generate events if for processes using too much cpu
set cpuhog create event { name: 'Over 90% cpu'  priority: 1 }
create handler ps { 
    mem: $cpuhog 90 100
    cycletime: 5 
}

Match events generated:

Event NameTypeDescription
up AW_EVENT_TYPE_STRING Process with matching name is up, send process name
down AW_EVENT_TYPE_STRING Process with matching name is that was up is now down, send pid:cmdline
count AW_EVENT_TYPE_INT32 The number of processes matching the regex

Mem events generated:

Event NameTypeDescription
mem AW_EVENT_TYPE_STRING If process' memory usage is in range, send pid:cmdline

Cpu events generated:

Event NameTypeDescription
cpu AW_EVENT_TYPE_STRING If process' cpu usage is in range, send pid:cmdline

Events accepted:

TypeDescription
Any Generate an event of type requested

*/

/**** moved below comment out of above because the "wire" interface does not allow you to set these currently ****/ /* Options:

  • AW_PSHANDLER_GROUP : Watch a group of processes defined by matching the regex. Only send 'up' events when the first match appears and only send 'down' events when the last match disappears. This is useful for applications like Apache which fork/kill child processes regularly.
  • AW_PSHANDLER_COUNTONCHANGE : Only send 'count' events when the count of the processes matching the regex changes. By default, the 'count' events are generated every cycle. This option is useful is you are interested in notification if the number of processes gets below or above a certain number (used with the rfilterhandler).

Flag values.

Enumerator
AW_PSHANDLER_GROUP 
AW_PSHANDLER_COUNTONCHANGE 

Definition at line 204 of file pshandler.h.