/** Enterprise Control Configuration and Logging Copyright (C) 2012 Free Software Foundation, Inc. Written by: Richard Frith-Macdonald Date: Febrary 2010 Originally developed from 1996 to 2012 by Brainstorm, and donated to the FSF. This file is part of the GNUstep project. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111 USA. */ #import @class GSMimeSMTPClient; @class NSArray; @class NSMutableArray; @class NSMutableDictionary; @class NSString; @class NSTimer; /** *

This class handles delivery and logging of error and alert messages * to the people who should be monitoring the system. It is used by the * Control server (to which all these messages are delivered) and * implements a simple rule based mechanism for managing final * delivery of the messages. *

*

The configured rules are compared against each message and any * actions associated with a matching rule are performed.
* The matching fields in each rule are - *

* * Host * An extended regular expression to match the name of the host * machine on which the message originated (possibly just the host name). * If this is not specified, messages from any host may match. * * Server * An extended regular expression to match the name of the server * process from which the message originated (possibly just the server * name). * If this is not specified, messages from any server may match. * * Type * The type of message ... Error or Alert. * If this is not specified, messages of any type may match. * * Pattern * An extended regular expression used to match the main text * of the message. See the posix regcomp documentation for details * of enhanced posix regular expressions. If this is not present, * any message text will match. * * Stop * A boolean (YES or NO) saying whether rule matching should * stop if this rule is matched. If this is NO (the default) then * after any action associated with this rule is performed, matching * continues at the next rule.
* Don't use this option injudiciusly. Try to write your pattern * matching rules so that most messages match a single rule to map * them to a nice readable version, and also match a default rule to * log full details to the technical team. * * Flush * A boolean (YES or NO) saying whether stored messages due to * be sent out later should be sent out immediately after processing * this rule. This is useful in the event that some time critical * message must be sent, but should not normally be used.
* As a special case, instead of the boolean value, this may take * the value Email or Sms indicating that a flush * should be performed, but only on the specified type of messages.
* beware The batching mechanism exists to prevent * a single problem triggering floods of messages. You should only * override it using Flush where you are sure * that messages triggering the flush will be infrequent. * * *

There are two additional fields Extra1 and Extra2 * which are matched against the message. These patterns do not effect * whether the action of the rule is executed or not, but the text matched * is made available for substitution into replacement messages. *

*

When a match is found the full message is normally sent to all the * destinations listed in the Email and Sms arrays in * the rule, and logged to all the destinations in the Log array.
* However, the Replacement field may be used to specify * a message to be sent in the place of the one received. Within the * Replacement string values enclosed in curly brackets will * be substituted as follows - *

* * Extra1 * The text in the message matched by the Extra1 pattern (if any) * Extra2 * The text in the message matched by the Extra2 pattern (if any) * Host * The host name of the original message * Server * The server name of the original message * Type * The type of the original message * Timestamp * The timestamp of the original message * Message * The text of the original message * Match * The text matched by the Pattern if any * *

The Log array specifies a list of log destinations which are * normally treated as filenames (stored in the standard log directory). * However, a value beginning 'database:' * is logged to a * database (the default database configured for SQLClient).
* After the colon you may place a table name, but if you don't then * the message will be logged to the 'Alert' table.
* The values logged in separate fields are the Timestamp, Type, Server, Host, * Extra1, Extra2, and full log text (as produced by the Replacement config) * is written into the Message field of the table after having been truncated * to 200 chars. Because of the truncation limit, it is recommended that * if you are trying to include the original alert {Message} (rather * than rewriting it) the Replacement does not include Timestamp, * Type, Server, Host, Extra1, Extra2 which are already saved in * separate fields, and would take up a lot of the 200 chars, which would * be better used to log the actual message. * *

*

The Sms array lists phone numbers to which Sms alerts are * to be sent. *

*

The Email array lists email addresses to which email alerts are * to be sent.
* An optional 'Subject' field may be present in the rule ... this is used * to specify that the is to be tagged with the given subject line. This * defeats batching of messages in that only messages with the * same subject may be batched in the same email. *

*/ @interface EcAlerter : NSObject { NSArray *rules; /** Rules for handling alerts */ NSMutableDictionary *email; /** Batching Email alerts */ NSMutableDictionary *sms; /** Batching SMS alerts */ NSTimer *timer; /** Timer for batch flush */ NSString *eBase; /** Sender host name for message ID */ NSString *eDflt; /** Default sender address */ NSString *eFrom; /** Sender address in use */ NSString *eHost; /** Host with SMTP MTA */ NSString *ePort; /** Port of SMTP MTA */ GSMimeSMTPClient *smtp; /** Client connection to MTA */ BOOL debug; /** Debug enabled in config */ } /** Called when user defaults are updated, this fetches the dictionary * 'Alerter' from the defaults system, and passes it to the * -configureWithDefaults: method. */ - (BOOL) configure: (NSNotification*)n; /** Called to set up or modify the configuration of the alerter.
* The dictionary c must contain (keyed on Rules an * array of dictionaries, each of which provides a rule for * delivering some form of alert.
* Other values in the configuration are used for standard configuration * of message delivery to the queueing system etc. */ - (BOOL) configureWithDefaults: (NSDictionary*)c; /** This method is called to flush any batched email messages. */ - (void) flushEmail; /** This method is called to flush any batched SMS messages. */ - (void) flushSms; /**

This method handles an error/alert event (an 'error' is one which may * be buffered, while an 'alert' must be sent immediately).
* If the identifier field is non-nil then the event is an alert which is * identified by the value of the field and may be 'cleared' by a later * event with the same identfier and with the isClear flag set. The use * of an empty string as an identifier is permitted for events which should * not be buffered, but which will never be matched by a clear. *

*

Each event must consist of text associated with a host name, * server name (usually the process on the host) and timestamp. *

*

Each message is matched against each rule in the Rules * configuration in turn, and the first match found is used. The * message is sent to the people listed in the Email and * Sms entries in the rule (which may be either single * names or arrays of names). *

*/ - (void) handleEvent: (NSString*)text withHost: (NSString*)hostName andServer: (NSString*)serverName timestamp: (NSString*)timestamp identifier: (NSString*)identifier isClear: (BOOL)isClear; /**

This method handles error/alert messages. It is able to handle * multiple (newline separated messages. *

*

Each message must be a line of the format -
* serverName(hostName): YYYY-MM-DD hh:mm:ss.mmm szzzz type - text *

*

Each message is parsed an then the components are passed to * the -handleEvent:withHost:andServer:timestamp:identifier:isClear: method. *

*/ - (void) handleInfo: (NSString*)str; /** Called by -handleEvent:withHost:andServer:timestamp:identifier:isClear: * to log a message to an array of destinations. */ - (void) log: (NSMutableDictionary*)m identifier: (NSString*)identifier isClear: (BOOL)isClear to: (NSArray*)destinations; /** Calls -log:identifier:isClear:to: with a nil identifier. */ - (void) log: (NSMutableDictionary*)m to: (NSArray*)destinations; /** Called by -handleEvent:withHost:andServer:timestamp:identifier:isClear: * to pass a message to an array of destinations. * The message is actually appended to any cached messages for those * destinations ... and the cache is periodically flushed. */ - (void) mail: (NSMutableDictionary*)m identifier: (NSString*)identifier isClear: (BOOL)isClear to: (NSArray*)destinations; /** Calls -mail:identifier:isClear:to: with a nil identifier. */ - (void) mail: (NSMutableDictionary*)m to: (NSArray*)destinations; /** Cache a copy of the Rules with modifications to store information * so we don't need to regenerate it every time we check a message. */ - (BOOL) setRules: (NSArray*)ra; /** Called by -handleEvent:withHost:andServer:timestamp:identifier:isClear: * to pass a message to an array of destinations. * The message replaces any cached messages for those * destinations (and has a count of the lost messages noted) ... and * the cache is periodically flushed. */ - (void) sms: (NSMutableDictionary*)m identifier: (NSString*)identifier isClear: (BOOL)isClear to: (NSArray*)destinations; /** Calls -sms:identifier:isClear:to: with a nil identifier. */ - (void) sms: (NSMutableDictionary*)m to: (NSArray*)destinations; /** Responsible for the periodic calling of -flushEmail and -flushSms */ - (void) timeout: (NSTimer*)t; @end