Submitted by: Phonegi (David Buler)

Description:

This Monitoring ZenPack provides a daemon that will send emails to specified addresses and retrieve them from a specified POP mailbox.

Introduction

If  you use an email system and an Internet connection for event  notification, you have numerous single points of failure that can  prevent you from receiving alerts. The email server itself, switch,  firewall, power supply, ISP, etc...

EmailPing  is designed to monitor your alerting mechanism as a single entity and  generate events when there is a problem. When combined with SMS via  modem, (see the article HOWTO send SMS via modem with Zenoss) you can be notified if your email/Internet based alerting mechanism is down.

How EmailPing works

EmailPing is a cyclical Zenoss daemon. The delay between each cycle is defined by the emailcycleinterval setting. During each cycle, EmailPing uses the Zenoss SMTP  configuration (defined on the Settings page) to send email to one or  more toaddress(es).  The subject line of the sent email is unique  to each cycle. After sending emails, EmailPing logs into the POP  account using the pophost, popusername, and poppassword settings,  retrieves and deletes emails, then matches them to any known sent  messages. Events are generated when specific error conditions occur. See  "Events Generated by EmailPing" below.

Example Configurations

Configuration #1

Your  company uses an external email service provider. Zenoss is configured  to log in to to the email server and send alerts via SMTP. Your alerting  mechanism may look like:

To use EmailPing, you create a mailbox named zenoss_alert@mydomain.com.  Configure EmailPing to send mail to this address and retrieve mail from  the same address. You add SMS via modem and Alerting Rules to send  EmailPing events through the modem. Now you have:

Configuration #2

Your  company uses an internal email server. Zenoss is  configured to use the  local sendmail server to relay email via the internal mail server.   Your alerting mechanism may look like:

There  are numerous ways to set up EmailPing in this configuration. You could  simply set up a free Internet email account and configure EmailPing to  send and receive at that account. That would ensure that the outbound  email system and the Internet connection were working.

You  could also set up email forwarding accounts on the Internet that  forward email back to a mailbox on the mail.mydomain.com server.   EmailPing would be configured to send emails to the forwarding accounts,  but retrieve mail from the mailbox at mail.mydomain.com. This  configuration would verify outbound email, outbound Internet, external  DNS, inbound Internet, and inbound email.

Installing EmailPing

• Follow the basic instructions in the Administrator Guide to install the EmailPing ZenPack.
• Next, you need to configure the daemon before you can start it. Navigate to Settings > Daemons. Click on the emailping edit config link.
  
  The following settings are required:
  pophost - The FQDN of the POP server where mail will be retrieved
  popusername - The user name for the POP account
  poppassword - The  password for the POP account
  toaddress - The address(es) where mail will be sent to. Having more than one toaddress is recommended as it distinguishes between a single account failure and a total system failure. Separate addresses with a semicolon and no space. Example: address1@gmail.com;address2@gmail.com
  
  The following settings control options that you may want to change:
  emailcycleinterval - The number of seconds between cycles
  emailqueuelength - The maximum number of email messages that emailping will store in memory while waiting to match them to a retrieved message
  poplogintype - Either ssl or cleartext
  popport - The port number to use when connecting to the POP server. A setting of '0' uses the default port based
       on the poplogintype - either 110 for cleartext or 995 for ssl
  
• Navigate back to the Settings > Daemons page. Click on the emailping Start button. The State indicator should change from red to green
• Click on the emailping view log link to verify that emailping started without errors

Events generated by EmailPing

These  events are added when EmailPing is installed. They are located under  Status/EmailPing. All of the clear events are configured to clear their  matching error event. You may want to modify the default severity level  of each as indicated by (W)arning or (E)rror.

epSendFailure (W) - An exception occurred while trying to send an email

epSendClear - Successfully sent email following a previous exception
epPopConnectionFailure (E) -  Unable to connect to the POP server
epPopConnectionClear - Successfully connected to POP server following a failure to connect
epPopReceiveFailure (E) - No matching emails received from the POP account during this cycle
epPopReceiveClear - Matching emails received during this cycle following a previous failure
epAccountReceiveFailure (W) -  No messages received from a specific "to" address during this cycle.  The email address is assigned to the component field of the event

epAccountReceiveClear - Matching emails received from an account that failed to receive email in the previous cycle

EmailPing Performance Data

EmailPing  will automatically add performance data to the default collector. Navigate to  Collectors, then click on the collector link  (typically localhost) Finally, click on the Performance Tab.

EmailPing  adds one graph point to the Cycle Times graph. This represents the  total amount of time that it takes for EmailPing to complete execution  of a cycle.

Three more graphs are added to the Performance Tab. The firest is EmailPing Queue Lengths. Each toaddress has a queue that stores emails that are waiting to me retrieved. This graph indicates the number of emails in the queue at the end of the cycle. If your emailcycleinterval is longer than the average transit time, this number should stay at 1.

The second graph that is added to the Performance Tab is EmailPing Transit Times.  When a email message is received and matched, the header data is used  to determine how long it took for the email to reach it's destination.  There is one graph point for each toaddress.

Finally, there is the EmailPing Received Mail Count graph. This indicates the number of emails retrieved and matched for each toaddress. An unknown datapoint is also included to catagorize retrieved emails that could not be matched or were from an unknown source. This can be useful for tracking spam in the POP mailbox.

Installation Requirements:

• Zenoss Versions Supported: 2.5.x (v1.0.0), 3.x (v1.1.0)
  
• External Dependencies: <none>
• ZenPack Dependencies: <none>
  
• Installation Notes:
  zopectl restart after installing this ZenPack.
  To start daemon after installing ZenPack: emailping start
  
• Configuration: Must edit $ZENHOME/etc/emailping.conf before starting daemon.
  
  

History:

Change History:

• 1.0 initial release
• 1.1 Updated statistics and code for Zenoss 3.x
  

Tested: This ZenPack was tested with versions 2.5.2 (v1.0.0) and 3.0.2 (v1.1.0).

Source: https://github.com/zenoss/Community-Zenpacks/tree/master/ZenPacks.community.EmailPing/