Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

Wire

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"
     input: "Alert:\n\t\$n:\$v at \$t\n\n"
     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:

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:

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):

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):

Aware 0.11.1 Copyright (C) 1998-2005 Russell Leighton (russ@elegant-software.com)