Chapter 19 Troubleshooting and Monitoring Instant Messaging

This chapter lists the common problems that might occur during installation and deployment of Instant Messaging and provides an overview of the watchdog. The log information generated by the various system components on their operation can be extremely useful when trying to isolate or troubleshoot a problem. In addition, you can use the monitoring framework agent to monitor the general health of Instant Messaging processes to help prevent problems before they occur, assess usage levels to help you scale your deployment, and to prevent downtime. This chapter contains information in the following sections:

• Troubleshooting Instant Messenger

• Problems and Solutions

• Troubleshooting Instant Messaging and LDAP

• Troubleshooting Connectivity Issues in a Multi-Node Deployment (Server Pool)

• Monitoring Instant Messaging

• Managing the Watchdog Process

For details and more information on managing server, multiplexor, watchdog, Calendar agent, and client logging, and for default log file locations, see Chapter 13, Managing Logging for Instant Messaging.

Troubleshooting Instant Messenger

Instant Messenger provides two ways for you to help troubleshoot the client. You can gather runtime information about the client system and generate an Instant Messenger log file on demand.

Obtaining Instant Messenger Runtime Information

You can obtain information about a client system from the Instant Messenger client.

To Obtain Instant Messenger Runtime Information from the About Dialog

1. In Instant Messenger, select Help->About.

   The About dialog box appears.

2. Select the Details tab.

   The Details tab contains information about the client system that you can use when troubleshooting problems.

Obtaining Instant Messenger Logs

You generate client logs as required. By default, no logs are generated. See Administering Logging for Instant Messenger for information on configuring client logging.

Problems and Solutions

Listed below are some problems and their possible causes, and information to help troubleshoot these problems:

• Unable to Connect to Instant Messaging Redirect Server from Client

• Unable to Log into Instant Messenger through the XMPP/HTTP Gateway

• Messages Not Archived With Sun Java^TM System Portal Server 7 2006Q1 or Later

• Instant Messenger Resource Customizations Lost After patchrm and patchadd

• Cannot Forward Mail to Offline Users

• Calendar Pop-up Reminders Do Not Work

• Single Sign-on Does Not Work

• Instant Messenger Does Not Load or Start

• Connection Refused or Timed Out

• Authentication Errors

• Instant Messenger Channel Display Error

• Instant Messaging Content is not Archived

• Server-to-Server Communication Fails to Start

• Catastrophic Installation Failure Leaves Server in an Inconsistent State

• Instant Messaging Services Do Not Appear in the Access Manager Console (amconsole)

Unable to Connect to Instant Messaging Redirect Server from Client

You must use a client that support XMPP redirection in order to successfully deploy the redirect server. Use Instant Messenger 2006Q1 or later, or if you use a third party client, ensure that the client that supports XMPP redirection.

Unable to Log into Instant Messenger through the XMPP/HTTP Gateway

If the XMPP/HTTP Gateway is serving two domains and the im.jnlp file contains an argument for only one domain, users not in the listed domain cannot authenticate. For example, if the im.jnlp file contains the following argument:

<argument>domain=mydomain.siroe.com</argument>

Users who attempt to log in from a domain other than mydomain will receive errors and cannot authenticate. To work around this problem, you need to configure Instant Messenger to authenticate to other domains.

To Configure Instant Messenger to Authenticate from a Specific Domain

1. Open the im.jnlp resource file.

2. Remove the domain argument entry.

   For example, remove:

   <argument>domain=mydomain.siroe.com</argument>

3. Download Instant Messenger again.

4. Run Instant Messenger.

   The Login page appears.

5. Click More Detail.

   The Login page expands to show connection settings for the client.

6. In the Server text box, enter the URL to the gateway and append ?to=domain.

   For example, if the user is part of mydomain.siroe.com, append the following to the URL:

   ?to=mydomain.siroe.com

7. To test the configuration, log in using a valid username and password.

Messages Not Archived With Sun Java^TM System Portal Server 7 2006Q1 or Later

If you have set up a Portal Archive with Sun Java System Portal Server 7 2006Q1 or later and your messages are not being archived, ensure that the iim_arch.portal.search parameter is set in iim.conf:

iim_arch.portal.search="Portal Server Search URL"

Where Portal Server Search URL is the Search URL for the Portal Server. For example:

iim_arch.portal.search="http://portal.siroe.com:8080/search1/search"

Instant Messenger Resource Customizations Lost After patchrm and patchadd

(Issue Number: 6361796) The patchrm and patchadd processes redeploy the client resources. When this occurs, all customized files are overwritten. You need to back up any customized files you want to save before performing these actions.

Cannot Forward Mail to Offline Users

By default, Instant Messaging uses the mail attribute to determine the email address to which it forwards instant messages when a recipient is offline. If your directory does not use the mail attribute for email addresses, you need to configure Instant Messaging to use the same attribute as your directory.

To Configure the Attribute Used for User Email Addresses

1. Open iim.conf.

   See iim.conf File Syntax for instructions on locating and modifying iim.conf.

2. Change the value of the iim_ldap.user.mailattr parameter to the attribute your directory uses to contain email addresses in user entries.

Calendar Pop-up Reminders Do Not Work

If Calendar pop-ups are not being delivered as expected, you can troubleshoot the configuration as described in this section. For instructions on setting up Calendar pop-ups, see Chapter 16, Using Calendar Pop-up Reminders.

The most common error in Calendar pop-up configuration is incorrectly entered parameter names in the configuration files. This includes typos and misspelled parameter names. Ensure that you have correctly entered all of the configuration parameters and values in iim.conf and ics.conf. If you have already configured pop-ups, use Table A–11 to compare your entries with the required parameters.

If your Instant Messaging and Calendar Server configuration files are correct, but pop-ups are still not arriving as expected, ensure the Calendar client and Instant Messenger are configured correctly.

To Troubleshoot Calendar Client and Instant Messenger Configuration for Pop-Ups

1. Log into the Calendar client.

2. Ensure that the time zone settings are correct.

   If you are using Calendar Express, select Tools->Options->Settings from the menu.

3. Schedule an email reminder.

   If you are using Calendar Express, select Tools->Options->Settings from the menu.

4. Save your settings.

5. Log into Instant Messenger with the same user.

6. Select Tools->Settings.

   The Settings dialog box appears.

7. Select the Alerts tab.

8. Check the Show Calendar Reminders checkbox and click OK.

9. Leave the Instant Messenger user logged in.

10. Check to see whether or not the user received the email alert and pop-up at the time configured in the Calendar client.

    If you did not receive the email alert, the Calendar client is incorrectly configured. Refer to the Calendar client documentation for further troubleshooting information.

    If you received the email alert, but not the Calendar pop-up, and you are sure that you have configured both servers and clients correctly, check the xmppd.log for further information. You may need to set this log to a more verbose setting, for example DEBUG. For instructions on changing the log level, see To Set Log Levels for Instant Messaging Components Using iim.conf Parameters.

Single Sign-on Does Not Work

If you are using SSO with Sun Java System Access Manager, the Access Manager server and Instant Messaging server must be configured to use the same web container.

Instant Messenger Does Not Load or Start

The following are the possible causes for this problem:

• Wrong codebase in the applet page.

• Application/x-java-jnlp-file MIME type not defined in the web container configuration.

• Plug-in of Java Web Start not installed or functional.

• No compatible Java version available.

• Security exception, cannot verify signature of .jar files.

Where to get the necessary information:

• In the Java Web Start or plug-in errors (exception stack trace, launch page.)

• In the applet page source on the browser.

Connection Refused or Timed Out

The following are the possible causes for this problem:

• Either the Instant Messaging server or the multiplexor is not running.

• Incorrect multiplexor host or port names used in the Applet descriptor file (.jnlp or .html).

• Different SSL settings used between Instant Messenger and the multiplexor.

• Client and server version mismatch.

Where to get diagnostic information:

• Instant Messaging server and multiplexor log files.

• Instant Messenger logs.

• Instant Messenger About dialog box, Details tab.

Authentication Errors

The following are the possible causes for this problem:

• Problems while accessing the LDAP server, such as the LDAP server is not running, or a provisioning error, such as a schema violation, has occurred.

• End user not found.

• Invalid credentials.

• Invalid Instant Messenger session.

Where to get diagnostic information:

• Instant Messaging server, Identity authentication, and LDAP log files.

• In deployments using Sun Java System Access Manager, ensure that the user entries in your Directory contain the iplanet-am-managed-person objectclass. The Instant Messaging server uses this object class when it searches for valid users in an Access Manager deployment. For more information about this object class and how Access Manager uses it, refer to the Sun Java System Access Manager documentation.

Instant Messenger Channel Display Error

The following are the possible causes for this problem:

• The server cannot validate the session token.

• Instant Messaging channel is not configured properly. For example, incorrect Instant Messaging server host, port, or both.

• Plug-in or Java Web Start is not installed or is not functional.

• End user not found and the Instant Messaging server cannot find the end user when performing an LDAP lookup.

Where to get diagnostic information:

Instant Messaging server and Instant Messaging channel logs.

Instant Messaging Content is not Archived

The following are the possible causes for this problem:

• Content is actually archived but the end user has insufficient rights to access it.

• The content has not yet been committed to the database.

• The archive provider has been disabled in the Instant Messaging server.

Where to get diagnostic information:

Instant Messaging server and the archive log files.

Server-to-Server Communication Fails to Start

The following are the possible causes for this problem:

• Incorrect server identification.

• Mismatch in the SSL settings.

Where get diagnostic information:

The Instant Messaging server log file for both servers.

Catastrophic Installation Failure Leaves Server in an Inconsistent State

If a catastrophic error occurs while installing or uninstalling Instant Messaging, the system might be left in an inconsistent state. This results in both install and uninstall being unable to complete. In this circumstance, you must manually remove all the Instant Messaging components so that a fresh install can be attempted. The clean up procedure consists of removing packages and registry information.

To Manually Remove All Instant Messaging Components

1. Back up any information you might need in a future installation.

   See Backing Up Instant Messaging Data for instructions.

2. Manually edit the product registry information.

   For Solaris 9, issue the following command:

   prodreg(1)

   For all other operating systems:

   1. Edit productregistry.xml and remove all Instant Messaging XML elements from the file.

      By default, the productregistry XML file is stored in the following locations:

      • Solaris: /var/sadm/install/productregistry

      • Linux: /var/tmp/productregistry

   2. Remove the following packages or RPMs if they are still present:

      • SUNWiim

      • SUNWiimc

      • SUNWiimd

      • SUNWiimid

      • SUNWiimin

      • SUNWiimjd

      • SUNWiimm

      • SUNWiimc-l10n

      • SUNWiimd-l10n

      • SUNWiimid-l10n

      • SUNWiimin-l10n

Instant Messaging Services Do Not Appear in the Access Manager Console (amconsole)

If Instant Messaging uses Access Manager policies in a Sun Java System Application Server deployment, you need to restart the Application Server when you finish configuring Instant Messaging. If you do not restart the Application Server, Instant Messaging services will not appear in the Access Manager console (amconsole).

Troubleshooting Instant Messaging and LDAP

The following LDAP issues might arise in a given deployment. Change the LDAP parameters in iim.conf accordingly.

Using a Directory That Does not Permit Anonymous Bind

By default, Instant Messaging server performs an anonymous search of the LDAP directory. However, it is common for sites to prevent anonymous searches in their directory so that any random person cannot do a search and retrieve all the information. If your site’s directory is configured to prevent such anonymous searches, and you didn't provide bind credentials during post-installation configuration, you need to configure the Instant Messaging server needs with a user ID and password it can use to bind and perform searches.

Use the iim_ldap.usergroupbinddn and iim_ldap.usergroupbindcred parameters to configure the necessary credentials.

To Configure Bind Credentials for the Instant Messaging Server

1. Open iim.conf.

   See iim.conf File Syntax for instructions on locating and modifying iim.conf.

2. Specify the DN you want the server to use to bind to the directory as the value for iim_ldap.usergroupbinddn.

   iim_ldap.usergroupbinddn=bind-DN

3. Specify the password that corresponds to the bind DN as the value for iim_ldap.usergroupbindcred

   iim_ldap.usergroupbindcred=password

4. Save and close the file.

Displaying Contact Names Using an Attribute Other than cn

You can customize how Instant Messenger displays contact names. The default attribute used byInstant Messenger to display contact names is cn. Contact names appear as First Name, Last Name. For example, Frank Smith, Mary Jones, and so on.

Use the iim_ldap.userdisplay and iim_ldap.groupdisplay parameters to specify which attribute to use to display contact names.

To Change the Attribute Used to Display Contact Names

1. Open iim.conf.

   See iim.conf File Syntax for instructions on locating and modifying iim.conf.

2. Specify the attribute you want to use to display user names as the value for iim_ldap.userdisplay.

   iim_ldap.userdisplay=user-name-attribute

3. Specify the attribute you want to use to display group names as the value for iim_ldap.groupdisplay

   iim_ldap.groupdisplay=group-name-attribute

4. Save and close the file.

Searching the Directory Using Wildcards

If your directory is indexed to allow the use of wildcards, and you want to be able to use wildcards while searching for contact names, you need to configure the Instant Messaging server to allow wildcard searches. However, allowing wildcard searches can impact performance unless User IDs are indexed for substring search. See Modifying How Client Users Search for Contacts for instructions on allowing wildcard searches in Instant Messaging.

Using Nonstandard Objectclasses for Users and Groups

If your directory uses nonstandard objectclasses to define users and groups you need to change the appropriate iim_ldap.* parameters, replacing inetorgperson and groupofuniquenames with your values.

See LDAP and User Registration Configuration Parameters for a list of LDAP parameters.

To Change the Objectclasses Used to Specify Users and Groups

1. Open iim.conf.

   See iim.conf File Syntax for instructions on locating and modifying iim.conf.

2. Search for and replace inetorgperson with the object class used to define users in your directory.

3. Search for and replace groupofuniquenames with the object class used to define groups in your directory.

4. Save and close the file.

Using an Attribute Other than uid for User Authentication

If your directory does not use the uid attribute for user authentication, you need to configure the Instant Messaging server with the attribute used by your directory. By default, Instant Messaging uses uid. You also need to change each filter parameter that contains uid in its value.

Use the iim_ldap.loginfilter parameter to specify which attribute to use for user authentication.

To Change the Attribute Used for User Authentication

1. Open iim.conf.

   See iim.conf File Syntax for instructions on locating and modifying iim.conf.

2. Search for and replace uid with the attribute you want to use for user authentication in the following parameters:

   • iim_ldap.loginfilter

   • iim_ldap.usergroupbyidsearchfilter

3. Save and close the file.

Using an Attribute Other than uid for User IDs

If your directory does not use the uid attribute for user IDs, you need to configure the Instant Messaging server with the attribute used by your directory. By default, Instant Messaging uses uid. In addition, you should index the attribute in the directory to help offset any performance degradation caused by searching on unindexed attributes.

Use the iim_ldap.user.uidattr parameter to specify which attribute to use for user IDs.

To Change the Attribute Used for User IDs

1. Open iim.conf.

   See iim.conf File Syntax for instructions on locating and modifying iim.conf.

2. Specify the attribute you want to use for user IDs as the value for iim_ldap.user.uidattr.

   The default value is uid.

   For example, to use the loginname attribute, set the iim_ldap.user.uidattr attribute as follows:

   iim_ldap.user.uidattr=loginname

3. Save and close the file.

4. Add the index directive to the indexing rules in LDAP:

   index loginname eq

Troubleshooting Connectivity Issues in a Multi-Node Deployment (Server Pool)

If you are receiving errors where presence status is not being shared between servers in a server pool:

• Ensure that the nodes are configured correctly to enable server-to-server communication. See Configuring Server-to-Server Communication Between Instant Messaging Servers in a Server Pool for a list of configuration parameters and appropriate values.

• Check for server-to-server session establishment errors in the log file.

Monitoring Instant Messaging

Instant Messaging provides an agent to help you monitor activity. This agent is called the monitoring framework management agent, or mfwk agent. The mfwk agent is contained within the Common Agent Container (CAC). The mfwk agent is installed with Instant Messaging. The CAC ships with Java ES and is installed using the Java ES installer. For more information about installing, enabling, and administering monitoring, as well as an overview of Instant Messaging objects monitored, see the Sun Java Enterprise System 5 Monitoring Guide.

Managing the Watchdog Process

The watchdog process monitors the server and multiplexor components and attempts to restart a component if it determines that the component is not running.

For the server, the watchdog determines whether the server is running by periodically attempting to make a connection, either directly to the server or through the multiplexor, based on the current configuration of the server. The watchdog tries to poll the server’s operational status and if it cannot determine the status, it then tries to make a connection to the server. If both operations fail, the watchdog stops and then restarts the server.

Before you use the watchdog, verify that it is enabled and running using the imadmin status command. By default, the watchdog is enabled and running when you install Instant Messaging.

More information about the imadmin utility is available in Appendix C, Instant Messaging imadmin Tool Reference.

Determining the Status of the Watchdog

You use the imadmin command-line utility to check the status of the watchdog.

To Determine the Status of the Watchdog

1. Change to the directory that contains the imadmin command-line utility.

   cd im-svr-base/sbin

2. Run imadmin status:

   ./imadmin status watchdog

   The imadmin utility returns the current status of the watchdog.

Enabling and Disabling the Watchdog

By default, the watchdog is enabled when you install Instant Messaging. You can disable or enable the watchdog by setting a configuration parameter in iim.conf.

To Enable or Disable the Watchdog

1. Open iim.conf.

   See iim.conf File Syntax for instructions on locating and modifying iim.conf.

2. Enable or disable the watchdog by setting the iim_wd.enable parameter as follows:

   To enable the watchdog: iim_wd.enable=true

   To disable the watchdog: iim_wd.enable=false

3. Save and close the iim.conf file.

4. Refresh the Instant Messaging server configuration:

   cd im-svr-base/sbin

   ./imadmin refresh

Managing Logging for the Watchdog

You manage logging for the watchdog the same way you manage logging for the server, multiplexor, and the Calendar agent. The watchdog log file is saved as im-db-base/log/iim_wd.log.

For more information on setting logging levels for all Instant Messaging components including the watchdog, see Chapter 13, Managing Logging for Instant Messaging.