MailTransportMonitor

The MailTransportMonitor runs a synthetic test of a complete email transaction, including sending a mail and determining that it has been delivered. It can also use both sendmail-test and readmail-test independently to determine whether an email can be sent or a mailbox can be read.

Tests

There are four basic tests that this monitor can perform.

Sending mail

The most basic test, the sendmail-test is highly configurable. An exception thrown during the sending of the configured email message causes the poll to fail.

Access of mail store and folder

Configure a readmail-test and don’t configure a subject-match attribute. This tests only the ability to open the default mail store and the configured mail folder (INBOX) by default. Folders are given by INBOX<separator>Foldername. The separator character might vary between IMAP implementations. Exchange uses / as a separator, for example.

Specific message in folder

Configure a readmail-test and a matching subject. Optionally, configure the test to delete all read mail. Do not 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.

Sending and receipt (end-to-end test) of a message

Test 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 and verify delivery.

Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.MailTransportMonitor

Configuration and use

Table 1. Optional monitor-specific parameters for the MailTransportMonitor
Parameter Description Default

sendmail-test

Defines the test for sending mail. Contains sendmail-host, sendmail-protocol, sendmail-message, and user-auth.

debug="true" use-authentication="false" use-jmta="true" attempt-interval="3000"

readmail-test

Defines the test for reading mail. Contains readmail-host, readmail-protocol, and user-auth.

debug="true" mail-folder="INBOX" attempt-interval="1000" delete-all-mail="false"

Table 2. Optional attributes for sendmail-test
Attribute Description Default

debug

Show additional debug output.

true

use-authentication

Whether to use authentication, in the event it is required.

false

use-jmta

Use the JavaMail Mail Transport Agent.

true

attempt-interval

Interval in milliseconds between send attempts.

3000

Table 3. Optional attributes for sendmail-host
Attribute Description Default

host

The SMTP server address for sending mail.

${ipaddr}

port

The SMTP server port.

25

Table 4. Optional attributes for sendmail-protocol
Attribute Description Default

char-set

Set the character set.

us-ascii

mailer

Use smtpsend or an alternate mailer.

smtpsend

message-content-type

Set the message content type.

text/plain

message-encoding

Set the message encoding.

7-bit

quit-wait

If set to false, the QUIT command is sent and the connection is immediately closed. If set to true (the default), it causes the transport to wait for the response to the QUIT command.

true

transport

The transport protocol to use. One of smtp or smtps.

smtp

ssl-enable

Whether to use SSL.

false

start-tls

Use the STARTTLS command (if supported or required by the server) to switch the connection to a TLS-protected connection before issuing any login commands.

false

Table 5. Optional attributes for sendmail-message
Attribute Description Default

to

The destination address.

root@localhost

from

The address to insert into the From: field.

root@[127.0.0.1]

subject

The message subject.

OpenNMS Test Message

body

The body of the message.

This is an OpenNMS test message.

Table 6. Optional attributes for readmail-test
Attribute Description Default

debug

Show additional debug output.

true

mail-folder

The folder or IMAP label to check for mail.

INBOX

subject-match

Substring match in email subjects when looking for a specific email.

no default

attempt-interval

Attempt to read email after this many milliseconds have passed; also used for retry interval.

1000

delete-all-mail

Delete all read mail after a successful match.

false

Table 7. Optional attributes for readmail-host
Attribute Description Default

host

The target host for reading mail.

${ipaddr}

port

The appropriate port for the protocol.

110

Table 8. Optional attributes for readmail-protocol
Attribute Description Default

transport

The transport protocol to use. One of: pop3, pop3s, imap, or imaps.

pop3

ssl-enable

Whether to enable SSL for the connection.

false

start-tls

Use the STARTTLS command (if supported or required by the server) to switch the connection to a TLS-protected connection before issuing any login commands.

false

Table 9. Optional attributes for user-auth
Attribute Description Default

user-name

The user name for SMTP, POP, or IMAP authentication.

opennms

password

The password for SMTP, POP, or IMAP authentication.

opennms

Table 10. Variables that you can use in the configuration
Variable Description

${ipaddr}

This value will be substituted with the IP address of the interface on which the monitored service appears.

Examples

Test for an end-to-end email transaction.

Examples use CentOS/RHEL path name. For Debian/Ubuntu, use /var/lib/opennms/rrd/response.

Note that you must include the monitor section in your definition.

<service name="MTM" interval="300000" user-defined="false" status="on">
  <parameter key="mail-transport-test">
    <mail-transport-test>
      <mail-test>
        <sendmail-test attempt-interval="30000" (1)
                       use-authentication="false" (2)
                       use-jmta="false" (3)
                       debug="false" > (4)
          <sendmail-host host="$\{ipaddr}" (5)
                         port="25" /> (6)
          <sendmail-protocol mailer="smtpsend" /> (7)
          <sendmail-message to=opennms@gmail.com  (8)
                            subject="OpenNMS Test Message" (9)
                            body="This is an OpenNMS test message." /> (10)
          <user-auth user-name="opennms" (11)
                     password="roolz" /> (12)
        </sendmail-test>
        <readmail-test attempt-interval="5000" (13)
                       subject-match="OpenNMS Test Message" (14)
                       mail-folder="OPENNMS" (15)
                       debug="false" > (16)
          <readmail-host host="imap.gmail.com" (17)
                         port="993"> (18)
            <readmail-protocol ssl-enable="true" (19)
                               start-tls="false" (20)
                               transport="imaps" /> (21)
          </readmail-host>
          <user-auth user-name=opennms@gmail.com (11)
                     password="opennms"/> (12)
        </readmail-test>
      </mail-test>
    </mail-transport-test>
  </parameter>
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/> (22)
  <parameter key="ds-name" value="mtm_lat"/> (23)
  <parameter key="retry" value="20" /> (24)
</service>

<monitor service="MTM" class-name="org.opennms.netmgt.poller.monitors.MailTransportMonitor" /> (25)
1 Interval, in milliseconds, between send attempts.
2 Whether to use authentication, in the event that it is required.
3 Use the JavaMail Mail Transport Agent.
4 Show additional debug output.
5 The SMTP server address for sending mail.
6 The SMTP server port.
7 Use smtpsend or an alternate mailer.
8 The destination address.
9 The message subject.
10 The body of the message.
11 The username for SMTP, POP, or IMAP authentication.
12 The password for SMTP, POP, or IMAP authentication.
13 Attempt to read email after this many milliseconds have passed; also used for retry interval.
14 Substring match in email subjects when looking for a specific email.
15 The folder or IMAP label to check for mail.
16 Show additional debug output.
17 The target host for reading mail.
18 The appropriate port for the protocol.
19 Whether to enable SSL for the connection.
20 Use the STARTTLS command.
21 The transport protocol to use: pop3, pop3s, imap, or imaps.
22 Base directory of an RRD repository in which to store this service monitor’s response-time samples.
23 Name of the RRD data source (DS) in which to store this service monitor’s response-time samples.
24 Number of attempts to test a service’s status
25 Required monitor section.

Test that we can connect via IMAPS and open the OPENNMS folder.

<service name="MTM-Readmail" interval="300000" user-defined="false" status="on">
  <parameter key="mail-transport-test">
    <mail-transport-test>
      <mail-test>
        <readmail-test attempt-interval="5000" (1)
                       mail-folder="OPENNMS" (2)
                       debug="false" > (3)
          <readmail-host host="imap.gmail.com" (4)
                         port="993"> (5)
            <readmail-protocol ssl-enable="true" (6)
                               start-tls="false" (7)
                               transport="imaps" /> (8)
          </readmail-host>
          <user-auth user-name=opennms@gmail.com (9)
                     password="opennms"/> (10)
        </readmail-test>
      </mail-test>
    </mail-transport-test>
  </parameter>
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/> (11)
  <parameter key="ds-name" value="rdmail_lat"/> (12)
</service>

<monitor service="MTM-Readmail" class-name="org.opennms.netmgt.poller.monitors.MailTransportMonitor" /> (13)
1 Interval, in milliseconds, between send attempts.
2 The folder or IMAP label to check for mail.
3 Show additional debug output.
4 The SMTP server address for sending mail.
5 The SMTP server port.
6 Whether to enable SSL for the connection.
7 Use the STARTTLS command.
8 The transport protocol to use: pop3, pop3s, imap, or imaps.
9 The username for SMTP, POP, or IMAP authentication.
10 The password for SMTP, POP, or IMAP authentication.
11 Base directory of an RRD repository in which to store this service monitor’s response-time samples.
12 Name of the RRD data source (DS) in which to store this service monitor’s response-time samples.
13 Required monitor section.