Sun Java Communications Suite 5 Installation Guide

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:

A summary provides a high-level description of what was installed and configured.
A detail version A file contains completion information.
A detail version B file contains more details on the log messages.
A debug file contains information that is relevant when installation fails. Use the debug file when one of the other logs indicates an error.

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:

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

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.A`timestamp
	`Sun_Java_Communications_Suite_install.B`timestamp
	`Sun_Java_Communications_Suite_log.`timestamp
	`Sun_Java_Communications_Suite_Summary_Report_install.`timestamp
Uninstaller	`Sun_Java_Communications_Suite_uninstall.A`timestamp
	`Sun_Java_Communications_Suite_uninstall.B`timestamp
	`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.

Log level. There are eight log levels to choose from: SEVERE, ERROR, WARNING, INFO, CONFIG, FINE, FINER, and FINEST. If you select a log level, then only log records having that log level or are greater in severity are displayed. Selecting FINEST is equivalent to selecting all records for display.
Module ID. The module is the part of the installer that is writing the log message. If you select a module ID (JAVAESConfig, JAVAESInstall, or JAVAESUninstall), only messages associated with the module IDs you selected are displayed.
Content. The content filter prompts you for a string, such as “configure,” and then displays only those messages that contain that string.

Some typical filtering examples:

Display only the SEVERE log messages.
Display only the log messages with a log level greater than or equal to ERROR.
Display only the log messages from installation steps.
Display only the log messages from installation that have a log level greater than or equal to ERROR.
Save the result of a filtered scenario into a file.

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.

To 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:

Solaris SPARC: /var/sadm/prod/SUNWcomm-entsys5i/Solaris_sparc
Solaris x86: /var/sadm/prod/SUNWcomm-entsys5i/Solaris_x86
Linux: /var/sadm/prod/sun-comm-entsys5i/Linux_x86

Start the Log Viewer.

To run the Log Viewer in graphical mode:

./viewlog

To Use Log Files for Troubleshooting

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.

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.

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.

Review the summary file and log files to see whether related products have failed. These might provide a clue as to what to fix first.
Check that you have specified correct connection information. For example:
- Does the information that you provided when configuring Directory Server match the directory information you provided for product components that use Directory Server?
- Does the Access Manager information that you provided for Portal Server or Portal Server SRA match the information you provided for Access Manager? See the Sun Java Enterprise System 5 Installation Guide for UNIX for information on Portal Server installation.

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.

Updates. Have you applied the recommended updates (patches)?
Disk Space. How is the disk partitioned, and to what partitions do installation directories point? The installation directories /var/sadm and /etc/opt, or the non-default directories that you specify, need sufficient disk space.
Network Ports. During configuration, you supply port numbers for Communications Suite product components. Check the following:
- Examine the standard port numbers in the file /etc/services .
- Look at the summary log file to compare your settings with the standards. Did you mistype a port number or set one server to the port that is typically used for another?
- Use the command netstat -a to view current port use on the system. Did you assign a port number that was already in use?
IP Addresses. During configuration, you specify IP addresses. Check that you entered the correct IP addresses. These are some questions to resolve:
- Does this system have multiple network interfaces, each with its own IP address?
- In a high availability configuration, did you specify the IP address of the logical host or the IP address of a cluster node?

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:

You specified an incorrect user ID and password for Directory Server.
You specified an incorrect LDAP port.
Directory Server is unreachable.

The interactive modes of the installer check for Directory Server connectivity during installation, but silent mode does not. If you perform a silent installation when Directory Server is not available, installation of Access Manager could fail.

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.