This chapter provides suggestions on how to resolve Sun JavaTM Enterprise System (Java ES) installation and uninstallation problems.
This chapter includes the following sections:
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:
If a problem occurs during installation or uninstallation, check the appropriate log file in the logs directory:
Solaris OS: /var/sadm/install/logsLinux: /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:
An A version of the log file records completion.
A B version of the log file contains more detailed log messages.
The following table lists the formats of the log files.
Table 9–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 |
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 JavaES_Config_log.timestamp JavaES_PanelFlow_log.timestamp JavaES_MasterLog_log.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.
The log files can give you clues that determine your next steps, such as these:
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.
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.
If a problem occurs starting a component, examine its log files. Locations of many component log files are listed in Component Troubleshooting Tips.
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 Sun Java Enterprise System 2005Q4 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 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?
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.
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 Java ES 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?
If you are having problems starting components, verify that the procedures outlined in Chapter 6, Configuring Components After Installation were done correctly.
If you are installing from a DVD or CD, examine the media for dirt or damage. Dirty discs can result in installation problems.
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. If you perform a silent installation when Directory Server is not available, installation of Access Manager or Portal Server could fail.
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.
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.
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 Chapter 5, List of Installable Packages, in Sun Java Enterprise System 2005Q4 Installation Reference uninstalled. Additional information is in Installation Fails Due to Leftover Files During Uninstallation.
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.
During uninstallation, you might need to grant administrator access to the uninstaller, as described in Granting Administrator Access for the Uninstaller.
This section addresses the following problems you might encounter during installation.
Installation Fails Due to Leftover Files During Uninstallation
Installation Fails Due to Removed Shared Components in Product Registry After Uninstallation
Cannot Configure IBM WebSphere as the Portal Server Web Container
Silent Installation Fails: “State File is Incompatible or Corrupted”
Uninstallation 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:
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, even though you removed it.
Use the following command to determine whether any packages were partially installed.
For Solaris OS:
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 Chapter 5, List of Installable Packages, in Sun Java Enterprise System 2005Q4 Installation Reference to discover what component the packages belong to.
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.
Clean the /opt, /etc/opt and /var/opt directories.
Run the installer again.
As of the Java ES 2005Q4 release, shared components are listed in the product registry file after installation.
The Java ES uninstaller removes selectable 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 Java ES shared components after an uninstallation, these components are not removed from the product registry. Thus, the next Java ES 2005Q4 installation fails because the installer assumes that the manually deleted shared components are present (because they still have entries in the product registry file).
Avoid manually removing Java ES 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 Java ES components are not using the product registry file.
On Linux: There is no equivalent of the graphical product registry file on Linux, so if you removed such rpm files by mistake, you must manually edit the product registry file.
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.
One approach is to check the configuration of your WebSphere instance.
Ensure that WebSphere is running.
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)
Use the WebSphere tools to check the configuration to make sure it matches the values you are entering.
Try again.
Another approach is to create new instances of the WebSphere entities.
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.
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
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.
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.
If you created the state file on the same platform on which you are running the silent installation, generate a new state file and reinstall.
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. For example, if you created the state file on Solaris 9, you cannot use it on Solaris 8, or, if you created the state file on the x86 platform, you cannot use it on the SPARC platform.
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.
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.
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?
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.
This section addresses the following problems you might encounter during uninstallation.
The Java ES installation program places the uninstaller on your system at the following location:
Solaris OS: /var/sadm/prod/SUNWentsys4
Linux: /var/sadm/prod/sun-entsys4
If the uninstaller is not in this directory, one of the following might have occurred:
Java ES was never installed on this host.
The Java ES uninstaller previously removed all components and itself from this host.
During uninstallation, if the uninstaller detects that there are no Java ES components on a host, it uninstalls itself.
During a failed installation, one of the following occurred:
The uninstaller was never installed on the host.
The uninstaller was removed, but some Java ES components remain on the host.
Suggested Fix. Manually clean up your system as described in 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.
Determine which packages you want to remove.
Compare the packages on your system with the Java ES packages listed in Chapter 5, List of Installable Packages, in Sun Java Enterprise System 2005Q4 Installation Reference. 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
Stop all running processes for Java ES components.
Brief instructions for stopping processes are contained in Chapter 6, Configuring Components After Installation component documentation.
Back up all custom configuration and user data you plan to use in subsequent installations.
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.
Use the pkgrm or rpm -e command to remove Java ES component packages.
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.
Update the product registry file, which is located here:
On Solaris OS: /var/sadm/install/productregistryOn 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.
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.
Clean up the log files for your system, which are located here:
Solaris OS: /var/sadm/install/logsLinux: /var/opt/sun/install/logs
The log files might not correctly reflect the state of your system after you manually remove packages.
During uninstallation, the uninstaller uses the product registry file to determine what needs to be uninstalled:
On Solaris OS: /var/sadm/install/productregistryOn Linux: /var/opt/sun/install/productregistry
If the uninstaller fails, you might need to retry after you restore the product registry from your backup copy.
If you manually remove packages, the product registry is not automatically updated. When you subsequently run the uninstaller, you might encounter problems because the product registry does not correctly reflect your system. In this case, you can try to reinstall and then run the uninstaller again.
This section addresses the following problems that might arise in relation to the common agent container shared component:
The common agent container inside Java ES occupies the following port numbers by default:
JMX port (TCP) = 10162
SNMP Adaptor port (UDP) = 10161
SNMP Adaptor port for traps (UDP) = 10162
Commandstream Adaptor port (TCP) = 10163
RMI connector port (TCP) = 10164
If your installation already reserves any of these port numbers, change the port numbers occupied by the common agent container as follows.
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.
As root, stop the common agent container management daemon:
# /opt/SUNWcacao/bin/cacaoadm stop |
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 10161 to 10165:
# /opt/SUNWcacao/bin/cacaoadm set-param snmp-adaptor-port=10165 |
Restart the common agent container management daemon:
# /opt/SUNWcacao/bin/cacaoadm start |
As root, stop the common agent container management daemon:
# /opt/sun/cacao/bin/cacaoadm stop |
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 10161 to 10165:
# /opt/sun/cacao/bin/cacaoadm set-param snmp-adaptor-port=10165 |
Restart the common agent container management daemon:
# /opt/sun/cacao/bin/cacaoadm start |
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 OS: /etc/opt/SUNWcacao/securityLinux: /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.
As root, stop the common agent container management daemon.
# /opt/SUNWcacao/bin/cacaoadm stop |
Regenerate the security keys.
# /opt/SUNWcacao/bin/cacaoadm create-keys --force |
Restart the common agent container management daemon.
# /opt/SUNWcacao/bin/cacaoadm start |
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.
As root, stop the common agent container management daemon.
# /opt/sun/cacao/bin/cacaoadm stop |
Regenerate the security keys.
# /opt/sun/cacao/bin/cacaoadm create-keys --force |
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.
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 OS, 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.
This section provides various quick tips on components, with references to useful documentation.
This section contains the following subsections:
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:
|
Debug Mode |
Refer to the Auditing Features chapter in the Sun Java System Access Manager 7 2005Q4 Developer’s Guide. |
Topic |
Details |
---|---|
Log Files |
|
Troubleshooting |
Refer to the . |
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 |
Configuration file directory: /var |
Troubleshooting |
Refer to the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Troubleshooting Guide. |
Topic |
Details |
---|---|
Log Files |
Administration Service (csadmind): admin.logDistributed Database Service (csdwpd): dwp.logHTTP Service (cshttpd): http.log Notification Service (csnotifyd): notify.logCalendar Backup Service (csstored): store.log Default log directory: /var/opt/SUNWics5/logs For more information, refer to Sun Java System Calendar Server 6 2005Q4 Administration Guide. |
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 6 2005Q4 Administration Guide. |
Troubleshooting |
Refer to Sun Java System Calendar Server 6 2005Q4 Administration Guide. |
Topic |
Details |
---|---|
Log Files |
Default log files: uwc-deployed-path/logs/uwc.log |
Troubleshooting |
Refer to the Chapter 6, Troubleshooting, in Sun Java System Communications Express 6 2005Q4 Administration Guide. |
Topic |
Details |
---|---|
Log Files |
Runtime log file: /opt/SUNWcomm/log |
Troubleshooting |
Topic |
Details |
---|---|
Log Files |
Default log file: DirectoryProxyServer-base/dps -hostname/logs/fwd.log For more information, refer to the Sun Java System Directory Proxy Server 5 2005Q1 Administration Guide. |
Troubleshooting |
Refer to the Sun Java System Directory Proxy Server 5 2005Q1 Administration Guide. |
Topic |
Details |
---|---|
Log Files |
Installation log file: Solaris OS: /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 5 2005Q1 Administration Guide. |
Troubleshooting |
Refer to the Sun Java System Directory Server 5 2005Q1 Administration Guide. |
For information on troubleshooting Instant Messaging, refer to the client online help and the Sun Java System Instant Messaging 7 2005Q1 Administration Guide.
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. |
Performance |
Refer to “Analyzing and Tuning a Message Service” Sun Java System Message Queue 3 2005Q4 Administration Guide. |
Topic |
Details |
---|---|
Executable Location |
/opt/SUNWmsgsr/sbin |
Log Files |
MessagingServer-base/data/log |
Troubleshooting |
Refer to the Sun Java System Messaging Server 6 2005Q4 Administration Guide. |
Portal Server uses the same log files and debug files as Access Manager.
Table 9–12 Portal Server Troubleshooting Tips
Topic |
Details |
---|---|
Debug Files |
Solaris OS: /var/opt/SUNWam/debug Linux: /var/opt/sun/identity/debug |
Log Files |
Solaris OS: /var/opt/SUNWam/logs Linux: /var/opt/sun/identity/logs |
Troubleshooting |
Refer to the Sun Java System Portal Server 6 2005Q4 Administration Guide. |
Portal Server uses the same log files and debug files as Access Manager.
desktop.debug
desktop.dpadmin.debug
The dpadmin, par, rdmgr , and sendrdm Portal Server command line utilities have options to generate debugging messages. They are described in the Portal Server Administration Guide.
Portal gateway debug logs are located in the following directories:
Solaris OS: /var/opt/SUNWps/debug
Linux: /var/opt/sun/portal/debug
Logs for Portal Server services (such as NetFile) are in /var/opt/SUNWam/debug when logging is turned on from Access Manager Administration Console.
Topic |
Details |
---|---|
Log Files |
Application Server instance log: Solaris OS: /var/opt/SUNWsoar/domains/registry/logs/server.log Linux: /var/opt/sun/SUNWsoar/domains/registry/logs/server.log |
Troubleshooting |
Refer to the Service Registry 3 2005Q4 Administration GuideService Registry 3 2005Q4 Administration Guide. |
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. |
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:
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 6.1 SP4 Administrator’s Guide. |
Troubleshooting |
Refer to the Sun Java System Web Server 6.1 SP4 Installation and Migration Guide. |
Configuration File Directory |
/opt/SUNWwbsvr/https-instance-name /config |
Debug Mode |
The following options are available:
|
Topic |
Details |
---|---|
Log Files |
Default log location: /opt/SUNWproxy/proxy-instancename/logs For more information, refer to the Sun Java System Web Proxy Server 4.0.2 Administration Guide. |
Configuration File Directory |
/opt/SUNWproxy/proxy-instancename /config |
Debug Mode |
You can set the value of the loglevel attribute of the LOG element in the /server-root/proxy-instance-name /config/server.xml file: info, fine, finer, finest. |
The following information in this guide is also useful for troubleshooting:
Chapter 6, Configuring Components After Installation contains instructions for performing post-installation configuration.
Chapter 8, Uninstalling Components contains information on problems that might occur while uninstalling the Java ES software.