Chapter 9 Troubleshooting Installation Problems

This chapter provides suggestions on how to resolve installation problems. It contains the following sections:

Troubleshooting Checklist

This section provides ideas for tracking down the source of a problem. It contains the following topics:

"Examine Installation Log Files"

"Examine Component Product Log Files"

"Verify Product Dependencies"

"Check Resources and Settings"

"Run Verification Procedures"

"Check the Distribution Media"

"Check Directory Server Connectivity"

"Verify Passwords"

"Use the prodreg Tool to Examine and Uninstall Components"

Examine Installation Log Files

If a problem occurs during installation or uninstallation, check the appropriate log file.

Installer log files are located in the directory /var/sadm/install/logs. The following table lists the log files, with their names. Most logs have two versions:

An A version of the log file records completion.

A B version of the log file contains more detailed log messages.

Table 9-1 Java Enterprise System Log File Name Formats
Logged Entity	Log File Name Format
Installer: component products	Java_Enterprise_System_install.Atimestamp Java_Enterprise_System_install.Btimestamp Java_Enterprise_System_Config_Log.id
Installer: shared components	Java_Shared_Component_Install.timestamp
Uninstaller	Java_Enterprise_System_uninstall.Atimestamp Java_Enterprise_System_uninstall.Btimestamp Java_Enterprise_System_Config_Log.id
Installation summary	Java_Enterprise_System_Summary_Report_install.timestamp Java_Enterprise_System_Summary_Report_ uninstall.timestamp

Some component products components write log files to the same directory, including Administration Server, Application Server, Directory Server, Portal Server, and Identity Server. For more information about component product log files, refer to "Component Product Facts for Troubleshooting".

To use the log files for troubleshooting, attempt to isolate the first problem that occurred. Often, the first problem leads to successive problems. Use the following sequence:

Review the installation summary file, which provides a high-level description of what was installed and configured.

If a problem occurred, see what component caused the problem. If multiple problems occurred, isolate the first.

Review the detailed log files.

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

Find the name of the component or package that caused the problem.

If there was a configuration problem, look at the configuration summary to examine the settings you used.

If there was a directory conflict, check that you did not specify a directory that is reserved by a component product.

Examine Component Product Log Files

Verify Product Dependencies

A number of components have installation-time interdependencies. Problems that affect one component can affect other components. To check for unmet interdependencies, familiarize yourself with the information in "Component Product Dependencies". Next, check the following:

Review the summary file and log files to see whether related products have failed. These may 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 components that use Directory Server?

Does the Identity Server information that you provided for Portal Server or Portal Server SRA match the information you provided for Identity Server?

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

Check Resources and Settings

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 nondefault directories that you specify, need sufficient disk space.

Network ports. During configuration, you supply port numbers for Java Enterprise System component products. 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?

Run Verification Procedures

Check the Distribution Media

If you are installing from a DVD or CD, is the media dirty? Dirty discs can result in installation problems.

Check Directory Server Connectivity

If you are installing a 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 do so. If you perform a silent installation when Directory Server is not available, the following could occur:

Identity Server or Portal Server could fail during installation.

Calendar Server, Instant Messaging, Messaging Server, and Sun Cluster software could fail during configuration.

Remove 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.

Verify Passwords

The installer requires that you enter a number of passwords for component products. If you are installing different components on different machines, it is important to ensure that you supply matching passwords on each machine.

To resolve password problems, you might need to uninstall and then reinstall. If the uninstall fails, refer to "Partial Installation Cleanup".

Use the prodreg Tool to Examine and Uninstall Components

If you have installed components but are having problems and cannot reinstall or uninstall, the prodreg tool is useful. This tool provides a graphical interface to the Solaris product registry and provides an easy interface to 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) manual page.

Partial Installation Cleanup

If the uninstaller does not succeed, it can fail so as to leave behind components or packages. In such a case, you must manually remove the components or packages in order to reinstall. You might discover this problem in the following ways:

The uninstaller fails, providing the name of the package it failed to uninstall.

You want to install a component but the installer reports that the component is already installed.

To Clean up a Partial Installation

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

pkginfo -p

The command output lists any partially installed packages. Using the package names returned, refer to Appendix D, "List of Installable Packages" to discover what component the packages belong to.

Remove components or packages.

On Solaris 9, use the prodreg tool.

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

On Solaris 8, use the pkgrm command.

The pkgrm command requires that you remove components one package at a time. This command does not update the product registry. Depending on what has happened, you can restore the archived product registry file or manually edit the product registry file so that it no longer refers to the removed components.

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

Remove the Web Server installation directory, if it is present.

Run the installer again.

The following table lists component product files and directories that you must remove.

Sample Problems and Solutions

This section provides explanations and suggested approaches for resolving sample problems.

Problem configuring IBM WebSphere as the Identity Server web container

Reason. WebSphere might not be running, or you may have specified a WebSphere value that does not match the WebSphere native configuration.

WebSphere Virtual Host (PS_IBM_VIRTUAL_HOST in the state file)

Application Server Name (PS_IBM_APPSERV_NAME in the state file)

Use the WebSphere tools to check the configuration, make sure it matches the values you are entering, and try again.

Another approach is to create new instances of the WebSphere entities and try again, as follows:

Use the adminclient.sh to start the WebSphere console.

Create a new virtual host instance and a new application server instance name.

Click the entry under Nodes (typically the host name), and select Regen WebServer Plugin.

This process saves the new entries into the plugin configuration file, which the installer checks for the legal names.

Return to the installer and enter the values you just created.

An unexpected external error occurs

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

Suggestion. 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 "Partial Installation Cleanup".

The graphical installer seems unresponsive

Reason. 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.

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

Silent installation fails with a “State File is Incompatible or Corrupted” error

Reason. If you are using a state file that was created on the same platform on which you are using it, the problem may be due to an unknown file corruption error.

If you are using a state file that was created on a different platform or version, the problem is that state files must be run on the same type of platform on which they are created. If you created the state file on Solaris 9, you cannot use it on Solaris 8, and if you created it on the x86 platform, you cannot use it on the Sparc platform.

Suggestion. If you created the state file on the same platform on which you are using it, generate a new state file and reinstall.

If the platform on which you created the state file is not the same as the platform on which you are using the file, resolve the problem by creating a new, platform-appropriate ID for the file. For instructions on how to do this, refer to "Creating a Platform-Appropriate ID".

Silent installation fails

Reason. If you edited the state file, you may have introduced errors. For example:, check the following:

Are all local host parameters set, and are they set to consistent values?

Are parameter values in the correct case?

Did you delete a required parameter without entering a replacement?

Are all port numbers valid and unassigned?

Suggestion. Regenerate the state file, using the graphical installer and saving its values, as described in "Generating a State File".

Component Product Facts for Troubleshooting

This section provides various quick tips on component products, with references to useful documentation.

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

Chapter 2, "Preparing for Installation" contains information on component interdependencies. Refer to Table 2-4 for details.

Chapter 8, "Postinstallation Configuration and Startup." Refer to the section "Starting and Stopping Component Products". This section contains per-component instructions for starting, stopping, and verifying component processes.

Administration Server

Log Files

Administration_Server_install.Atimestamp
Administration_Server_install.Btimestamp

For more information on logging options, refer to the Sun ONE Server Console 5.2 Server Management Guide (http://docs.sun.com/doc/816-6704-10). See Chapter 6, Administration Server Basics.”

Troubleshooting Information

Refer to the Sun ONE Server Console 5.2 Server Management Guide (http://docs.sun.com/doc/816-6704-10). See Chapter 1, “Installing Sun ONE Directory Server.”

Application Server

Log Files

/var/sadm/install/logs/

Sun_ONE_Application_Server_install.log

Sun_ONE_Application_Server_uninstall.log

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

/var/opt/SUNWappserver7/domains/domain1/server1/logs

server.log, for each server instance

Administration Server log directory (default location for the initial created administrative domain):

/var/opt/SUNWappserver7/domains/domain1/admin-server/logs

Configuration Files

Calendar Server

Log Files

Administration Service (csadmind): admin.log
Distributed Database Service (csdwpd): dwp.log
HTTP Service (cshttpd): http.log
Notification Service (csnotifyd): notify.log

For more information, refer to Sun ONE Calendar Server Administrator's Guide (http://docs.sun.com/doc/816-6708-10). See Chapter 3, “Managing Calendar Server.”

Configuration File

Debug Mode

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

For more information, refer to Sun ONE Calendar Server Administrator's Guide (http://docs.sun.com/doc/816-6708-10). See the following chapters:

Chapter 3, Managing Calendar Server

Chapter 12, Calendar Server Configuration Parameters

Troubleshooting Information

Chapter 3, “Managing Calendar Server” for information on troubleshooting the start-cal and stop-cal utilities.

Chapter 10, “Setting Up a High Availability (HA) Configuration” for information on troubleshooting a high availability configuration.

Directory Proxy Server

Logging

For more information, refer to the Directory Proxy Server Administration Guide (http://docs.sun.com/doc/816-6391-10). See Chapter 10, “Configuring and Monitoring Logs.”

Troubleshooting

Refer to the Directory Proxy Server Administration Guide (http://docs.sun.com/doc/816-6391-10). See Appendix B, “Directory Proxy Server FAQ, Features, and Troubleshooting.”

Directory Server

Log Files

For information on managing log files, refer to the Sun ONE Directory Server Administration Guide (http://docs.sun.com/source/816-6698-10/logs.html). See Chapter 12, “Managing Log Files.”

For information on the logconv.ps tool, which helps you analyze the access log, refer to the Sun ONE Directory Server Resource Kit Tools Reference (http://docs.sun.com/doc/816-6400-10/logconv.html). See Chapter 24, “logconv.pl.”

Troubleshooting

Refer to the Directory Server Installation and Tuning Guide (http://docs.sun.com/doc/816-6697-10). See Chapter 1, “Installing Sun ONE Directory Server.”

Identity Server

Configuration File

Debug Mode

For information, refer to the Sun ONE Identity Server 6.1 Customization and API Guide (http://docs.sun.com/doc/816-6774-10). See the following sections:

Appendix A, “AMConfig.properties File” for information about how to enable logging.

Chapter 10, “Auditing Features,” for information about debug files.

Instant Messaging

Helpful Documentation

Message Queue

Log Files

Chapter 2, “The MQ Messaging System,” for a logging overview.

Chapter 5, “Starting and Configuring a Broker,” for information about how to configure logging.

Messaging Server

Troubleshooting Documentation

Executable Location

Portal Server

Log Files and Debug Files

Portal Server uses the same log files and debug files as Identity Server. Their directories are as follows:

For information on managing Portal Server log files and debug files, refer to the Portal Server Administrator’s Guide, (http://docs.sun.com/doc/816-6748-10).

For information on managing these files, refer to the Portal Server Administration Guide. See “Administering the Desktop Service.”

The dpadmin, par, rdmgr, and sendrdm Portal Server command line utilities have options to generate debugging messages. Options are described in the Portal Server Administrator’s Guide.

Portal Server, Secure Remote Access

Debug Logs

Sun Cluster Software and Sun Cluster Agents

For information on Sun Cluster software and Sun ONE Agents for Sun Cluster, refer to the Sun Cluster 3.1 Software Installation Guide, at http://docs.sun.com/doc/816-3388.

Web Server

Log Files

There are two types of Web Server log files: the errors log file and the access log file, both located in the directory /opt/SUNWwbsvr/server_root/https-server_name/logs.

The errors log file lists all the errors the 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 ONE Web Server 6.1 Administrator’s Guide (http://docs.sun.com/doc/817-1831-10). See Chapter 10, “Using Log Files.”

Troubleshooting Information

Configuration File Directory

Debug Mode

Log output may be used for diagnostics and debugging. You can set the value of the loglevel attribute of the LOG element in the /server_root/https-server_name/config/server.xml file to the following values: fine, finer or finest. These values indicate the verbosity of debug messages, with finest giving maximum verbosity. For more information about the LOG element, refer to the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference (http://docs.sun.com/doc/817-1834-10).

A debug flag may be enabled to start the server web container in debug mode ready for attachment with a Java Platform Debugger Architecture (JPDA debugger. To do this, set the value of the jvm.debug flag of the JAVA element in the /server_root/https-server_name/config/server.xml file to true. For more information, refer to the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference (http://docs.sun.com/doc/817-1834-10).

The Sun™ ONE Studio 5, Standard Edition, plugin enables the debugging of web applications. For more information, refer to the Sun ONE Web Server 6.1 Programmer's Guide to Web Applications (http://docs.sun.com/doc/817-1833-10). See Chapter 7, “Debugging Web Applications.”