Configures the following settings for system alerts (events):
Notes:
realevent options
The following list summarises the available command line options. The remaining sections describe how to use these options.
-a Amend.
-b bound Event-specific bound setting.
-c configurationOption
Displays configuration help.
-D days Specifies the days on which an alert should be sent (filter configuration).
-d Disable.
-E events Specifies the events to which a filter applies.
-e Enable.
-f filter Specifies a filter.
-h Help.
-i eventID Specifies an event.
-l List configuration (lower case L.).
-m message Defines a message.
-n notificationMethod
Specifies a notification method.
-p param Specifies a configuration parameter.
-r recipient Specifies the recipient of an alert.
-s Send message (raise an alert).
-T times Specifies the period during which an alert should be sent (filter configuration).
-t message Specifies the text of a message.
-v value Specifies the value of a parameter.
-w Initialise the specified notification method. Use with the -n option.
-x Debug.
-z Zap. Resets or deletes (as appropriate) the specified parameter.
This section describes how to configure general notification settings.
realevent -ap param -v value
Sets the specified parameter to value.
realevent -zp param
Clears the specified parameter.
param Specifies the configuration parameter to be set or cleared. Must be one of the following:
myemail
The email address to be supplied in both the ‘From’ and ‘Reply To’ fields of any
emails transmitted (it is not possible to specify different addresses
for these fields). This must be specified before you configure the SMS or SMTP
notification method.
smtpserver
The fully qualified domain name of the email server to which any emails will be sent.
This must be specified before you configure the SMS or SMTP
notification method.
smstemplate
The full path of the SMS template that is to be used
to construct an email envelope. This must be specified before you configure the SMS
notification method.
smsextra
An optional extra parameter that can be
referenced from the SMS template.
myhost
The domain name of the host which is
establishing the connection to the email server. Some email servers will reject
the connection unless this is specified.
value The value to which to set the specified parameter.
realevent -ap myemail -v plato@deepspace.phi -l
Sets the value of the myemail parameter to the email address “plato@deepspace.phi”. The -l (lower case L) option specifies that on completion the new configuration should be displayed.
realevent -zp myemail
Resets the myemail configuration parameter to a null string.
This section describes how to configure the different notification methods – email, text messaging and web page.
realevent -a{e}{w}n notificationMethod {-r recipient}
Configures and/or enables the specified notification method. When enabling (e option), a recipient must have already been set up, or must be specified with the -r option. If the w option is included, the notification method is initialised if appropriate (in practice, this only applies to the html notification method, for which it clears the web page).
realevent -ae{w}n notificationMethod
Enables the specified notification method.
realevent -ad{w}n notificationMethod
Disables the specified notification method.
realevent -zn notificationMethod
Clears and disables the specified notification method.
notificationMethod
The notification method to be configured. One of:
smtp
Notification by email. The
myemail and smtpserver
configuration parameters must be set
before configuring the smtp notification method.
sms
Notification by text message to a mobile phone. The myemail,
smtpserver and
smstemplate
configuration parameters must be set
before configuring the sms notification method.
Note: Alerts sent by text message are sent to an SMTP to SMS gateway, which extracts the text message and forwards it to the recipient. To use text messaging, therefore, you will require a subscription to a suitable gateway.
html
Notification by appending to the end of a web page. Note that if the
w option is specified, the web page is cleared.
recipient Specifies the email address, mobile phone number or web page address (as appropriate) of the recipient. Multiple recipients must be separated by semicolons.
For SMS notification, recipient generally has the form
mobilePhoneNumber@SMSGatewayServer (for example,
01234012345@fastsms.com), where mobilePhoneNumber is the number of a mobile phone and
SMSGatewayServer is the
network name or IP address of the SMS gateway server that will forward the message to
this number. Note, however, that some SMS gateway servers may require a
different format – refer to your SMS gateway server documentation.
For web page notification, recipient must be the full path of a web page to which alert messages will be appended. The default is $REALROOT/files/event.rpt – this is a text file that is referenced by the web page $REALROOT/files/event.htm. If only a file name is specified, this is assumed to be relative to $REALROOT/files.
realevent -aen sms -r 01234012345@fastsms.com
Enables the sms notification method and sets it to the phone number 01234012345, with the text message being forwarded by the SMS server fastsms.com.
realevent -adn smtp
Disables the smtp notification method, but leaves its configuration unchanged.
realevent -aen smtp
Enables the smtp notification method, using the current configuration.
realevent -zn sms
Disables the sms notification method and resets it to its default state (no recipient).
This section describes how to create and configure alert events. Events are of two types: predefined service and system events, and user-defined events (some user-defined events may be created by Northgate applications). User-defined events can be generated using either realevent or the ALERT TCL command.
realevent -a{e}i eventID {-b boundValue} {-t message}
Configures and/or enables (-e option) the specified event. When enabling, the event must have already been configured, or the -b and/or -t options must be specified.
realevent -aei eventID
Enables the specified event.
realevent -adi eventID
Disables the specified event.
realevent -zi eventID
For Reality service and system events, resets and disables the specified event. For Northgate application events and user-defined events (see below), deletes the specified event.
eventID The ID of the required event. There are four types of event, with IDs in the following ranges:
1001-1999 Reality service events.
2001-2999 Reality system software events.
3001-3999 Northgate application events.
4001-4999 Available for user-defined events.
Reality service and system alerts are generated automatically by the system. Northgate application and user-defined events are generated with either realevent -s or the ALERT TCL command.
boundValue
A setting specific to a particular Reality
Service or System Event. Bound values can be used to limit the number and type of events that
will be reported; for example, you can choose to receive notification of all
daemon log events, or just those that are most serious.
Note that you cannot define bound values for user-defined and Northgate application events.
message The message to be sent to the recipient. For pre-defined events this overrides the default message.
realevent -aei 1002 -b 4 -t "My daemon messages"
Enables event 1002 and configures it to report daemon log events down to level 4. Recipients will be sent the message “My daemon messages”, instead of the default message.
realevent -adi 4001
Disables event 4001, but leaves its configuration unchanged.
realevent -aei 4001
Enables event 4001, using the current configuration.
realevent -zi 1002
Disables event 1002 and resets it to its default state. Note that if the event were user-defined or a Northgate application event, it would be deleted.
This section describes how to specify days and times of day when alert messages should be sent to particular recipients:
realevent -af filterNumber {-E events} {-r recipient} {-D days} {-T times}
Creates or amends a filter. When creating a new filter, you must specify a recipient.
realevent -zf filterNumber
Deletes the specified filter.
filterNumber
The number of the filter to be created, amended or deleted.
events Specifies the
IDs of the events allowed by this filter. This can be a single event
ID, a range of IDs in the form
recipient Specifies the recipients (email addresses, mobile phone numbers and/or web page addresses) to which this filter will allow messages to be sent. Multiple recipients must be separated by semicolons.
Note: When creating a filter, you must specify at least one recipient. When amending a filter, the recipients can be omitted.
days Specifies the days
on which this filter will allow alert messages to be sent. This can be a single
day, a range of days (in the form
times Specifies the
period during which this filter will allow alert messages to be sent. This can be a
range of times (in the form
A range can span two
days (for example, 18:00-09:00). However, the
times set will apply only on the days set with the -D
option (for example, -D wed -T 21:00-07:00 means from
midnight to 7 am and from 9 pm to midnight on Wednesday, not from 9 pm on
Wednesday to 7 am on Thursday).
realevent -af 1 -r me@home.com
Amends filter number 1 to allow messages to be sent only to the recipient me@home.com. If filter number 1 does not exist, it is created with all events enabled for all days and times.
realevent -af 1 -D wed-mon
Amends filter number 1 to allow messages to be sent on the days Wednesday to Monday only.
realevent -af 1 -E 1001-1999
Amends filter number 1 to allow only messages resulting from events 1001 to 1999 to be sent.
realevent -af 1 -T 17:30-2:00
Amends filter number 1 to allow messages to be sent between the hours of 5.30 pm and 2 am only.
realevent -af 1 -r him@home.com -E * -D * -T 18:00-23:59 -l
Amends filter number 1 to allow all events to send messages to the recipient him@home.com, between 6 pm and midnight on any day. The -l option specifies that, on completion, the changed configuration should be displayed.
realevent -zf 1
Deletes filter number 1.
-c[n || f || b || p] Displays help for the specified configuration option, as follows:
b Event bounds.
f Filters.
n Notification methods.
p Configuration parameters.
-h Displays the main help page.
-l Used on its own, lists the complete current configuration. Can be combined with other options to list a revised configuration.
-s -i
eventID {-m message}
Send the specified event, if enabled, to the enabled recipients. message
is text sent in addition to that defined for the event. For example:
realevent -s -i 1001 -m "Sending test event 1001"
Raises alert event 1001, with the additional text “Sending test event 1001”. This message is sent to all enabled recipients.
You can also raise alerts with the ALERT TCL command.
-x This switch can be combined with any other options to produce a debug trace.
-z Used on its own, the -z option reinitialises the entire alert system. All configuration parameters, notification methods and built-in events are reset to their default states, and all user-defined events and filters are deleted.
Note: You must initialise the alert system with realevent -z before you can configure system alerts for the first time.
Can't access config file [path]
Initialise the alert system with realevent -z.
The SMS template is used to create an email that is sent to the SMS gateway server. This extracts the message and forwards it to the specified mobile phone number. The contents of the SMS template will depend on the requirements of your SMS gateway server – refer to your SMS gateway server documentation for details.
The template can contain the following codes:
%myemail% Represents the value of the myemail configuration parameter; that is, the return email address.
%smsextra% Represents the value of the smsextra configuration parameter.
When an alert is raised, these are replaced with the appropriate configuration parameter values.
The following companies can provide SMS gateway services:
| Event ID | Description | Default message | Info field | Bound Values |
|---|---|---|---|---|
| 1001 | Invalid event ID (outside the range 1001 to 4999). | Bad event code | – | None. |
| 1002 | Raised whenever a message is added to the daemon log. The bound value allows you to filter the messages according to their significance – only messages up to the level you set (that is, the more significant messages) will generate an alert. | Daemon event logged | Details of the event that generated the daemon log message. | 0 – none (default) 1 – panic 2 – alert 3 – warning 4 – notice 5 – info 6 – debug |
| 1003 | Raised when the usage of a licensed service approaches or exceeds the licensed data limit. See Web Service Licences for example. | Licensed LRUs exceeded | The name of the database, the percentage of the licensed data limit (see Bound Values) and the total data throughput for the previous shift. | 2 – 100% 3 – 95% 4 – 90% |
The following example demonstrates the procedure for configuring the alert system to use email notification:
realevent -ap myemail -v reality@deepspace.phi realevent -ap smtpserver -v mail.deepspace.phi realevent -aen smtp -r fred.bloggs@deepspace.phi;bert.smith@deepspace.phi realevent -aen html -r c:\realman\html\alerts.htm realevent -aei 1002 -b 4 realevent -aei 4001 -t "Application alert" realevent -af 1 -E * -r fred.bloggs@deepspace.phi -D mon -T 18:00-23:59 realevent -af 2 -E * -r fred.bloggs@deepspace.phi -D tue-thu -T 18:00-09:00 realevent -af 3 -E * -r fred.bloggs@deepspace.phi -D fri -T 00:00-09:00 realevent -af 4 -E * -r bert.smith@deepspace.phi -D fri -T 18:00-23:59 realevent -af 5 -E * -r bert.smith@deepspace.phi -D sat-sun -T * realevent -af 6 -E * -r bert.smith@deepspace.phi -D mon -T 00:00-09:00 realevent -l
This example does the following:
Application alert.Creates filters 1 to 6 to allow events to send messages only between 6 pm and 9 am on Monday to Friday, and at weekends (from 6 pm on Friday to 9 am on Monday). On weekdays, alert messages are sent to one SMTP recipient and at weekends, to the other.
Note: Since no filters have been created for the HTML recipient, all alerts will be logged on the web page.
Finally the configuration is displayed:
param:myemail=[reality@deepspace.phi] param:smtpserver=[mail.deepspace.phi] param:smstemplate=[] param:smsextra=[] notify:smtp enabled, recipient=[fred.bloggs@deepspace.phi;bert.smith@deepspace.phi] notify:sms disabled, recipient=[] notify:html enabled, recipient=[c:\realman\html\alerts.htm] notify:snmp disabled, recipient=[] filter:1 fred.bloggs@deepspace.phi, Events=*, Days=mon-mon, Times=18:00-23:59 filter:2 fred.bloggs@deepspace.phi, Events=*, Days=tue-thu, Times=18:00-09:00 filter:3 fred.bloggs@deepspace.phi, Events=*, Days=fri-fri, Times=00:00-09:00 filter:4 bert.smith@deepspace.phi, Events=*, Days=fri-fri, Times=18:00-23:59 filter:5 bert.smith@deepspace.phi, Events=*, Days=sat-sun, Times=* filter:6 bert.smith@deepspace.phi, Events=*, Days=mon-mon, Times=00:00-09:00 event:1001 disabled, bound=0, text=[Bad event code] event:1002 enabled, bound=4, text=[Daemon event logged] event:4001 enabled, bound=0, text=[Application alert]