Pegasus Enhancement Proposal (PEP)

PEP #: 207

Title: Email Indication Handler

Version: 1.5

Created: 08 March 2005

Authors: Yi Zhou

Status: Approved

 

Version History:

Version Date Author Change Description
1.0 28 October 2004 Yi Zhou Initial Submission
1.1 20 November 2004 Yi Zhou Updated Version
1.2 24 November 2004 Yi Zhou Added compile option to enable Email handler.
1.3 08 December 2004 Yi Zhou Updated the PEP based on 12/07/2004 comments.
1.4 07 March 2005 Yi Zhou Removed support for severity mapping.
1.5 08 March 2005 Yi Zhou Readded the severity mapping specification, indicating that it is not supported by the sendmail implementation.

 

Abstract: This PEP proposes the addition of a new Indication Handler to OpenPegasus release 2.5. The Email Indication Handler is being proposed to enable CIM indications to be delivered to a specified e-mail address.

Definition of the Problem

Email is a convenient way to send notification of a critical event to people who need to take action for the failure. However, Pegasus currently does not support event notification via e-mail.

Proposed Solution

This PEP proposes to define a new type of Indication Handler, Email Indication Handler. The Email Indication Handler will allow the indications to be delivered to a specified e-mail address.

This PEP does not address:

  • Throttling of indications; This issue is not specific to this handler; excessive indications could be an issue regardless of which type of handler is part of a subscription. Generation of excessive indications would more likely be caused by a problem with an indication provider, rather than the indication handler. (Poorly designed subscription filters could also result in generation of excessive indications.) An ill-behaved provider can be disabled via the cimprovider command. Currently, there are no good tools to help the admin determine which provider might be causing a problem. This is a generic issue for any ill-behaved provider. The only indication throttling mechanism currently available involves the use of the Repeat Notification properties of the subscription. It is up to an indication provider to honor the Repeat Notification settings of a subscription.
  • Pluggable handlers; The long term goal is to support pluggable handlers, but that feature is not proposed in this PEP.

    • The proposal would require the following changes:

    1. Define a new CIM_ListenerDestination subclass, CIM_ListenerDestinationEmail. We are planning to submit a CR defining this subclass to DMTF. If the CR can not be approved in the Pegasus 2.5 time frame, a contingent plan is to use a PG_ListenerDestinationEmail class. 
      2. The class is as follows:
// ====================================================================
// CIM_ListenerDestinationEmail
// ====================================================================
   [Description (
     "CIM_ListenerDestinationEmail describes the addresses and subject for "
     "Indications to be delivered via email.)] 

class CIM_ListenerDestinationEmail: CIM_ListenerDestination
{
      [Required, Description (
          "An array containing the addresses of the To: field in the mail "
          "message to which indications are delivered via e-mail.")]
   string MailTo [];

      [Description (
          "An array containing the addresses of the Cc: field in the mail "
          "message to which indications are delivered via e-mail.")]
   string MailCc [];

      [Required, Description (
           "A string containing the Subject: field of the mail message.")]
   string MailSubject;
};
    2. Modify Indication Service and Indication Handler Service to support the class CIM_ListenerDestinationEmail.

    3. Create and implement a new class EmailListenerDestination in a new directory EmailListenerDestination (under the directory pegasus/src/Pegasus/Handler). The existing sendmailIndicationHandler directory will be removed as it is not currently supported in Pegasus.

      4. The way the EmailIndicationHandler formats the received indications is the same as PEP206 (System Log Indication Handler). A platform-independent internal interface is created to give platform maintainers the flexibility to use different tools to send indications via e-mail. Utility "sendmail" is the default tool to be used to send the formatted indications to the specified recipients. The "To:" field of the mail message is the value of MailTo property in the CIM_ListenerDestinationEmail instance. The "Cc:" field of the mail message is the value of MailCc property in the CIM_ListenerDestinationEmail instance. The "Subject:" field of the mail message is the value of MailSubject property in the CIM_ListenerDestinationEmail instance. The "From:" field of the mail message is user@hostname (the user information is taken from System:getEffectiveUserName() and the hostname is taken from System::getHostName()).

    4. Priority: If an indication contains severity information (e.g. a subscriber may include the PerceivedSeverity property in the SELECT list of the filter condition), the PerceivedSeverity will be mapped to e-mail priority. Otherwise, default priority (Normal) is used. The mapping is: 
      5. PerceivedSeverity                    Email Priority
===================                  =================
Fatal/NonRecoverable    ===>         High 
Critical                ===>         High
Major                   ===>         High
Minor                   ===>         Normal
Degraded/Warning        ===>         Normal
Information             ===>         Low
Other                   ===>         Low
Unknown                 ===>         Normal

      NOTE: The current implementation using sendmail does not map the PerceivedSeverity to e-mail priority since there is no option to specify the e-mail priority in the sendmail interface.

    Configurability

    The Email Indication Handler is enabled by compiling with PEGASUS_ENABLE_EMAIL_HANDLER flag defined. By default, this handler is disabled and Indication Service rejects to create Email handler instance requests.

    This PEP does not propose a feature to disable an email handler at runtime. By default, the enableSubscriptionsForNonprivilegedUsers configuration property is set to false for release builds for HP-UX and Linux. Other platforms may also choose to set this configuration property to false by default. When the enableSubscriptionsForNonprivilegedUsers configuration property is set to false, operations (create, modify, delete, get, enumerate) on subscription, handler and filter instances may only be performed by privileged users. Subscription, handler and filter instances are stored in the repository. It is recommended that in packaging, the repository files are made readable only by privileged users, but packaging decisions are made by the platform maintainers. Restriction of operations on subscription, handler and filter instances to only privileged users decreases the risk of a malicious user creating subscriptions that flood a system with indications. That restriction, as well as access restrictions on the repository files, decrease the risk of subscription data (such as e-mail addresses) being read, modified or deleted by an unauthorized user. Information on the enableSubscriptionsForNonprivilegedUsers property will be documented in the Pegasus FAQ, when it is available.

    Test Plan

    A test program is added to create a subscription with email handler and indications are generated to deliver to the privileged user on the system. Users may check if notifications have been sent.

    Dependency

    Email Indication Handler has the same DMTF dependencies as PEP 206 (System Log Indication Handler). It also depends on PEP206 in these areas: 1) enhance Indication Service to support the CIM_FormattedIndicationSubscription class; 2) format received indication base on specified property vaules of TextFormat and TextFormatParameters; 3) change handler interface "handleIndication" (in the pegasus/src/Pegasus/Handler/CIMHandler.h) to include a subscriptionInstance parameter in order to retrieve subscription data.

    Schedule

    Copyright (c) 2004 EMC Corporation; Hewlett-Packard Development Company, L.P.; IBM Corp.; The Open Group; VERITAS Software Corporation

    Permission is hereby granted, free of charge, to any person obtaining a copy  of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

     THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED  "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.