Notification modules allow the SQL Relay server programs to notify recipients when a specified set of events occur.
The notifications section of the sqlrelay.conf file indicates which notification modules to load and what parameters to use when executing them.
<?xml version="1.0"?>
<instances>
...
<instance ...>
...
<notifications>
<notification module="events">
<events>
<event event="db_error"/>
<event event="db_warning"/>
<event event="filter_violation"/>
</events>
<recipients>
<recipient address="dev@firstworks.com"/>
</recipients>
</notification>
</notifications>
...
</instance>
...
</instances>
The module attribute specifies which module to load.
Module configurations may have attributes and/or nested tags. How these elements are interpreted is module-specific.
Currently, all notification modules have an enabled parameter, allowing the module to be temporarily disabled. If enabled="no" is configured, then the module is disabled. If set to any other value, or omitted, then the module is enabled.
Notification modules can be "stacked". Multiple modules may be loaded and multiple instances of the same type of module, with different configurations, may also be loaded.
<?xml version="1.0"?>
<instances>
...
<instance ...>
...
<notifications>
<notification module="events">
<events>
<event event="db_error"/>
<event event="db_warning"/>
<event event="filter_violation"/>
</events>
<recipients>
<recipient address="dev@firstworks.com"/>
</recipients>
</notification>
<notification module="events">
<events>
<event event="integrity_violation"/>
</events>
<recipients>
<recipient address="dba@firstworks.com"/>
</recipients>
</notification>
</notifications>
...
</instance>
...
</instances>
At startup, the SQL Relay server processes create instances of the specified notification modules and initializes them. As events occur, the server passes the event and, optionally, a string of information about the event to each module, in the order that they were specified in the config file. If a module is listening for that event, then it sends a notification to the specified recpients.
Currently, the following standard notification modules are available:
The events module listens for a specified set of events and notifies recipients when a one occurs.
An example configuration follows.
<?xml version="1.0"?>
<instances>
...
<instance ...>
...
<notifications>
<notification module="events">
<events>
<event event="db_error"/>
<event event="db_warning"/>
<event event="filter_violation"/>
</events>
<recipients>
<recipient address="dev@firstworks.com"/>
</recipients>
</notification>
</notifications>
...
</instance>
...
</instances>
In this example, the module sends notifications to dev@firstworks.com when one of the db_error, db_warning, or filter_violation events occurs.
The events tag defines the set of events to listen for. Valid events are:
Any number of events may be specified. Each event must be specified in its own event tag. The event tag supports the following attributes:
Any number of recipients may also be specified. Each recipient must be specified in its own recipient tag. The recipient tag supports the following attributes:
Currently, notifications may only be sent via email.
If the subject attribute is not provided, then SQL Relay uses a default subject of:
SQL Relay Notification: @event@
Where @event@ is replaced with the event that triggered the notification.
If the template attribute is not provided, then SQL Relay uses a default template of:
SQL Relay Notification: Event : @event@ Event Info : @eventinfo@ Date : @datetime@ Host Name : @hostname@ Instance : @instance@ Process Id : @pid@ Client Address : @clientaddr@ Client Info : @clientinfo@ User : @user@ Query : @query@
In both subject lines and template files, the following substitutions can be made:
On linux/unix systems, the mail program is used to send notifications. Messages are sent using the following command:
mail -s subject address < message
Where subject is replaced with the subject, address is replaced with the recipient and messagee is replaced with the name of the temporary file that is used to store the message.
SQL Relay assumes that the mail program is installed, in the PATH of the user that SQL Relay runs as, and that mail delivery is configured on the host system.
On Windows systems the blat program is used to send notifications. Messages are sent using the following command:
blat message -to address -subject subject -q
Where subject is replaced with the subject, address is replaced with the recipient and message is replaced with the name of the temporary file that is used to store the message.
SQL Relay assumes that the blat program is installed, in the PATH of the user that SQL Relay runs as, and that blat has been configured. See http://www.blat.net to download and configure blat.
Custom modules may also be developed.
For more information, please contact David Muse at david.muse@firstworks.com.