Sun Java Communications Suite 5 Installation Guide

Chapter 10 Troubleshooting

This chapter provides suggestions on how to resolve Communications Suite installation and uninstallation problems.

This chapter includes the following sections:

How to Troubleshoot Problems

This section provides general guidelines for analyzing and identifying the source of problems during installation and uninstallation of Communications Suite.

This section contains the following subsections:

Examining Installation Log Files

If a problem occurs during installation or uninstallation, the first place to look for information on what happened is the installation logs. Messages on installation, uninstallation, and install-time configuration are gathered into the source log files. Informational, warning, and error messages are issued after such operations as user choices, package manipulations, and installation or uninstallation steps. Information that is displayed for each message includes date and time, log level, module ID, and the message text.

Log File Formats

There are four types of log files that capture information on an installation or uninstallation:

After an uninstallation, the uninstaller removes itself, the installer, and the Log Viewer. However, source log files are not removed and are stored in the following locations:

The following table lists the formats of the source log files.

Table 10–1 Log File Formats

Logged Entity 

Log File Name Format 

Installer 

Sun_Java_Communications_Suite_install.Atimestamp

 

Sun_Java_Communications_Suite_install.Btimestamp

 

Sun_Java_Communications_Suite_log.timestamp

 

Sun_Java_Communications_Suite_Summary_Report_install.timestamp

Uninstaller 

Sun_Java_Communications_Suite_uninstall.Atimestamp

 

Sun_Java_Communications_Suite_uninstall.Btimestamp

 

Sun_Java_Communications_Suite_UnInstall_log.timestamp

 

Sun_Java_Communications_Suite_Summary_Report_uninstall.timestamp

The log messages are stored in Unified Logging Format (ULF). If you find this format difficult to read, you can edit the source files with a text editor such as vi, or you can use the Communications Suite Log Viewer to view the log messages.

How the Log Viewer Works

The Communications Suite Log Viewer provides a graphical display for viewing the installer log messages in the Sun_Java_Communications_Suite_Install_log.timestamp file or the Sun_Java_Communications_Suite_UnInstall_log.timestamp file. There are three ways to filter messages so that the messages displayed are of sufficient importance or interest: by log level, by module ID, and by content.

Some typical filtering examples:

The following table summarizes the basic functionality of the Log Viewer.

Table 10–2 Log Viewer Functions

Task 

Capability 

Open 

Selects a log file for filter and display.  

Save 

Saves the filtered and translated messages into a file designated by the File>Save As option. 

Save As 

Chooses a separate file into which to write filtered and translated messages.  

Note: This file cannot exist in the directory used by the installer to store source logs. 

Print 

Prints the filtered and translated file. 

Exit 

Closes any open output file, closes the input file, and closes the Log Viewer page. 

Filter for Log Level  

Chooses a log level for filtering.  

Filter for Module ID 

Chooses none or one of the module IDs in the file you opened. The list is populated when you have chosen a log file for filtering. 

Filter for Content 

Selects messages that contain a user-defined string.  

Choose Language 

Chooses a translation language. Default is English. This list is populated from the translation resource bundles stored by the installer. 

With this functionality, the Log Viewer can provide filtered information to help with your troubleshooting scenario. The messages that meet your filter criteria are displayed in a single log table. A row in the log table can then be selected for detailed display which allows a message to be displayed in a multiple line format.

ProcedureTo Run the Log Viewer

Because the Log Viewer operates in read-only mode, multiple users can use the Log Viewer at the same time. After installation, the Log Viewer is located here:

  1. Start the Log Viewer.

    To run the Log Viewer in graphical mode:

    ./viewlog

ProcedureTo Use Log Files for Troubleshooting

  1. Review the summary file, for example, Sun_Java_Communications_Suite_Summary_Report_install.timestamp.

    If a problem occurred, determine which component caused the problem. If multiple problems occurred, address the first problem. You will probably need to look at one or both of the detail logs.

  2. Review the detail logs (A and B), for example, Sun_Java_Communications_Suite_install.Atimestamp.

    1. Look for the first error or warning that occurred and resolve it. Sometimes resolving one error resolves a number of seemingly unrelated errors that follow.

    2. Find the name of the component or package that caused the problem. If attempts to resolve the problem fail, examine the debug log.

  3. Examine the debug log, for example, Sun_Java_Communications_Suite_Install_log.timestamp.

Verifying Product Dependencies

A number of product components have installation-time interdependencies. Problems that affect one product component can affect other product components. First, you should familiarize yourself with the information in Sun Java Enterprise System 5 Installation Planning Guide.

In addition to product component interdependencies, some product components depend on the existence of Solaris packages that might not be installed on the host, and their absence could cause installation failures. Read the “Software Requirements” section of the Release Notes for details.

If a problem occurs starting a product component, examine that product component's log files. Locations of many product component log files are listed in Product Component Troubleshooting Tips.

Checking Resources and Settings

The following host-level issues can cause installation problems.

Checking Postinstallation Configuration

If you are having problems starting product components, verify that the procedures outlined in Chapter 6, Completing Communications Suite Postinstallation Configuration were done correctly.

Checking the Distribution Media

If you are installing from a DVD or CD, examine the media for dirt or damage. Dirty discs can result in installation problems.

Checking Directory Server Connectivity

If you are installing a product component that relies on Directory Server, problems can be caused by one of these problems:

Removing Web Server Files and Directory

To prevent the overwriting of customized files, such as edited configuration files, Web Server cannot be installed into a directory that contains files.

If you are reinstalling Web Server, check the installation directories to ensure that they are empty. If they are not empty, archive the files elsewhere and retry the installation.

Verifying Passwords

The installer requires that you enter a number of passwords for product components. If you are installing different product components on different hosts, it is important to ensure that you supply matching passwords on each host.

To resolve password problems, you might need to uninstall and then reinstall. If the uninstall fails, refer to Installation Fails Due to Leftover Files During Uninstallation.

Examining the Installed or Uninstalled Product Components

If you have installed product components but are having problems and cannot reinstall or uninstall, check the packages installed using the Solaris pkginfo command or the Linux rpm command. Compare the results with the Communications Suite packages listed in Chapter 5, List of Installable Packages, in Sun Java Enterprise System 5 Installation Reference for UNIX. Additional information is in Installation Fails Due to Leftover Files During Uninstallation.


Tip –

On Solaris 9 and Solaris 10, you can also use the prodreg tool which provides a graphical interface to the product registry that indexes both components and their packages, superseding the pkg utilities. To invoke prodreg, type the command name at the command line. For more information, refer to the prodreg(1) man page.


Verifying Administrator Access

During uninstallation, you might need to grant administrator access to the uninstaller, as described in Granting Administrator Access for the Uninstaller.

Resolving Installation Problems

This section addresses the following problems you might encounter during installation.

Installation Fails Due to Leftover Files During Uninstallation

Uninstallation can leave behind product components or packages. In such a case, you must manually remove the product components or packages before you reinstall Communications Suite. You might discover this problem in the following ways:

ProcedureTo Clean up a Partial Installation

  1. Use the following command to determine whether any packages were partially installed.

    Solaris OS: pkginfo -p

    Linux:


    rpm -qa |grep —I ^sun | xargs rpm -V

    The command output lists any partially installed packages. Using the package names returned, refer to Chapter 5, List of Installable Packages, in Sun Java Enterprise System 5 Installation Reference for UNIX to discover what product component the packages belong to.

  2. Remove components or packages.

    • On Solaris 9 or 10, use the prodreg tool.

      The prodreg tool manages the package-based components on your host. You can view product components and their packages, with full information, including interdependencies. You can use the prodreg tool to safely uninstall product components and remove packages. Once you have removed a product component with the prodreg tool, you can reinstall.

    • On Linux, use the rpm -e command.

      To edit the product registry file, open the file /var/opt/sun/install/productregistry. This XML file describes each product component. Each product component description starts with a <compid\> tag and ends with a </compid\> tag. Delete the entire entry for the product component.

  3. Verify that the following directories do not contain Communications Suite product components or packages:

    /opt

    /etc/opt

    /var/opt

  4. Run the installer again.

Installation Fails Due to Removed Shared Components in Product Registry After Uninstallation

As of the Communications Suite 5 release, shared components are listed in the product registry file after installation.

The uninstaller removes product components from the system but does not remove shared components. After an uninstallation, the product registry still contains entries for the shared components. If you manually remove any shared components after an uninstallation, these components are not removed from the product registry. Thus, the next Communications Suite 5 installation fails because the installer assumes that the manually deleted shared components are present (because they still have entries in the product registry file).


Tip –

Avoid manually removing Communications Suite shared components from your system.


Suggested Fix. Either remove the corresponding entries from the product registry file or remove the product registry file itself. Removing entries from the product registry file can cause the file to become corrupted, so you might prefer to remove the whole product registry. Before doing this, verify that products other than Communications Suite components are not using the product registry file.

On Linux there is no equivalent of the graphical product registry that exists on Solaris OS. If you manually removed files on Linux, you must manually edit the product registry file to remove those entries.

Unexpected External Error Occurs

A power failure or system failure might have occurred, or you might have entered CTRL/C to stop the installer process.

Suggested Fix. If the failure occurred during the installation or configuration process, you are probably left with a partial installation. Run the uninstaller. If the uninstaller fails, follow the instructions under Uninstallation Fails, Leaving Behind Files

Graphical Installer Seems Unresponsive

The installer sometimes creates an image on the screen before the image is ready for input. You cannot repeatedly click Next in the installation wizard without waiting.

Suggested Fix. The button that represents the default choice includes a blue rectangle. This rectangle sometimes appears after the button itself appears. Wait until you see the blue rectangle before clicking a button.

Silent Installation Fails: “State File is Incompatible or Corrupted”

If you are using a state file that was created on the same platform on which you are using it, the problem might be due to an unknown file corruption error. There are two approaches to troubleshooting this issue.

Generate a New State File

Create a New Platform-Appropriate ID

If the platform on which you created the state file is not the same as the platform on which you are running the silent installation, create a new, platform-appropriate ID for the file. For instructions on how to do this, refer to Creating a Platform-Appropriate State File ID.

Silent Installation Fails

If you edited the state file, you might have introduced errors. Check the following and regenerate the state file as described in Creating a State File.

Suggested Fix. Resolve the problem and regenerate the state file.

Man Pages Do Not Display

The most likely reason for this is that your MANPATH environment variable is not set correctly for the components you installed.

Suggested Fix. Update /etc/MANPATH to point to the new man page directory. Refer to Verifying the MANPATH.

Resolving Uninstallation Problems

This section addresses the following problems you might encounter during uninstallation.

Cannot Find Uninstaller

The installation program places the uninstaller on your system at the following location:

If the uninstaller is not in this directory, one of the following might have occurred:

Suggested Fix. Manually clean up your system as described in Uninstallation Fails, Leaving Behind Files.

Uninstallation Fails, Leaving Behind Files

If manual cleanup is necessary because the uninstaller left behind files or processes, perform the following procedure to remove packages from your system.

ProcedureTo Manually Clean Up Packages

  1. Determine which packages you want to remove.

    Compare the packages on your system with the Communications Suite packages listed in Chapter 5, List of Installable Packages, in Sun Java Enterprise System 5 Installation Reference for UNIX. You can use the Solaris pkginfo or prodreg utility or the Linux rpm command to determine which packages are installed. (See Installation Fails Due to Leftover Files During Uninstallation

  2. Stop all running processes for Communications Suite product components.

    Brief instructions for stopping processes are contained in Chapter 6, Completing Communications Suite Postinstallation Configuration product component documentation.

  3. Back up all custom configuration and user data you plan to use in subsequent installations.

    Reviewing Uninstallation Behavior for Communications Suite Product Components provides some information on configuration and user data that should be backed up. For more information, refer to the product component documentation for each product component.

  4. Use the pkgrm, rpm -e, or swremove command to remove Communications Suite component packages.

  5. Remove any remaining product component directories and their content that you do not plan to use in subsequent installations. If you do plan to use these directories later, move them elsewhere.

  6. Update the product registry file, which is located here:

    Solaris OS: /var/sadm/install/productregistry

    Linux: /var/opt/sun/install/productregistry

    The uninstaller uses this registry to determine which product components are installed on a host. Both the installer and uninstaller update the product registry upon completion of an installation or uninstallation.


    Note –

    If you manually remove packages rather than using the uninstaller, then you must edit the product registry so it correctly reflects the software installed on your system.


  7. Clean up the log files for your system, which are located here:

    Solaris OS: /var/sadm/install/logs

    Linux: /var/opt/sun/install/logs

    The log files might not correctly reflect the state of your system after you manually remove packages.

Product Registry Is Corrupted

During uninstallation, the uninstaller uses the product registry file to determine what needs to be uninstalled:

Solaris OS: /var/sadm/install/productregistry

Linux: /var/opt/sun/install/productregistry

Resolving Common Agent Container Problems

This section addresses the following problems that might arise in relation to the common agent container shared component:

Port Number Conflicts

The common agent container (V2.0) included with Communications Suite reserves the following port numbers by default:

If you are troubleshooting an installation of Sun Cluster, the port assignments are different because Sun Cluster uses a different version of common agent container. In this case, default ports are as follows:

If your installation already reserves any of these port numbers, change the port numbers used by the common agent container as described in the following procedure.

Checking Port Numbering

For further information on the common agent container cacaoadm command, see the cacaoadm man page. If you cannot see this man page at the command line, verify that your MANPATH is set correctly. Refer to Verifying the MANPATH.

ProcedureTo Verify Solaris Port

  1. As root, stop the common agent container management daemon:


    /opt/SUNWcacao/bin/cacaoadm stop
  2. Change the port number using the following syntax:

    /opt/SUNWcacao/bin/cacaoadm set-param param=value

    For example, to change the port occupied by the SNMP Adaptor from the default 11161 to 11165:


    Note –

    For Sun Cluster, use previously-specified ports.



    /opt/SUNWcacao/bin/cacaoadm set-param snmp-adaptor-port=11165
  3. Restart the common agent container management daemon:


    /opt/SUNWcacao/bin/cacaoadm start

ProcedureTo Verify Linux Port

  1. As root, stop the common agent container management daemon:


    /opt/sun/cacao/bin/cacaoadm stop
  2. Change the port number using the following syntax:

    /opt/sun/cacao/bin/cacaoadm set-param param=value

    For example, to change the port occupied by the SNMP Adaptor from 11161 to 11165:


    /opt/sun/cacao/bin/cacaoadm set-param snmp-adaptor-port=11165
  3. Restart the common agent container management daemon:


    /opt/sun/cacao/bin/cacaoadm start

Compromised Security Around the Root Password

It might be necessary to regenerate security keys on a host running Communications Suite. For example, if there is a risk that a root password has been exposed or compromised, you should regenerate security keys. The keys used by the common agent container services are stored in the following locations:

Solaris OS: /etc/opt/SUNWcacao/security

Linux: /etc/opt/sun/cacao/security

Under normal operation, these keys can be left in their default configuration. If you need to regenerate the keys due to a possible key compromise, you can regenerate the security keys using the following procedure.

Security Key Problems

ProcedureTo Generate Keys for Solaris OS

  1. As root, stop the common agent container management daemon.


    /opt/SUNWcacao/bin/cacaoadm stop
  2. Regenerate the security keys.


    /opt/SUNWcacao/bin/cacaoadm create-keys --force
  3. Restart the common agent container management daemon.


    /opt/SUNWcacao/bin/cacaoadm start

    Note –

    In the case of Sun Cluster software, you must propagate this change across all nodes in the cluster. For more information, see “How to Finish a Rolling Upgrade to Sun Cluster 3.1 8/05 Software” in Sun Cluster Software Installation Guide for Solaris OS.


ProcedureTo Generate Keys for Linux

  1. As root, stop the common agent container management daemon.


    /opt/sun/cacao/bin/cacaoadm stop
  2. Regenerate the security keys.


    /opt/sun/cacao/bin/cacaoadm create-keys --force
  3. Restart the common agent container management daemon.


    /opt/sun/cacao/bin/cacaoadm start

    For more information on the cacaoadm(1M) command, see the cacaoadm man page.

Product Component Troubleshooting Tips

The tables in this section provide various quick tips on troubleshooting product component problems, including references to useful documentation. This section contains the following subsections:

Access Manager Troubleshooting Tips

Table 10–3 Access Manager Troubleshooting Tips

Topic 

Details 

Configuration File

AMConfig.properties

  • Solaris OS: /etc/opt/SUNWam/config

  • Linux: /etc/opt/sun/identity/config

Log and Debug Files

Log file directory: 

  • Solaris OS: /var/opt/SUNWam/logs

  • Linux: /var/opt/sun/identity/logs

    Debug file directory:

  • Solaris OS: /var/opt/SUNWam/debug

  • Linux: /var/opt/sun/identity/debug

Debug Mode

Refer to the Auditing Features chapter in the Sun Java System Access Manager 7.1 Developer’s Guide.

Application Server Troubleshooting Tips

Table 10–4 Application Server Troubleshooting Tips

Topic 

Details 

Log Files

Log file directory: 

  • Solaris OS: /var/sadm/install/logs/

  • Linux: /var/opt/sun/install/logs/

Application Server instance log directory (default location for the initially created instance): 

  • Solaris OS: /var/opt/SUNWappserver/domains/domain1/logs

  • Linux: /var/opt/sun/appserver/domains/domain1/logs

Message log file name: 

server.log, for each server instance

Configuration Files

  • Solaris OS: /opt/SUNWappserver/appserver/config/asenv.conf

  • Linux: /var/opt/sun/appserver/config/asenv.conf

Troubleshooting

Refer to the Sun Java System Application Server Enterprise Edition 8.2 Troubleshooting Guide.

Calendar Server Troubleshooting Tips

Table 10–5 Calendar Server Troubleshooting Tips

Topic 

Details 

Log Files

Administration Service (csadmind): admin.log

Distributed Database Service (csdwpd): dwp.logHTTP Service (cshttpd): http.log

Notification Service (csnotifyd): notify.logCalendar

Backup Service (csstored): store.log

Default log directory:  

  • Solaris: /var/opt/SUNWics5/logs

  • Linux: /var/opt/sun/calendar/logs

For more information, refer to Sun Java System Calendar Server 6.3 Administration Guide.

Configuration File

Solaris: /opt/SUNWics5/cal/config/ics.conf

Linux: /opt/sun/calendar/config/ics.conf

Debug Mode

To use debug mode, a Calendar Server administrator sets the logfile.loglevel configuration parameter in the ics.conf file. For example:

logfile.loglevel = "debug"

For more information, refer to Sun Java System Calendar Server 6.3 Administration Guide.

Troubleshooting

Refer to Sun Java System Calendar Server 6.3 Administration Guide.

Communications Express Troubleshooting Tips

Table 10–6 Communications Express Troubleshooting Tips

Topic 

Details 

Log Files

Default log files: uwc-deployed-path/logs/uwc.log

Instance Directory

Solaris OS: /var/opt/SUNWuwc

Linux: /var/opt/sun/uwc

Troubleshooting

Refer to the Chapter 5, Troubleshooting, in Sun Java System Communications Express 6.3 Administration Guide.

Delegated Administrator Troubleshooting Tips

Table 10–7 Delegated Administrator Troubleshooting Tips

Topic 

Details 

Log Files

Runtime log file: 

Solaris: /opt/SUNWcomm/log

Troubleshooting

Refer to Appendix C, Debugging Delegated Administrator, in Sun Java System Delegated Administrator 6.4 Administration Guide.

Directory Server Troubleshooting Tips

Table 10–8 Directory Server Troubleshooting Tips

Topic 

Details 

Log Files

Installation log file: 

  • Solaris: /var/sadm/install/logs

  • Linux: /var/opt/sun/install/logs

Troubleshooting

Refer to Part I, Directory Server Administration, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide

Refer to Part II, Directory Proxy Server Administration, in Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide.

Instant Messaging Troubleshooting Tips

Table 10–9 Instant Messaging Troubleshooting Tips

Topic 

Details 

Log Files

Server log: xmppd.log

Agent calendar log: agent-calendar.log

WatchDog log: iim_wd.log

Multiplexor log: mux.log.log

Default log directory: 

  • Solaris: /var/opt/SUNWiim/default/log

  • Linux: /var/opt/sun/im/default/log

For more information, refer to Sun Java System Instant Messaging 7.2 Administration Guide

Configuration File

Solaris: /opt/SUNWiim/config/iim.conf

Linux: /opt/sun/im/config/iim.conf

Debug Mode

To use debug mode, an Instant Messaging administrator sets the iim.log.iim_server.severity configuration parameter in the iim.conf file.

Example for the server component: 

iim.log.iim_server.severity = "DEBUG"

Example for the multiplexor component: 

iim.log.iim_mux.severity = "DEBUG"

Example for the watchdog component: 

iim.log.iim_wd.severity = "DEBUG"

Troubleshooting

For further specifics and additional information on troubleshooting, refer to Sun Java System Instant Messaging 7.2 Administration Guide.

Post-Uninstallation Tasks

Instant Messaging configuration directories and Instant Messages resources deployed in the web container are not removed during uninstallation and should be removed after uninstallation.  

To completely remove Instant Messaging from a host, unnecessary directories such as the following should be removed: /opt/SUNWiim/, /var/opt/SUNWiim/, and /etc/opt/SUNWiim/.

In addition, resources should be undeployed from the web container using the undeploy all command.

Message Queue Troubleshooting Tips

Table 10–10 Message Queue Troubleshooting Tips

Topic 

Details 

Log Files

Installation log file: 

  • For Solaris OS: /var/sadm/install/logs

  • For Linux: /var/opt/sun/install/logs

Broker log file: 

  • Solaris: /var/mq/instances/instance-name/log

  • Linux: /var/opt/sun/imq/instances/instance-name/log

Troubleshooting

Refer to the Troubleshooting Problems chapter of the Sun Java System Message Queue 3 2005Q4 Administration Guide.

For performance problems, refer to “Analyzing and Tuning a Message Service” in the Sun Java System Message Queue 3 2005Q4 Administration Guide.

Messaging Server Troubleshooting Tips

Table 10–11 Messaging Server Troubleshooting Tips

Topic 

Details 

Executable Location

Process log files: 

  • For Solaris OS: /opt/SUNWmsgsr/sbin

  • For Linux: /opt/sun/messaging/sbin

Configure log files: 

  • MessagingServer-base/install

Log Files

  • For Solaris OS: MessagingServer-base/data/log

  • For Linux: /opt/sun/messaging/log

Troubleshooting

Refer to the Sun Java System Messaging Server 6.3 Administration Guide.

Monitoring Console Troubleshooting Tips

Table 10–12 Monitoring Console Troubleshooting Tips

Topic 

Details 

Configuration Files

For Monitoring Console: 

  • For Solaris OS: /opt/SUNWjesmc/WEB-INF/web.xml

  • For Linux: /opt/sun/jesmc/WEB-INF/web.xml

For Monitoring Framework: 

  • For Solaris OS: /etc/opt/SUNWmfwk/config/mfwk.properties

  • For Linux: /etc/opt/sun/mfwk/config/mjwk.properties

Log Files

For Monitoring Console: 

  • /var/log/webconsole/console/console_config_log (all platforms)

  • /var/log/webconsole/console/console_debug_log (all platforms

For Monitoring Framework: 

  • For Solaris OS: /var/opt/SUNWmfwk/logs

  • For Linux: /var/opt/sun/mfwk/logs

Troubleshooting

If you cannot access Monitoring Console, refer to Troubleshooting the Monitoring Console in Sun Java Enterprise System 5 Monitoring Guide. If you cannot see your monitored components in the Monitoring Console, refer to Troubleshooting the Monitoring Framework in Sun Java Enterprise System 5 Monitoring Guide

Web Server Troubleshooting Tips

Table 10–13 Web Server Troubleshooting Tips

Topic 

Details 

Log Files

There are two types of Web Server log files: the errors log file and the access log file. The errors log file lists all the errors a server has encountered. The access log records information about requests to the server and the responses from the server. For more information, refer to the Sun Java System Web Server 7.0 Administrator’s Guide.

These logs are located in the following directories: 

  • Solaris OS: /var/opt/SUNWwbsvr7/https-instancename/logs

  • Linux: /var/opt/sun/webserver7/https-instancename/logs

If Web Server configuration fails during Configure Now installation, refer to the following logs for additional information: 

  • Solaris OS: /var/opt/SUNWwbsvr7/setup/WebServer_Install.log

  • Linux: /var/opt/sun/webserver7/setup/WebServer_Install.log

Configuration File Directory

  • Solaris OS: /var/opt/SUNWwbsvr7/https-instance-name/config

  • Linux: /var/opt/sun/webserver7/https-instance-name/config

Additional Troubleshooting Information

The following information in this guide is also useful for troubleshooting: