Mail Transport Monitor
Subscribe

From OpenNMS

Jump to: navigation, search

(This feature is available in OpenNMS 1.3.10 and higher.)

The Mail Transport Monitor (MTM) is an implementation of the OpenNMS Service Monitoring API (ServiceMonitor.java) that gives network managers the ability to monitor the sending and receiving of email as a complete transaction. In OpenNMS speak, this is know as a synthetic transaction and this monitor provides for monitoring a system's ability to send or serve mail by actually sending and reading email.

Use Cases

The premise of the MailTransportMonitor (MTM) is to actually complete a transaction of send ing an email message. This extends the monitoring capability of OpenNMS' current SMTP and POP3 Service Monitors that are designed to test connectivity to a mail server and perhaps test receipt of a banner issued by the server.

  1. Test that it can successfully send an email.
  2. Test that it can successfully connect to a mail server and get mailbox contents.
  3. Test that it can successfully read an email message from a mail server.
  4. Test that it can send an email and read that same email from a mail server (could be the same of 2 separate servers.

The MTM goes beyond the level of simple protocol monitoring and tests the full transaction of sending mail, reading mail, or both as a transaction. The MTM can be configured to simply test that a mail server is able to complete the transaction of sending mail. Likewise, it can test that a mail server is serving email by retrieving an email folder and alternatively checking for a message with a matching subject. It also has the capability to send an email message and check for receipt of that message by reading the contest of the mail folder of the recipient.

Design

The MTM uses OpenNMS’ implementation of the Sun JavaMail package (now open source). OpenNMS has used this package as a native (Java implementation) of sending email notifications for a couple of years. Now the implementation has been extended to support the requirements of this new service monitor. The current configuration used for sending email, was, and is still, is a system wide properties style configuration file for connecting to an SMTP mail service and sending an email message. This configuration is via a properties file called javamail-configuration.properties and it still serves as configuration for the JavaMail notification strategy. It also serves as the base configuration for the MTM, but the MTM can be configured to override any or all of the base settings via its XML configuration.

The MTM design is much like the Page Sequence Monitor (PSM) that monitors the transaction of navigating a web page in that it has the transaction defined via XML within a parameter to the monitor. The MTM also supports the same bit of indirection as the PSM in that the service assigned to an interface that is monitored by the MTM can be redirect to another host or IP address via the configuration.

So, if the use case is that host/interface that is serving mail is to be tested that it can receive email from different host, that can be configured. The same can be done in the other direction. In fact, the service assigned to a host/node can be a virtual node/interface and the entire transaction never needs to communicate directly with that virtual entity.

Implementation

To use the MTM, determine your requirement from the use cases above. The following example is an “end2end” test that results in a graph that an also be used for thresholding alerting you not only when mail is down but also when it is slow.

Example

This example sends email to the recipient, foo@gmail.com, via an SMTP server running on a localhost (127.0.0.1) and then connects and reads the email from the Gmail POPs server.

capsd-configuration.xml


    <protocol-plugin protocol="MAIL" class-name="org.opennms.netmgt.capsd.plugins.SmtpPlugin" scan="on" user-defined="false">
        <property key="port" value="25" />
        <property key="timeout" value="3000" />
        <property key="retry" value="2" />
    </protocol-plugin>

poller-configuration.xml

<service name="MAIL" interval="30000" user-defined="false" status="on">
  <parameter key="mail-transport-test">
    <mail-transport-test>
      <mail-test>
        <sendmail-test attempt-interval="3000" use-authentication="false" use-jmta="false">
          <sendmail-host host="${ipaddr}" port="25" />
          <sendmail-protocol mailer="smtpsend" />
          <sendmail-message to="foo@gmail.com" subject="OpenNMS Test Message "
            body="This is an OpenNMS test message." />
          <user-auth user-name="opennms" password="rulz" />
        </sendmail-test>
        <readmail-test attempt-interval="5000" subject-match="OpenNMS" >
          <readmail-host host="pop.gmail.com" port="995">
            <readmail-protocol ssl-enable="true" start-tls="false" transport="pop3s" />
          </readmail-host>
          <user-auth user-name="foo" password="bar"/>
        </readmail-test>
      </mail-test>
    </mail-transport-test>
  </parameter>
</service>

<monitor service="MAIL" class-name="org.opennms.netmgt.poller.monitors.MailTransportMonitor" />

Example 2

That configuration will assign this new "MAIL" protocol to any box with port 25 open. I have 13 boxes with port 25 open, but only one real mail server that has an MX record pointing to it. I turn the auto scan off and set a specific scan range for my real mail server.

capsd-configuration.xml

    <protocol-plugin protocol="MAIL" class-name="org.opennms.netmgt.capsd.plugins.SmtpPlugin" scan="off" user-defined="false">
        <property key="port" value="25" />
        <property key="timeout" value="3000" />
        <property key="retry" value="2" />
        <protocol-configuration scan="on" user-defined="false">
               <specific>1.2.3.4</specific>
       </protocol-configuration>
    </protocol-plugin>


Example 3

Quoting David's ML post:

<service name="MTM" interval="300000" status="on" >
 <parameter key="retry" value="6" />
 <parameter key="mail-transport-test" >
  <mail-transport-test> 
   <mail-test> 
    ...
   <readmail-test attempt-interval="60000" debug="true" mail-folder="INBOX" subject-match="OpenNMS Test Message" delete-all-mail="true" > 
    ...
   </mail-test>
  </mail-transport-test>
 </property>
</service>

This will cause the poller to schedule a poll 5 minutes after each successful mail test. The mail test will attempt to read the sent message 6 times at 1 minute intervals. Basically, the read test will run for a maximum of 7 minutes before failing (initial 1 minute delay + 6 retries 1 minute apart).

Schema

The XSD for this monitor:

Here is the schema definition that you can use with your favorite XML editor for authoring this element:


As XML: http://xmlns.opennms.org/xsd/mail-transport-test

As HTML-layout version: http://www.opennms.org/documentation/java-xsddocs-stable/mail-transport-test.html

Configuration Details

The MTM has embedded XML as one of the key-value parameters so familiar to each of OpenNMS' service configurations. This allows for greater flexibility configuring the monitor and is much less confusing and less error prone than having a ton of parameters. Also, a good XML editor allows for configuration validation against the XML schema.

Elements and Attributes

The two major elements of this monitor's configuration are:

<sendmail-test>

<readmail-test>

Tests

There are five basic tests that can be performed by this monitor as defined by the use cases above.

Test Sending Mail

The most basic of all tests but typically the most difficult in today's environment due to mail servers being locked down to reduce spam. The sendmail-test is highly configurable. An Exception thrown during the sending of the configured email message will cause the poll to fail.

Test Access of Mail Store and Folder

Configure a readmail-test and don't configure a subject-match attribute. This will test only the ability to open the default mail store and the configured mail folder ("INBOX") by default. Folders are given by "INBOX<seperator>Foldername"; seperator character might vary between IMAP implementations. Exchange 2010 uses "/" as seperator.

Test for Specific Message in Folder

Configure a readmail-test and a matching subject. Optionally configure the test to delete all read mail. Probably not something you want to do unless this is a mail folder that you are sending email to from another system that you can't do in the end-to-end test behavior.

Test for Sending and Receipt (end-to-end test) of a Message

This is the ultimate test of your infrastructure's ability to send and receive email. It tests sending and receiving of an mail message via one or two separate mail servers. For example, you can send email via SMTPS to one server outside of your organization addressed to a recipient on your internal mail server.

To make this happen, just configure both a sendmail-test and an readmail-test element. The MTM handles the rest of the logic. If the sendmail-test fails, the readmail-test will, obviously, not be executed.

Troubleshooting

IMAP/IMAPs readmail test

With IMAP it could be possible you have a error message in your log like this:

javax.mail.MessagingException: No login methods supported!;
  nested exception is:
        com.sun.mail.iap.ProtocolException: No login methods supported!

The error occurs also if you use the right authentication mechanism for example CRAM-MD5. A way to solve this issue is using IMAPS with SSL encryption.

If you have an signed certificate from CAcert or a self signed certificate it is necessary to import the server certificate. You will find an error message like this in your pollerd.log

javax.mail.MessagingException: No login methods supported!;

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target </pre>

To import a server certificate in the Java Virtual Machines trust store follow this steps:

1. Get the server certificate with openssl:

openssl s_client -connect <your-imap-server>:imaps

2. Copy the server certificate include ---BEGIN--- and ---END--- and save it to a file for example in imapd.pem

[root@opennms bin]# openssl s_client -connect <your-imap-server>:imaps
CONNECTED(00000003)
depth=0 CN = *.<your-domain>
.
.
.
   i:/O=Root CA/OU=http://www.cacert.org/CN=CA Cert Signing Authority/emailAddress=support@cacert.org
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIF2zCCA8OgAwIBAgIDCrA3MA0GCSqGSIb3DQEBBQUAMHkxEDAOBgNVBAoTB1Jv
b3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEiMCAGA1UEAxMZ
Q0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJARYSc3VwcG9y
.
.
.
7T45FF4KGmtpm0TeREBI8ElJXVWz+wUdEJ9lICmsXHJr/UXgI700+XQ8l9Dd0UwF
4YGYeVyhrcm3S7Bi/5ZQod8c93lHhIzdsKZzAhgvCVpp/Dj+EqgxrE2nskgP2//N
-----END CERTIFICATE-----

3. Import the certificate to your Java trust store with the following command

./keytool -import -alias mail.opennms-edu.net \
-keystore /usr/java/default/jre/lib/security/cacerts -file /path/to/imapd.pem

The default password for the Java trust store is changeit

4. Restart opennms to make the new trusted certificate available with

service opennms restart

Version History/Availability