IMAP4 monitor

The IMAP4 monitor works with the SMTP monitor to test the availability and response time of an IMAP4 email service.

The following table lists the IMAP4 monitor files.

Table 1. IMAP4 monitor files
Monitor files	Name or location
Monitor executable	`nco_m_imap4`
Properties file	$ISHOME/etc/props/imap4.props
Rules file	$ISHOME/etc/rules/imap4.rules
Log file	$ISHOME/log/imap4.log

Guidelines for configuring IMAP4 monitor

The IMAP4 monitor works with the SMTP monitor by monitoring the mailbox to which the SMTP monitor sends test messages, and measuring that amount of time taken to deliver those messages.

Note: Ensure that the system clocks on the monitor host computer and the mail server are synchronized for the delivery time calculation to work correctly.

When the IMAP4 monitor has read the contents of the mailbox, it generates two different types of events:

Message-specific events
The IMAP4 monitor creates a message-specific event for each email message that it downloads from the mailbox. In this type of event, the monitor sets the $message element to Message Successfully Downloaded. The $timeToDeliver element is calculated as the time taken for the message to travel between the SMTP monitor that issued it and the mailbox that received it. The $hopCount element indicates the number of hosts the message hopped through to arrive at the mailbox.
Summary events
The monitor creates a summary event when it has processed all the messages in the mailbox. In this type of event, the $message element indicates the total number of messages successfully downloaded from the mailbox and the $totaltime element indicates the time taken to complete the requests. The $totaltime is in seconds.

Secure mail: The IMAP4 monitor supports connections to secure mail services. It can connect using SSL/TLS, or the STARTTLS command. When defining a profile element, use the securitytype field to select the appropriate security. If the mail server requires a client-side certificate for SSL encryption, use the SSL properties to specify a certificate file, key file, key password and cipher suite.

Client-side certificates

The IMAP4 monitor enables you to monitor servers that require client-side certificates for mutual authentication.

Specify the SSL certificate file, key file, and key password when creating a profile element.

Certificates must be in Privacy Enhanced Mail (PEM) format. If your certificate is in another format, you must convert it to PEM format. Certificates can be converted using software such as openSSL, which is available from http://www.openssl.org.

Note: If you always use the same certificate, key, and password in all profile elements, specify them using monitor properties instead of defining them in every profile element you create.

Mail boxes: After the IMAP4 monitor processed information contained in an email message sent by the SMTP monitor, it deletes it from the mailbox. You can use any existing mailbox to store email messages between the two monitors, even if the mailbox belongs to a real user. However, it’s recommended that you create a special mailbox account for service testing.

Configuring IMAP4 monitor service tests

Use the IMAP4 monitor configuration parameters to define service tests.

When you configure the monitor, default values are shown for the timeout and poll interval parameters. These defaults are 30 and 300 seconds respectively. Other defaults listed in the table aren’t shown during configuration but are applied when the configuration details are saved if no value has been specified.

Table 2. IMAP4 monitor configuration
Field	Description
server	The IP address of the mail server. Example is `test.mycompany.com`
description	A text field for providing descriptive information on the element.
port	The IP Port of the IMAP4 Server. Default: `143`
securitytype	The type of secure connection opened with the mail server: `NONE` - Connect without security. `SSL` - Send an SSLv2 `hello`, then negotiate SSLv2, SSLv3 or TLSv1. `STARTTLS` - Connect without security, issue a `STARTTLS` command, then establish a connection over TLSv1. Default: `NONE`
username	The name of the mailbox.
password	The password used to log in to the mailbox, if necessary.
authenticationtype	The method of authentication to use (`STANDARD` or `CRAM_MD5`) Default: `STANDARD`
sharedsecret	The shared secret for CRAM_MD5 authentication if applicable.
timeout	The time, in seconds, to wait for the server to respond. Default: `30`
poll	The time, in seconds, between each poll. Default: `300`
failureretests	The number of times to retest before indicating a failure. Default: `0`
retestinterval	The time, in seconds, to wait between each failure retest. Default: `10`

Regular expression matching

You can perform a regular expression search on the information being downloaded by entering up to 50 different regular expressions. The monitor attempts to match the contents retrieved to each of the regular expressions.

If a match for a specified regular expression is found, the matched lines (or as much as can fit in the monitor’s internal buffer) are returned in the corresponding $regexpMatchn element. If the regular expression matches more than once in the information downloaded, only the first match is returned. The status of each regular expression test is indicated by the $regexpStatusn elements. You can use the regular expression matches and their status information as criteria for service level classifications.

For information about regular expression syntax, see Table 3.

Monitor elements

In addition to the test results common to all elements, the IMAP4 monitor generates a set of test results containing data specific to IMAP4 service tests.

The following table describes the additional elements for the IMAP4 monitor.

Elements indicated by an asterisk (*) are available as attributes. The names of the attributes are shown within brackets. Absence of an asterisk indicates there’s no equivalent attribute. Attributes shown in bracket but without an element indicate that they are only available as attributes, there’s no equivalent element.

Table 3. IMAP4 monitor elements
Element	Description
`$authentication`	The type of user authentication method required by the IMAP4 server (Standard or CRAM-MD5).
`$bytesPerSec`	The average number of bytes transferred each second.
`$bytesTransferred`	The number of bytes uploaded or downloaded.
`$connectTime`	The time taken to connect to the IMAP4 server.
`$downloadTime*` (`DownloadTime`)	The time taken to download the file.
`$hopCount`	The number of hosts the message hopped through to reach the mailbox.
`$inEvent`	Indicates that this event is part of a series of events. `1` indicates that it’s not the final event. `0` indicates that it’s the final event.
`$lookupTime*`(`LookupTime`)	The time taken to obtain the IP address of the host server.
`$port*`(`Port`)	The port on which the service is monitored.
`$responseTime*` (`ResponseTime`)	The time between when the connection is established and the first byte of data is received.
`$security`	The type of secure connection opened with the mail server specified when adding an IMAP element (`NONE`, `STARTTLS` or `SSL`).
`$sentTo*`(`SentTo`)	The email address used by the SMTP monitor to send the original message.
`$smtpServer`	The name of the SMTP server from which the email was sent.
`$SSLHandshakeTime*` (`SslHandshakeTime`)	The time taken to establish the SSL connection.
`$timeToDeliver`	The time taken for an email message to travel between an SMTP monitor and its destination mailbox.
`$user*`(`ImapUser`)	The username (account name) used by the monitor to log in to the IMAP4 server.

Status message

The IMAP monitor provides status messages in the ResultMessage attribute when using IBM® Application Performance Management. These messages indicate the result of the test.

The following table describes the IMAP4 status messages.

Table 4. IMAP4 monitor status messages
Message	Description
`Message successfully downloaded`	The message was successfully downloaded.
`Downloaded x messages`	Indicates how many messages were successfully downloaded from the mailbox.
`Server not IMAP4rev1 compliant`	The IMAP4 server doesn’t comply with the IMAP4 specification (RFC2060).
`Server does not support STARTTLS capability`	The server isn’t configured correctly.
`Unable to log into server`	The monitor cannot log in to the IMAP server.
`Unrecognised response to STATUS command`	The monitor doesn’t recognize the value returned by the server.
`Unrecognised response to FETCH INTERNALDATE command`
`Failed to obtain Actual-Time-Sent header`	The monitor didn’t obtain the expected response from the server.
`Failed to obtain Actually-To header`
`Failed to obtain SMTP-Server header`

Properties

The properties and command-line options specific to the IMAP4 monitor are described in the following table.

Table 5. IMAP4 monitor properties
Property name	Property parameter	Description
`Originator`	string	Specifies the `From` field to match when retrieving test email messages sent by the SMTP monitor. The monitor retrieves only messages where the `From` field matches the string in Originator. The IMAP4 Originator must match the Originator in the SMTP monitor. Default: `SMTP-Monitor`
`SSLCertificate File`	string	The path and filename of the digital certificate file used if no certificate is explicitly specified for an HTTPS element during its creation. If the path isn’t absolute, the monitor interprets it relative to the working directory ($ISHOME/platform/arch/bin).
`SSLCipherSuite`	string	The cipher suite to use for SSL operations. For a description of possible values, see Cipher Suites. Default: `RC4:3DES:DES:+EXP`
`SSLDisableTLS`	integer	Disables TLSv1 for heritage support. Default: `0` - TLSv1 is enabled. `1` - TLSv1 is disabled.
`SSLKeyFile`	string	The file containing the SSL private key.
`SSLKeyPassword`	string	The password used to encrypt the SSL private key.

Cipher suites: The SSLCipherSuite property specifies the cipher suite used by the IMAP4 monitor. For more information about SSL settings, see SSL setting in Internet Service Monitoring.