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.