Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Instant Messaging 7 2005Q1 Administration Guide 

Chapter 8  
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 monitoring agent. 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 agent to monitor the general health of Instant Messaging processes to help prevent problems before they occur, asses usage levels to help you scale your deployment, and to limit downtime. This chapter contains information in the following sections:

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

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 About from the Help menu.

    2. The About dialog box appears.

  2. Select the Details tab.

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

Obtaining Instant Messenger Logs

In order to obtain Instant Messenger logs, you first need to enable logging on the client host. See Administering Client Logging for instructions.

Problems and Solutions

Listed below are some problems and their possible causes and the clues for troubleshooting these problems:

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.

The Messenger client does not load or start

The following are the possible causes for this problem:

Where to get the necessary information:

Connection refused or timed out

The following are the possible causes for this problem:

Where to get diagnostic information:

Authentication errors

The following are the possible causes for this problem:

Where to get diagnostic information:

In addition, 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.

IM channel display error

The following are the possible causes for this problem:

Where to get diagnostic information:

Instant Messaging content is not archived

The following are the possible causes for this problem:

Where to get diagnostic information:

Server-to-server communication fails to start

The following are the possible causes for this problem:

Where get diagnostic information:

The necessary information can be obtained from the two Instant Messaging server log files.

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.

  1. Back up any information you might need in a future installation. See Backing Up Instant Messaging Data.
  2. Manually edit the product registry information.

    3. For Solaris 9, issue the following command:

    prodreg(1)

    For all other 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:
    2. Solaris: /var/sadm/install/productregistry
    3. Linux: /var/tmp/productregistry
    4. Remove the following packages or RPMs if they are still present:
      • SUNWiim
      • SUNWiimc
      • SUNWiimd
      • SUNWiimid
      • SUNWiimin
      • SUNWiimjd
      • SUNWiimm

Troubleshooting Instant Messaging and LDAP

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

Issue: Your directory 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.

Solution: If your site’s directory is configured to prevent such anonymous searches, then Instant Messaging server needs to have a user ID and password it can use to bind and do searches. Use the iim_ldap.usergroupbinddn and iim_ldap.usergroupbindcred parameters to configure the necessary credentials.

Issue: Your site does not use the uid attribute for user authentication.

Solution: Use the iim_ldap.loginfilter parameter to set the attribute that is used by your directory for authentication. By default, this parameter is set to uid. Also, change any “filter” parameters that contains uid in its value.

Issue: You want to change how Instant Messenger displays contact names from the default.

Solution: The default attribute that Instant Messenger uses to display contact names is cn. Thus, contact names appear as Frank Smith, Mary Jones, and so on. Edit the iim_ldap.userdisplay and iim_ldap.groupdisplay parameters to a different attribute, such as uid.

Issue: Your directory is indexed to use wildcards.

Solution: Change the iim_ldap.allowwildcardinuid parameter to True. This parameter determines if the use of wildcards should be enabled for User IDs while doing a search. As most directory installations have User IDs indexed for exact searches only, the default value is False. Setting this value to True can impact performance unless User IDs are indexed for substring search.

Issue: Your directory uses nonstandard object/group classes.

Solution: Change the appropriate iim_ldap.* parameters, replacing inetorgperson and groupofuniquenames with your values.

Issue: Your directory does not use the mail attribute for email addresses. If so, Instant Messenger will not be able to forward instant messages to offline users as email messages.

Solution: By default, the iim_ldap.user.mailattr contains the value mail. Change this value to your site’s value.

Issue: Your directory uses an attribute other than uid as the user id attribute

Solution: If the attribute “loginname” is used as the user id attribute:

iim_ldap.user.uidattr=loginname

Add the following index directives to the indexing rules in LDAP:

index login name eq

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 CAC and the mfwk agent are installed when you installed Instant Messaging.

The mfwk agent makes XMPP module statistics available through the Java Monitoring and Management Console (JConsole). Table 8-1 describes the Instant Messaging services for which the agent exposes state and performance metrics.

Table 8-1  Instant Messaging Services Monitored by the mfwk Agent 

Category

Services

Description

Authentication

auth

Authentications.

Discovery

disco

Discovery requests.

Messages

message

Information about alerts and one-on-one chat sessions between two clients such as the speed at which messages are sent.

Conference

muc-presence, muc-admin, and muc-message

Conference statistics such as leaving or joining a conference, conference administrative requests, and conference (group chat) messages relayed.

Presence

presence-subscribe, presence-unsubscribe, presence-probe, and presence-authorize

Presence informations such as updates and subscriptions.

Privacy

private-get, private-set, privacy-get, and privacy-set

Privacy details.

Roster

roster-get and roster-set

Roster information.

Search

search

Search statistics.

This section provides information about administering and troubleshooting the mfwk agent and JConsole, and how you can use the agent and JConsole to monitor Instant Messaging in the following sections:

Administering the mfwk Agent

You use the mfwkadm command-line utility to administer the mfwk agent. For example, you can start, stop, and restart the agent, and set up new and view current performance monitoring jobs performed by the agent. Detailed instructions on using this utility are available in the mfwkadm man page. In addition, the agent runs inside the CAC. For information on the CAC, refer to the cacaoadm and cacao man pages. This section provides instructions for locating these man pages.

    To Access the mfwkadm and CAC man Pages
  1. On the command line, check your MANPATH environment variable to see if the correct paths are already there.

    2. Table 8-2 lists the paths to the man pages.

    Table 8-2  mfwkadm and CAC man page paths 

    Component

    Solaris Path

    Linux Path

    mfwkadm

    /opt/SUNWmfwk

    /opt/sun/mfwk

    CAC

    /opt/SUNWcacao/man

    /opt/sun/man

  2. If the correct path is not there, append the location of the mfwkadm utility and CAC man pages to your MANPATH environment variable. For example, on Solaris using C shell:

    3. setenv MANPATH=/usr/dt/man:/usr/man:/opt/SUNWmfwk:/opt/SUNWcacao/man

    On Linux, update /etc/man.config with the path to the man pages.

  3. Verify that the man pages are accessible. For example:

    4. man mfwkadm

Viewing Monitoring Data

Use JConsole to view the information exposed by the mfwk agent. JConsole is a graphical console tool that enables you to monitor and manage Java applications and virtual machines in your network. Using JConsole, you can browse the server JVM and also observe the Instant Messaging services described in Table 8-1.

For more information about using JConsole, see the JConsole documentation at the following locations:

http://java.sun.com/j2se/1.5.0/docs/tooldocs/share/jconsole.html

http://java.sun.com/j2se/1.5.0/docs/guide/management/jconsole.html

    To View Instant Messaging Monitoring Information Using JConsole
  1. Log in as root.
  2. Set the CLASSPATH to include the location of the CAC, JConsole, and the JMX jar file.

    3. Note

    The line should be entered as a single line.

    On Solaris:

    /opt/SUNWcacao/lib/cacao_cacao.jar:/opt/SUNWjdmk/5.1/lib/jmxremote_optional.jar:/usr/jdk/e ntsys-j2se/lib/jconsole.jar

    On Linux:

    /opt/sun/cacao/share/lib/cacao_cacao.jar:/opt/sun/jdmk/5.1/lib/jmxremote_optional.jar:/us r/jdk/entsys-j2se/lib/jconsole.jar

  3. Run JConsole.

    4. Note

    The command should be entered as a single line.

    On Solaris:

    /usr/jdk/entsys-j2se/bin/java sun.tools.jconsole.JConsole "service:jmx:cacao-jmxmp://loca lhost;wellknown=true;username=root"

    On Linux:

    /usr/jdk/entsys-j2se/bin/java sun.tools.jconsole.JConsole "service:jmx:cacao-jmxmp://loca lhost;wellknown=true;username=root"

  4. On the MBeans tab, expand the XMPP tree.

    5. The service attributes and their values are listed within the tree. See Table 8-1 for a complete list of Instant Messaging services visible through JConsole.

Troubleshooting the mfwk Agent

If you are experiencing trouble using the mfwk agent to monitor Instant Messaging, ensure the following:

Troubleshooting JConsole

If you cannot bring up JConsole, ensure the following:

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 check command. By default, the watchdog is enabled and running when you install Instant Messaging.

More information about the imadmin utility is available in Appendix B, "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:

    2. cd im_svr_base/sbin

  2. Run imadmin check:

    3. ./imadmin check 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. Change to the directory that contains the iim.conf file.

    2. cd im_cfg_base

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

    3. 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:

    5. 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 Managing Logging.



Previous      Contents      Index      Next     

Part No: 819-0430-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.