Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java Enterprise System 2005Q1 Installation Guide 

Chapter 13
Troubleshooting

This chapter provides suggestions on how to resolve Sun Java™ Enterprise System (Java ES) installation and uninstallation problems.

This chapter includes the following sections:

Troubleshooting Techniques

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

This section contains the following subsections:

Examine Installation Log Files

If a problem occurs during installation or uninstallation, check the appropriate log file in the logs directory:

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

Examining the uninstall and installer log files (along with the Java ES configuration log and component logs) can help locate the source of problems. For example, you can compare the packages listed in the installation log to the packages listed in the uninstallation log.

Most logs have two versions:

The following table lists the formats of the log files.

Table 13-1  Java ES Log File Name Formats 

Logged Entity

Log File Name Format

Installer: components

Java_Enterprise_System_install.Atimestamp

Java_Enterprise_System_install.Btimestamp

Java_Enterprise_System_Config_Log.id

Installer: shared components

Java_Enterprise_System_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

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:

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

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

  2. Review the detailed log files.
    1. 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.
    2. Find the name of the component or package that caused the problem.

The log files can give you clues that determine your next steps, such as these:

Examine Component Log Files

If a problem occurs starting a component, examine its log files. Locations of many component log files are listed in Component Troubleshooting Tips.

Verify Product Dependencies

A number of components have installation-time interdependencies. Problems that affect one component can affect other components. First, you should familiarize yourself with the information in How Do Component Interdependencies Affect My Installation?. Next, check the following:

In addition to component interdependencies, some 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.

Check Resources and Settings

The following host-level issues can cause installation problems.

Check Postinstallation Configuration

If you are having problems starting components, verify that the procedures outlined in Chapter 10, "Configuring Components After Installation" were done correctly.

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

Check Directory Server Connectivity

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

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 or Portal Server could fail.

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 components. If you are installing different 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.

Examine the Installed or Uninstalled Components

If you have installed components but are having problems and cannot reinstall or uninstall, check the packages installed using the Solaris pkginfo or the Linux rpm command. Compare the results with the Java ES packages listed in Appendix F, "List of Installable Packages" to determine which products were not uninstalled. 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.

Verify Administrator Access

During uninstallation, you might need to grant administrator access to the uninstaller, as described in Granting Administrator Access for the Uninstaller. Make sure you provide the correct user IDs and passwords during uninstallation.

Installation Problems

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

Installation Fails Due to Leftover Files During Uninstallation

If an uninstallation fails, it can leave behind components or packages. In such a case, you must manually remove the components or packages before you reinstall Java ES. You might discover this problem in the following ways:

    To Clean up a Partial Installation
  1. Use the following command to determine whether any packages were partially installed.

    2. For Solaris:

    pkginfo -p

    For Linux:

    rpm -qa |grep sun | xargs rpm -V

    The command output lists any partially installed packages. Using the package names returned, refer to Appendix F, "List of Installable Packages" to discover what 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 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 opens with a <compid> tag and closes with a </compid> tag. Delete the entire entry for the component.

    • 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 component. Each component description starts with a <compid> tag and ends with a </compid> tag. Delete the entire entry for the component.

  3. Remove the Web Server installation directory, if it is present.
  4. Run the installer again.

Cannot Configure IBM WebSphere as the Portal Server Web Container

WebSphere might not be running, or you might have specified a WebSphere value that does not match the WebSphere native configuration. There are two approaches to troubleshooting this issue.

Check the Configuration

One approach is to check the configuration of your WebSphere instance.

  1. Ensure that WebSphere is running.
  2. Examine the values for the following installer fields:
    • WebSphere Virtual Host (PS_IBM_VIRTUAL_HOST in the state file)
    • Application Server Name (PS_IBM_APPSERV_NAME in the state file)
  3. Use the WebSphere tools to check the configuration to make sure it matches the values you are entering
  4. Try again.

Create New Instances

Another approach is to create new instances of the WebSphere entities.

  1. Use the adminclient.sh to start the WebSphere console.
  2. Create a new virtual host instance and a new Application Server instance name.
  3. Click the entry under Nodes (typically the host name), and select Regen WebServer Plugin.

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

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

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.

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. Refer to MANPATH Setup.

Uninstallation Problems

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

Cannot Find Uninstaller

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

/var/sadm/prod/entsys/

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.

    To Manually Clean Up Packages
  1. Determine which packages you want to remove.

    2. Compare the packages on your system with the Java ES packages listed in Appendix F, "List of Installable Packages". 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 Java ES components.

    3. Brief instructions for stopping processes are contained in Chapter 11, "Starting and Stopping Components". Component Troubleshooting Tips provides some information on each component, with links to component documentation.

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

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

  4. Use the pkgrm or rpm -e command to remove Java ES component packages.
  5. Remove any remaining 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:

    7. On Solaris: /var/sadm/install/productregistry
    On Linux: /var/opt/sun/install/productregistry

    The uninstaller uses this registry to determine which 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:

    8. Solaris: /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:

On Solaris: /var/sadm/install/productregistry
On Linux: /var/opt/sun/install/productregistry

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 inside Java ES occupies the following port numbers by default:

If your installation already reserves any of these port numbers, change the port numbers occupied by the common agent container as follows.

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

    2. # /opt/SUNWcacao/bin/cacaoadm stop

  2. Change the port number using the following syntax:

    3. # /opt/SUNWcacao/bin/cacaoadm set-param param=value

    For example, to change the port occupied by the SNMP Adaptor from the default 10161 to 10165:

    # /opt/SUNWcacao/bin/cacaoadm set-param snmp-adaptor-port=10165

  3. Restart the common agent container management daemon:

    4. # /opt/SUNWcacao/bin/cacaoadm start

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

    2. # /opt/sun/cacao/bin/cacaoadm stop

  2. Change the port number using the following syntax:

    3. # /opt/sun/cacao/bin/cacaoadm set-param param=value

    For example, to change the port occupied by the SNMP Adaptor from 10161 to 10165:

    # /opt/sun/cacao/bin/cacaoadm set-param snmp-adaptor-port=10165

  3. Restart the common agent container management daemon:

    4. # /opt/sun/cacao/bin/cacaoadm start

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 MANPATH Setup.

Compromised Security Around the Root Password

It might be necessary to regenerate security keys on a host running Java ES. 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: /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.

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

    2. # /opt/SUNWcacao/bin/cacaoadm stop

  2. Regenerate the security keys.

    3. # /opt/SUNWcacao/bin/cacaoadm create-keys --force

  3. Restart the common agent container management daemon.

    4. # /opt/SUNWcacao/bin/cacaoadm start

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

    2. # /opt/sun/cacao/bin/cacaoadm stop

  2. Regenerate the security keys.

    3. # /opt/sun/cacao/bin/cacaoadm create-keys --force

  3. Restart the common agent container management daemon.

    4. # /opt/sun/cacao/bin/cacaoadm start

    Note

    In the case of Sun Cluster, you must propagate this change across all nodes in the cluster. For more information, see the Sun Cluster System Administration Guide, http://docs.sun.com/doc/817-6546.

For more information on the cacaoadm command, see the cacaoadm man page.

Error Notification About Lock File

When you issue a cacaoadm subcommand, it is possible that another user issued a command at exactly the same time. However, only one cacaoadm subcommand can be run at a time.

On Solaris, the following error message is generated:

If cacaoadm daemon is running, it is busy executing another command.
Otherwise remove lock file /var/opt/SUNWcacao/run/lock

On Linux, the following error message is generated:

If cacaoadm daemon is running, it is busy executing another command.
Otherwise remove lock file /var/opt/sun/cacao/run/lock.

The first recommended action when you receive this notification message is to wait a few moments and retry.

If you receive the same notification message when you retry, then it is possible that a lock file has not been removed by the common agent container management daemon. This can happen in the case of a crash. The lock file prevents further cacaoadm subcommands from being run.

Remove the lock file from the location indicated in the error message.

Component Troubleshooting Tips

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

This section contains the following subsections:

Access Manager Troubleshooting Tools

Table 13-2  Access Manager Troubleshooting Tools 

Topic

Details

Configuration File

AMConfig.properties

Solaris: /etc/opt/SUNWam/config
Linux: /etc/opt/sun/identity/config

Log and Debug Files

Log file directory:

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

Debug file directory:

  • Solaris: /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 Developer’s Guide (http://docs.sun.com/doc/817-7649).

Administration Server Troubleshooting Tools

Table 13-3  Administration Server Troubleshooting Tools 

Topic

Details

Log Files

Installation log directory:

  • AdministrationServer-base/admin-serv/logs/

Configuration log files:

  • Administration_Server_install.Atimestamp
    Administration_Server_install.Btimestamp

For more information on logging options, refer to the Sun Java System Administration Server Administration Guide (http://docs.sun.com/doc/817-7612).

Troubleshooting

Refer to the Sun Java System Administration Server Administration Guide (http://docs.sun.com/doc/817-7612).

Application Server Troubleshooting Tools

Table 13-4  Application Server Troubleshooting Tools 

Topic

Details

Log Files

Log file directory:

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

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

Solaris: /var/opt/SUNWappserver/domain/domain1/logs
Linux: /var/opt/sun/appserver/domains/domain1/logs

Message log file name:

  • server.log, for each server instance

Configuration Files

Configuration file directory: /var

Troubleshooting

Refer to the Sun Java System Application Server Enterprise Edition Troubleshooting Guide (http://docs.sun.com/doc/819-0086).

Calendar Server Troubleshooting Tools

Table 13-5  Calendar Server Troubleshooting Tools 

Topic

Details

Log Files

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

Default log directory: /var/opt/SUNWics5/logs

For more information, refer to Sun Java System Calendar Server Administration Guide (http://docs.sun.com/doc/819-0024).

Configuration File

/opt/SUNWics5/cal/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 Administration Guide (http://docs.sun.com/doc/819-0024).

Troubleshooting

Refer to Sun Java System Calendar Server Administration Guide (http://docs.sun.com/doc/819-0024).

Communications Express Troubleshooting Tools

Table 13-6  Communications Express Troubleshooting Tools 

Topic

Details

Log Files

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

Troubleshooting

Refer to the "Troubleshooting" chapter in the Sun Java System Communications Express Administration Guide, http://docs.sun.com/doc/819-0115.

Directory Proxy Server Troubleshooting Tools

Table 13-7  Directory Proxy Server Troubleshooting Tools 

Topic

Details

Log Files

Default log file: dps_svr_base/dps-hostname/logs/fwd.log

For more information, refer to the Sun Java System Directory Proxy Server Administration Guide (http://docs.sun.com/doc/817-7615).

Troubleshooting

Refer to the Sun Java System Directory Proxy Server Administration Guide (http://docs.sun.com/doc/817-7615).

Directory Server Troubleshooting Tools

Table 13-8  Directory Server Troubleshooting Tools 

Topic

Details

Log Files

Installation log file:

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

Configuration log files:

  • Directory_Server_install.Atimestamp
    Directory_Server_install.Btimestamp

For information on managing log files, refer to the Sun Java System Directory Server Administration Guide (http://docs.sun.com/doc/817-7613).

Troubleshooting

Refer to the Sun Java System Directory Server Administration Guide (http://docs.sun.com/doc/817-7613).

Instant Messaging Troubleshooting Tools

For information on troubleshooting Instant Messaging, refer to the client online help and the Sun Java System Instant Messaging Administration Guide (http://docs.sun.com/doc/819-0430).

Message Queue Troubleshooting Tools

Table 13-9  Messaging Server Troubleshooting Tools 

Topic

Details

Troubleshooting

Refer to the Troubleshooting Problems chapter of the Sun Java System Message Queue Administration Guide and the MQ Forum, at: http://swforum.sun.com/jive/forum.jspa?forumID=24.

Additional articles are available in Knowledge Base, at http://developers.sun.com/prodtech/msgqueue/reference/techart/index.html

Performance

Refer to the “Analyzing and Tuning a Message Service” chapter in the Sun Java System Message Queue Administration Guide (http://docs.sun.com/doc/819-0066).

Messaging Server Troubleshooting Tools

Table 13-10  Messaging Server Troubleshooting Tools 

Topic

Details

Executable Location

/opt/SUNWmsgsr/sbin

Log Files

MessagingServer-base/data/log

Troubleshooting

Refer to the Sun Java System Messaging Server Administration Guide (http://docs.sun.com/doc/819-0105).

Portal Server Troubleshooting Tools

Portal Server Secure Remote Access Troubleshooting Tools

Portal gateway debug logs are located in the following directories:

Sun Cluster Software Troubleshooting Tools

Table 13-11  Sun Cluster Software Troubleshooting Tools 

Topic

Details

Log Files

Default log directory: /var/cluster/logs/install

Error messages: /var/adm/messages

Troubleshooting

Refer to the Sun Cluster Software Installation Guide for Solaris OS, at http://docs.sun.com/doc/817-6543.

Sun Remote Services Net Connect Troubleshooting Tools

For information on troubleshooting SunSM Remote Services (SRS) Net Connect, refer to the “Troubleshooting” chapter of the Sun Remote Services Net Connect 3.1.1 Activation Guide, http://docs.sun.com/doc/819-0619.

Additional material on using and troubleshooting SRS Net Connect after an installation can be found at:

Log in to retrieve the following documents:

Web Server Troubleshooting Tools

Table 13-12  Web Server Troubleshooting Tools 

Topic

Details

Log Files

There are two types of Web Server log files: the errors log file and the access log file, both located in the following directories:

  • Solaris: /opt/SUNWwbsvr/https-instance_name/logs
  • Linux: /opt/sun/webserver/https-instance_name/logs

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 One Web Server 6.1 Administrator’s Guide (http://docs.sun.com/doc/819-0130).

Troubleshooting

Refer to the Sun One Web Server 6.1 Installation and Migration Guide (http://docs.sun.com/doc/819-0131).

Configuration File Directory

/opt/SUNWwbsvr/https-instance-name/config

Debug Mode

The following options are available:

  • Log output might be used for diagnostics and debugging. You can set the value of the loglevel attribute of the LOG element in the /server_root/https-instance_name/config/server.xml file to the following values: info, 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 Administrator’s Configuration File Reference (http://docs.sun.com/doc/817-6248).
  • A debug flag might 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 attribute in the /instance_root/https-server_name/config/server.xml file to true. For more information, refer to the Sun ONE Web Server Administrator’s Configuration File Reference (http://docs.sun.com/doc/817-6248).
  • The Sun Java System Studio 5, Standard Edition, plugin enables the debugging of web applications. For more information, refer to the Sun ONE Web Server Programmer's Guide to Web Applications (http://docs.sun.com/doc/817-6251).

Additional Troubleshooting Information

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



Previous      Contents      Index      Next     

Part No: 819-0056-11.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.