Documentation Comments
Use this form to comment on this topic. You can also provide any general observations about the Online Documentation, or request that additional information be added in a future release.
Reality V15.0 ()
realevent (realevent.htm)
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 boundEvent-specific bound setting.
-c configurationOption
Displays configuration help.
-D daysSpecifies the days on which an alert should be sent (filter configuration).
-d Disable.
-E eventsSpecifies the events to which a filter applies.
-e Enable.
-f filterSpecifies a filter.
-h Help.
-i eventIDSpecifies an event.
-l List configuration (lower case L.).
-m messageDefines a message.
-n notificationMethod
Specifies a notification method.
-p paramSpecifies a configuration parameter.
-r recipientSpecifies the recipient of an alert.
-s Send message (raise an alert).
-T timesSpecifies the period during which an alert should be sent (filter configuration).
-t messageSpecifies the text of a message.
-v valueSpecifies 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.
paramSpecifies 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.
valueThe 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.
recipientSpecifies 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 smsnotification 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 smtpnotification method, but leaves its configuration unchanged.
realevent -aen smtp
Enables the smtpnotification method, using the current configuration.
realevent -zn sms
Disables the smsnotification 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.
eventIDThe 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.
messageThe 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.
eventsSpecifies the IDs of the events allowed by this filter. This can be a single event ID, a range of IDs in the form
recipientSpecifies 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.
daysSpecifies 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
timesSpecifies 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.
Unable to access the config file [path]
This usually indicates that you are not the realman user on UNIX, or an user with administrator privileges on Windows, and therefore realevent is unable to create the config file.
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]