immonitor-access (Sun Java System Messaging Server 6.3 Administration Reference)

Sun Java System Messaging Server 6.3 Administration Reference

immonitor-access

Monitors the status of Messaging Server components—Mail Delivery (SMTP server), Message Access and Store (POP and IMAP servers), Directory Service (LDAP server) and HTTP server. This utility measures the response times of the various services and the total round trip time taken to send and retrieve a message. The Directory Service is monitored by looking up a specified user in the directory and measuring the response time. Mail Delivery is monitored by sending a message (SMTP) and the Message Access and Store is monitored by retrieving it. Monitoring the HTTP server is limited to finding out weather or not it is up and running.

The internal operation of immonitor-access is as follows: first it does an ldapsearch of a test user created by the administrator. This checks the Directory Server. It can then connect to the SMTP port and send a message to the mail address to check the dispatcher. Then, it checks Message Access by using the IMAP and POP server to see if the message made it to the Message Store. The command logs a message in the default log file if any of the thresholds are exceeded.

The command creates a report that contains the following information:

The state of the components
The response time
The round-trip time for that service

immonitor-access is typically run by cron at scheduled intervals to provide a snapshot of the status of the Message Access and Store components. immonitor-access can also connect to the IMAP/POP service and delete messages with the subject specified by -k. If -k is not specified, all messages containing the subject header, immonitor, are deleted.

The administrator must create a test user for use by this command before it can be executed.

Syntax

immonitor-access -u user_name { [-L LDAP_host:[port]=[threshold] ] [-b searchbase] [-I IMAP_host:[port]=[threshold] ] [-P POP_host:[port]=[threshold] ] [-H HTTP_host:[port]=[threshold] ] [-S SMTP_host:[port]=[threshold] ] [-w passwd] } [-D threshold] [-m file] [-r alert_recipients] [-A Host] [-f SOMSADMIN] [-C LMTP_host:[port]=[threshold] ] [-hdv]

immonitor-access -u user_name -w passwd { [ -I IMAP_host:[port]=[ threshold ]] [ -P POP_host: [port]=[ threshold ]]} [-k subject] -z

immonitor-access -u user_name -w passwd { [ -H HTTP_host:[port]=[ threshold ]] }

Options

The following list contains valid task options for the command.

Option	Description
`-u` `user_name`	The valid test user account to use. This test mail user has to be created by the administrator. If the test mail user is in a hosted domain, `user`@`domain` should be specified.
`-w` `passwd`	The password corresponding to the user specified with `-u`. This option is mandatory when the `-I` or `-P` is used. “`-`” can specified with `-w`, to enter the password through standard input.
`-L` `LDAP_host:` [ `port` ] = [ `threshold` ]	Use the LDAP server and the port specified to check the Directory Server. The threshold is specified in seconds.
`-I` `IMAP_host:` [ `port` ] = [ `threshold` ]	Use the IMAP server and the port specified to check the IMAP component of the Message Access. The threshold is specified in seconds. The threshold involves the time to login, retrieve, and delete the message.
`-P` `POP_host:` [ `port` ] `=` [ `threshold` ]	Use the POP server and the port specified to check the POP component of the Message Access. The threshold is specified in seconds. The threshold involves the time to login, retrieve, and delete the message.
`-S` `SMTP_host:` [ `port` ] `=` [ `threshold` ]	Use the SMTP server and the port specified to check if Messaging Server is able to accept mail for delivery. The threshold is specified in seconds.
`-C` `LMTP_host:` [ `port` ] `=` [ `threshold` ]	Use the LMTP server and the port specified to check if Messaging Server is able to deliver the message to the store. The threshold is specified in seconds.
`-H` `HTTP_host:` [`port`] `=` [ `threshold` ]	Use the HTTP server and the port specified to check if the HTTP server is able to accept requests on the specified port. When `-I -H` or `-P` is used, it is necessary to provide the test user password with `-w`. When `-S`/`-C`, `-I`/`-P` are specified together, the command does the following: - sends mail and retrieves with IMAP and POP - reports the per protocol response time - reports round-trip time o reports delivery time (the time taken to send the mail and be visible to IMAP/POP) Multiple `-I`, `-P`, and `-S` options can be specified, which helps in monitoring Messaging Server on various systems.
`-b` `searchbase`	Use search base as the starting point for the searching in the Directory Server. It is the same as `-b` of `ldap-search(1)`. If `-b` is not specified, the utility uses the value of dcRoot of the configuration parameter `local.ugldapbasedn`.
`-f` `mail From option:`	When `immonitor-access` sends out an e-mail, it usually is sent as root@`domainname`. Specify this option to send out an e-mail as different user: `-f user@red.iplanet.com`
`-D` `threshold`	The delivery (also called round-trip time) threshold. The time taken to send the mail and the mail being visible to POP/IMAP. This option can be used only when `-I`/`-P` and `-S`/`-C` are used.
`-h`	Prints command usage syntax.
`-i` `inputfile`	Read the command information from a file instead of from the command line.
`-m` `file`	The file that is mailed to the test user. You can get response and round-trip times for various mail sizes with this option. Specify only text files as non-text files result in unexpected behavior. If `-m` is not specified, the `mailfile.txt` file in `msg-svr-base/lib/locale/C/mailfile.txt` is used as the mail file.
`-k` `subject`	Header subject of the messages to be sent/deleted. The utility, by default, uses the string “immonitor:<date>” as the subject in the header sent out with the `-S` option. If `-k` is specified, the string “immonitor:subject” is used in the subject header. This option can be used with `-z` to delete messages, if `-k` is not specified, all messages with the Subject header containing “immonitor” are deleted.
`-z`	Delete messages containing the string specified by `-k` in the subject header. If `-k` is not specified, all messages with the subject header containing “immonitor” are deleted. Use `-z` only with `-I` or `-P`. Do note use `-z` with `-S` or `-C` as this can cause unexpected results.
`-r` `alert_recipients`	A comma-separated list of mail recipients who will be notified. If this option is not specified, the command reports the alert messages on the standard output.
`-A` `host`	The alternate mail server to be used to send mail to the `alert_recipients`. This option helps in sending alert messages even when the primary mail server is down or heavily loaded. If `-A` is not specified, the SMTP server on the localhost is used.
`-h`	Display the usage message.
`-d`	The debug mode: display the execution steps.
`-v`	Run in verbose mode, with diagnostics written to standard output.

The default ports are:

SMTP = 25IMAP = 143POP = 110 LDAP = 389LMTP = 225HTTP = 80

If either the port or threshold is not specified, default ports with the default threshold of 60 seconds is assumed. The threshold specified can be a decimal number.

Output

The command generates a report containing the various protocol execution times. For example:

Smtp Statistics for: thestork:25
Connect Time: 2.122 ms
Greeting Time: 5.729 ms
Helo Time: 2.420 ms
Mail From: Time: 2.779 ms
Rcpt To: Time: 4.128 ms
Data Time: 1.268 ms 
Sending File Time: 94.156 ms
Quit Time: 0.886 ms
Total SMTP Time: 113.488 Milliseconds

If the alert recipients are specified and any of the threshold values are exceeded, the command mails the report containing the service name and the response time:

ALERT: <service> exceeds threshold Response time=secs/Threshold=secs

Note that in case of times reported for IMAP, the individual times might not add up to the exact value shown by the “Total IMAP time”. This occurs because the message does not get to the store immediately. The utility loops until the message is found. Typically, the search time indicates only the successful search time. However, the total time includes each of the individual sleep and search times.

With POP, the utility needs to login and logout multiple times before the message is actually found in the store. Thus, the total time here is the accumulated time for all the logins and log outs.

Examples: To monitor the LDAP, SMTP, IMAP and POP with the threshold of 10 seconds and 250 milliseconds on localhost use:

immonitor-access -L localhost:=60.25 -S \
localhost:=60.25 -I localhost:=60.25 -P localhost:=60.25 \
-u test_user -w passwd

This example assumes that test_user exists with password “passwd.”

Exit Status

The exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error. A different exit status is returned when various thresholds are exceeded.

0	Successful execution with no errors or thresholds exceeded
1	Exceeded threshold of a service
2	Errors
64	Usage errors

An alert message is written to the console when the response time of any server exceeds the threshold.

An error message is written to the console when any of the servers cannot be reached.

Warnings

The password passed with -w can be visible to a user using the ps(1) command. It is strongly advised that you create a test user to be specifically used by the monitoring utilities.

It is recommended that you use -w and enter the password through standard input. However, if the utility is executed through cron, the password can be stored in a file. This file can be redirected as the standard input for the utility.

cat passwd_file | immonitor-access -w -
immonitor-access -w - ... < passwd_file

Do not use the echo command such as:

echo password | immonitor-access .. -w - ..

because the ps might show the echo’s arguments.

To delete the test mail sent by the -S option, invoke the immonitor-access command with the -z option separately. Do not use the two together.