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)  

Wire

Wire

@header wire.h
The Aware deamon, awared, is configured by reading a file called a "wire" file. This file describes the handlers and other objects as well as how they are interconnected. The wire file format is a declarative format, supporting variable binding, and file inclusion. It is not a scripting language. The intention is to keep the implementation light. Adding many script-like features would make the implementation become heavy, at which point you might as well link Aware directly to Perl or Python (which would be easy to do should someone have the energy to create such bindings, hint). However, you might find it useful to use a scripting language to generate a complex wire file driven by many parameters. Handlers can run on a timed cycle and generate events. For example, you might create a handler to ping a machine on your network every 60 seconds. Handlers may also register to receive events and do something with them. For example, you might generate an alert if the ping handler did not receive a response. In the wire file you name an event by creating an event object:

set pingfailed create event { name: 'noconnect' }


The above example create an event named 'noconnect' and binds it to a variable called 'pingfailed'. Each handler has particular keywords associated with it's function but all handlers have the cycletime: keyword (cron: can also be used) which specifies how often to run:

create handler ping { hostname: www.yahoo.com noconnect: $pingfailed cycletime: 60 }


The above example will create a ping handler that will ping www.yahoo.com every 60 seconds and generate the event created in the earlier example named 'noconnect' should the handler's ping fail to get a response from the target host. Handlers may register to receive events and perform some action. Optionally, handlers may generate events of their own:

create handler execp {
     cmd: "mail -s \"alert: $n" sysadmin" <br> &nbsp;&nbsp;&nbsp;&nbsp; input: "Alert:
\t$n:$v at $t

"
     regevent: $pingfailed
}


The above example will send email to 'sysadmin' when it receives a 'pingfailed' event, printing the event's name, value and timestamp in the body of the message.

Comments

/*
     C style comments are supported
*/
// and C++ style


Quoting strings

Strings specified in a wire file are defined as a consecutive set of non-white space characters, as the wire format is white space delimited. For example:

set hostname www.google.com


If spaces are desired in a string it should be enclosed in single or double quotes. Single quotes will create a string as specified inside the quotes:

set emailbody 'Alert: /etc/passwd has changed!'


Strings enclosed within double quotes will have variables expanded as well as \t,\r,\n,\a,\b,\v,\f :

print "Creating handler for host $hostname\n"


Include

You may include other wire files in a manner similar to the C pre-processor. To include another wire file use the include directive:

include "myhandlers.wire"


To include a file only if it exists use the includeifexists directive:

includeifexists "customizations.wire"


Variables

Strings, numbers and objects may be bound to variables using the set command. A '$' is used to dereference the variable. Curly braces may be used to join 2 non white space seperated strings:

set filename "${device}.${interface}.rrd"


The following variables are predefined:

  • HOSTNAME is bound to the hostname of current machine.
  • MASTER is bound to the hostname of master if in slave mode, if not it is bound to ""

The print command

The print will print the string or varable to the console. You may specify multiple arguments:

print "Created event" $event "\n"


The set command

The set command will bind a string, number or object to a variable:

set the handler cycletime
set cycletime 30
set the url
set url 'http://exchange.mydomain.net'


The list command

The list command will bind a set of variables to another variable:

list failevents $pingfail $httpfail $wwwfail


The create command

The create command is used to create an object.

Creating events

Events are used to connect handlers. Event creation takes 3 arguments:

  • name:string
  • priority:integer (optional)
  • source:string (optional)
set freememory create event { name: "freemem" priority: 1 }


Creating loggers

Loggers output error/warning messages. By default a logger will output messages to the console (stderr) and prepend the date. Logger creation takes 6 arguments (all optional):

  • filename:string Output messages to a file (optional)
  • rotate:[hour|day|month] Rotate the log filename on specified time boundary (optional)
  • nodate: Do not prepend the date (optional)
  • dedup: Do not output consecutive duplicate messages (optional)
  • stdout: Output via stdout (optional)
  • syslog: Output via syslog (optional)
set alertlogger create logger { filename: /usr/log/alert.log rotate: day }


Creating handlers

The list of all handlers can be found here. Each handler has its own specific set of arguments but all handlers have these 9 (note cycletime:,and cron: are mutally exclusive):

  • start: Start time of this handler.
  • stop: Stop time of this handler.
  • cycletime:number Time period in seconds. May be a float (e.g, 0.5).
  • cron:crontab A space delimited string in crontab format (e.g., '0 3 * * *', run at 3am).

    fieldallowed values
    minute0-59
    hour0-23
    day of month1-31
    month1-12
    day of week0-6


    A field may be an asterisk (*), which always stands for `‘first-last’'.


    Ranges of numbers are allowed. Ranges are two numbers separated with a hyphen.

    The specified range is inclusive. For example, 8-11 for an `‘hours’' entry specifies execution at hours 8, 9, 10 and 11.


    Lists are allowed. A list is a set of numbers (or ranges) separated

    by commas. Examples: 1,2,5,9'',0-4,8-12''.

  • runonce: Run one time and stop
  • wait: Do not run until ALL events associated registered event have finished. That description makes it sound complicated to use, but it is not. You use wait: in a handler to synchronize events. Generally, this is used when you need transactionally oriented control. For example, perhaps a handler generates an event that causes handlers to insert data into multiple tables in a database and you want subsequent events to be generated only after all these events derived from the original probe event are done. This is very easy, just create a handler that registers to receive the first handler's event and add the wait: keyword.
  • ~cron: crontab This specifies when not not run. Used for maintenance windows. The crontab is of the form specified for cron:.
  • desc: Description string
  • elogger:logger Handler logger for errors/warnings (optional, defaults to logger configuration for awared)