
= MailTransportMonitor
:description: Learn about the OpenNMS {page-component-title} MailTransportMonitor that runs a synthetic test of a full email transaction (sending to delivery confirmation).

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

[cols="1,7"]
|===
| Class Name
| `org.opennms.netmgt.poller.monitors.MailTransportMonitor`
|===

== Configuration and use

.Optional monitor-specific parameters for the MailTransportMonitor
[options="header"]
[cols="1,3,2"]
|===
| 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"
|===

.Optional attributes for sendmail-test
[options="header"]
[cols="1,3,2"]
|===
| 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
|===

.Optional attributes for sendmail-host
[options="header"]
[cols="1,3,2"]
|===
| Attribute
| Description
| Default

| host
| The SMTP server address for sending mail.
| $\{ipaddr}

| port
| The SMTP server port.
| 25
|===

.Optional attributes for sendmail-protocol
[options="header"]
[cols="1,3,2"]
|===
| 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
|===

.Optional attributes for sendmail-message
[options="header"]
[cols="1,3,2"]
|===
| 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.
|===

.Optional attributes for readmail-test
[options="header"]
[cols="1,3,2"]
|===
| 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
|===

.Optional attributes for readmail-host
[options="header"]
[cols="1,3,2"]
|===
| Attribute
| Description
| Default

| host
| The target host for reading mail.
| $\{ipaddr}

| port
| The appropriate port for the protocol.
| 110
|===

.Optional attributes for readmail-protocol
[options="header"]
[cols="1,3,2"]
|===
| 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
|===

.Optional attributes for user-auth
[options="header"]
[cols="1,3,2"]
|===
| 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
|===

.Variables that you can use in the configuration
[options="header"]
[cols="1,3"]
|===
| 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.

[source, xml]
----
<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.

[source, xml]
----
<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.
