Sun Java System Instant Messaging 7 2005Q1 Administration Guide |
Chapter 8
Troubleshooting and Monitoring Instant MessagingThis 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 InformationYou can obtain information about a client system from the Instant Messenger client.
To Obtain Instant Messenger Runtime Information from the About Dialog
Obtaining Instant Messenger LogsIn order to obtain Instant Messenger logs, you first need to enable logging on the client host. See Administering Client Logging for instructions.
Problems and SolutionsListed 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:
- Authentication error when the server cannot validate the session token.
- Instant Messaging channel is not configured properly. For example, incorrect Instant Messaging server host and/or port.
- 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 in the LDAP lookup.
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.
- Back up any information you might need in a future installation. See Backing Up Instant Messaging Data.
- Manually edit the product registry information.
For Solaris 9, issue the following command:
prodreg(1)
For all other systems:
- 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
- Remove the following packages or RPMs if they are still present:
Troubleshooting Instant Messaging and LDAPThe 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 MessagingInstant 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.
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
- On the command line, check your MANPATH environment variable to see if the correct paths are already there.
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
- 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:
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.
- Verify that the man pages are accessible. For example:
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
- Log in as root.
- Set the CLASSPATH to include the location of the CAC, JConsole, and the JMX jar file.
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
- Run JConsole.
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"
- On the MBeans tab, expand the XMPP tree.
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:
Solaris:
- For the mfwk agent: pkginfo SUNWmfwk-agent
- For the CAC: pkginfo SUNWcacao
- For JDMK, if the CAC is running, then the JDMK is installed. You can also check that the jar files are installed under /opt/SUNWjdmk/version/lib and /opt/SUNWjdmk/version/bin, where version is the version number of the JDMK, for example 5.1.
Linux:
- For the mfwk agent: rpm -qi sun-mfwk-agent-1.0
- For the CAC: rpm -qi sun-cacao-1.0
- For JDMK, if the CAC is running, then the JDMK is installed. You can also check that the jar files are installed under /opt/sun/jdmk/version/lib and /opt/sun/jdmk/version/bin, where version is the version number of the JDMK, for example 5.1. In addition, you can use the following command:
rpm -qi sun-jdmk-runtime-5.1
- The CAC is running. To get status on the CAC, use the following commands.
Solaris: /opt/SUNWcacao/bin/cacaoadm status
Linux: /opt/sun/cacao/bin/cacaoadm status
If CAC is not running, start it as follows:
Solaris: /opt/SUNWcacao/bin/cacaoadm start
Linux: /opt/sun/cacao/bin/cacaoadm start
- The XMPP module is loaded within the CAC and running:
- The mfwk agent is running. To get status on the mfwk agent, use the following commands.
Solaris: /opt/SUNWcacao/bin/cacaoadm status com.sun.mfwk.mfwk_module
Linux: /opt/sun/cacao/bin/cacaoadm status com.sun.mfwk.mfwk_module
If the mfwk agent is not running, start it as follows:
Solaris: /opt/SUNWmfwk/bin/mfwkadm start
Linux: /opt/sun/mfwk/bin/mfwkadm start
Troubleshooting JConsole
If you cannot bring up JConsole, ensure the following:
Managing the Watchdog ProcessThe 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
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
- Change to the directory that contains the iim.conf file.
cd im_cfg_base
- 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
- Save and close the iim.conf file.
- 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 Managing Logging.