Sun Java Studio Enterprise 7 Installation Guide

This chapter provides tips for how to troubleshoot problems that you might encounter in the following areas:

• Basic Installation Troubleshooting Techniques
• Java Studio Enterprise Problems and Solutions

---

Basic Installation Troubleshooting Techniques

This section contains some basic trouble shooting suggestions. You can also find troubleshooting tips for some common errors specific to tasks described in several other chapters of this guide. Refer to the Table of Contents or the index.

Examine Installation Log Files

If a problem occurs during installation or uninstallation, check the appropriate log file. Installer and uninstaller log files and reports are found in the following locations:

• (Solaris OS) /var/sadm/install/logs
• (Microsoft Windows), determined by the value of the user environment variable, %TEMP%, such as C:\Documents and Settings\Administrator\Local Settings\Temp.
• A copy of the installation summary report, Summary_Report.timestamp, is also stored in the java-studio-install-dir on all platforms.

The following table lists the formats for the log file names. The A version of the log file records completion of the installer. The B version of the log file contains the log messages. Use the Microsoft Windows utility Notepad to view the log files.

The timestamp variable represents the time the log was created. It has the format MMddhhmm, where

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.

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

2. Review the detailed log files.

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

b. 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:

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

3. Examine component product log files.

If a problem occurs starting a component product, examine its log files. Some component products components write log files to the same directory as the installer's log files, including Administration Server, Application Server, Directory Server, Portal Server, and Access Manager. For more information about component product log files, see the appropriate appendix for your platform.

• (Microsoft Windows) See Appendix C
• (Solaris OS) See Appendix D

Check Resources and Settings

The following host-level issues can cause installation problems.

• (Solaris OS) Updates. Have you applied the recommended updates (patches)?
• Disk space. How is the disk partitioned, and to what partitions do installation directories point?
• (Solaris OS) The installation directories /var/sadm and /etc/opt, or the nondefault directories that you specify, need sufficient disk space.
• (Windows OS) The installation directory C:\Sun\jstudio, or the nondefault directory that you specify needs sufficient disk space.

• DNS Suffix. Be sure the DNS suffix is set properly. See Verifying the DNS Suffix.
• (Microsoft Windows) %TEMP% variable. Be sure that you have defined the user environment variable %TEMP%.

Run Verification Procedures

If you are troubleshooting problems related to starting component products, check that the component processes are running and perform the validation procedures in the following chapters (as seems appropriate to the problem you are debugging):

• Starting the IDE
• Using Sun Java System Application Server Instances in the IDE
• Validating Server Installation for Windows systems
• Validating Server Installation for Solaris OS systems

Check the Distribution Media

If you are installing from a DVD or CD-ROM, is the media dirty? Dirty discs can result in installation problems due to read errors.

Verify Directory Server Connectivity

If you are installing a component that relies on Directory Server, one of the following could cause an issue:

• You specified an incorrect user ID and password for Directory Server.
• You specified an incorrect LDAP port.
• Directory Server has not been started.
• During silent mode installation, Directory Server was not running.

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, Access Manager or Portal Server could fail during installation.

Verify Passwords

During installation you choose a user name and password. The installer uses the name and password to configure the server component products. This user name and password are used for Application Server, Directory Server and Web Server. Access Manager and Portal Server use a different user name and password. To access the Access Manager Admininstrative Console, type the user name amadmin. The password value is the one you used during installation. Review the Summary_Report.timestamp to verify that you are using the correct login information for each server process.

Verifying the DNS Suffix

Installation and configuration of Directory Server, Access Manager, Portal Server and Web Server require a valid domain name. On Microsoft Windows machines, the DNS Suffix property must be set to a valid value.

Use the procedure appropriate to your platform to verify that the DNS Suffix is set correctly on your machine. If you have questions about the correct DNS Suffix or domain name for your machine, contact your network administrator for assistance.

4. Right-click My Computer and select Properties.

The System Properties dialog box is displayed.

5. Select the Computer Name tab.

Review the value of the field Full computer name. If it contains a fully-qualified domain name for your computer, for example machinename.my.company.com, then your settings are complete. If the field is blank or incomplete, then continue to the next step.

6. Click Change (a button near the bottom of the displayed tab).

The Computer Name Changes dialog box is displayed.

7. Click More.

The DNS Suffix and NetBIOS Computer Name dialog box is displayed.

8. Type the correct DNS suffix in the field, Primary DNS suffix of this computer, and verify that the check box, Change primary DNS suffix when domain membership changes, is checked.

9. Reboot your machine and follow steps 1-3 to verify your changes.

1. Right-click the My Computer icon on your desktop.

2. Select Properties from the contextual menu.

3. Select the Network Identification tab and click Properties.

The Identification Changes dialog box displays.

4. Click More.

The DNS Suffix and NetBios Computer Name dialog displays.

5. Type the correct DNS suffix in the field, Primary DNS suffix of this computer, and verify that the check box, Change primary DNS suffix when domain membership changes, is checked.

6. Reboot your machine and follow steps 1-3 to verify your changes.

1. Change to the /etc directory.

2. View the resolv.conf file and verify that it contains the proper domain name entry for your machine and an entry for the DNS name server for your organization or network.

---

Java Studio Enterprise Problems and Solutions

This section describes some common error conditions you might encounter and suggested solutions for resolving the problems.

Installing Java Studio Enterprise Software

1. Nothing happens after double-clicking the Java Studio Enterprise 7 installer.bat file after downloading and unzipping the downloaded file.

Reason. If you are on a Microsoft Windows system, most likely there is spaces or other special characters in the path name to the location of installer.bat. To verify that this is the problem, open a command prompt window, invoke the installer from this windows and you should see a command line error message describing the problem.

Solution. Unzip the downloaded file to a directory that does not contain spaces or special characters anywhere in the path name. See To Install Java Studio Enterprise Software for complete installation steps on Windows systems.

2. Trying to reinstall Java Studio Enterprise after uninstalling the software results in the following message from the installer:

Corrupt Serial Number: Installation Cannot Proceed

<html><body> A serial number that was installed on the machine appears to have been corrupted.

Reason. Certain files were not uninstalled properly during a previous uninstall session. You should not see this message unless you have repeatedly installed and uninstalled the software.

Solution. Be sure to remove the following files if they are not removed by the uninstaller:

• Solaris OS systems - /var/sadm/install/.JavaStudio
• Microsoft Windows systems - remove the Registry Key HKEY_LOCAL_MACHINE > SOFTWARE > Sun Microsystems > JavaStudio

Starting Servers

The Java Studio Enterprise servers have specific dependencies and need to be started in the proper startup sequence. Refer to Chapter 13 for more information on Microsoft Windows systems. Refer to Chapter 14 for more information on Solaris OS systems.

When accessing Directory Server Admin console, sometimes the login dialog displays an incorrect URL and log in attempts fail. Correct the URL and log in again. Use the procedure To Verify Directory Server Connectivity.

Identifying and Fixing an Incomplete Uninstallation

If the uninstaller stops running before all the product files are deleted, some files, directories, and other system entries may not be properly uninstalled. It is also possible for the installation, configuration, or uninstallation of a component product to fail in such a way that subsequent attempts to uninstall or install fail.

You can identify a failed uninstallation in the following ways:

• Examining the directories and files remaining after you uninstall Java Studio Enterprise indicates that not all files were deleted properly. See the uninstallation chapter for your platform for a list of files that are not deleted during uninstallation.
• After uninstalling the product, you are unable to reinstall the same or a newer version even though you are using a different installation directory or you have deleted the old one. This problem might indicate a corrupted product registry.
• You see an error message while uninstalling, the uninstall process fails, or the log contains an indication that the uninstallation failed.

If you have a failed uninstallation you might encounter problems if you try to reinstall the same or different versions of the software or if you try to install a stand-alone version of Java Studio Enterprise component products.

If you used an uninstallation method other than the provided uninstaller wizard, you might be left with an incomplete or corrupted uninstallation. The following sections describe what to do to fix your system if you determine that you have an incomplete uninstallation.

1. Be sure you are logged in as a user with administrator privileges.

2. Locate the Java Studio Enterprise uninstaller executable, uninstall.bat.

It is found in the java-studio-install-dir. The default installation directory is %SystemDrive%\Sun\jstudio_04Q4.If this executable is not present, continue to Step 4.

3. Run the uninstaller and continue to Step 4.

C:\> java-studio-install-dir\uninstall.bat

4. Verify that all servers are stopped.

Stop the servers using the Start Menu or the command line. To verify, use the following steps:

a. Choose Start > Settings > Control Panel.

The Control Panel dialog box is displayed.

b. Double-click on Administrative Tools.

The Administrative Tools dialog is displayed.

c. Double-click on Services.

d. Scroll down the list of Services until you see the entries for Sun ONE servers.

The uninstaller may have removed some of the entries. If you see entries for Sun ONE servers that were installed using this installer, then verify they are stopped.

5. Remove the Java Studio Enterprise entries from the productregistry file located at %SystemRoot%\system32\.

To be safe, backup this file before editing the entries if you have installed other Sun software. The variable, %SystemRoot%, on a Microsoft Windows 2000 system might be C:\WINNT. On a Microsoft Windows XP Professional system this variable might be C:\WINDOWS. See also To Manually Edit Product Registry File.

6. Using the Windows Registry Editor, delete the following folders and their contents from the Windows Registry.

If you have other Sun software products installed, you should just delete the Java Studio Enterprise entries, not the entire folder. You can verify that the entry was installed by Java Studio Enterprise by examining the registry key attribute ImagePath. The value indicates the installation directory, if it's under java-studio-install-dir, then it was installed by the Java Studio Enterprise installer.

The Java Studio Enterprise entries are:

• HKEY_LOCAL_MACHINE\SOFTWARE\Sun\
• Administration\5.2
• Directory\5\slapd-machinename
• Directory\5\SNMP\CurrentVersion

• HKEY_LOCAL_MACHINE\SOFTWARE\Sun Microsystems\
• Application Server\7 2004Q2
• IdentityServer\6.1
• JavaStudio\2004Q4
• PortalServer\6.2
• studio_ee\7
• Sun ONE Message Queue\3.0.1
• WebServer\6.1

7. Using the Windows Registry Editor, delete the Sun ONE server registry keys from the following folder:

• HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application\
• admin52-serv
• c_sun_jstudio_04q4_webserver6_2004q1_https-admserv_config
• c_sun_jstudio_04q4_webserver6_2004q1_https-hostname.domainname_config
• slapd-hostname
• SunAppServer7 2004Q2UR1ER1-domain1_admin-server
• SunAppServer7 2004Q2UR1ER1-domain1_server1
• SunAppServer7 2004Q2UR1ER1-jstudio-domain_admin-server
• SunAppServer7 2004Q2UR1ER1-jstudio-domain_<asserver>

Also remove the following Java Studio Enterprise Services entries:

• HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
• admin52-serv
• https-admserv61
• https-machinename.domainname
• slapd-machinename
• SunAppServer7 2004Q2UR1ER1-domain1_admin-server
• SunAppServer7 2004Q2UR1ER1-domain1_server1
• SunAppServer7 2004Q2UR1ER1-jstudio-domain_admin-server
• SunAppServer7 2004Q2UR1ER1-jstudio-domain_jstudio-server

8. Remove the Start Menu Program Group named Sun Microsystems > Sun Java Studio Enterprise 7 and its contents (Program Items).

9. Remove the product files from the java-studio-install-dir.

If you have trouble deleting some of these directories, check the Task Manager to see if a java.exe process is running. End the java.exe process and try again to delete the java-studio-install-dir and its subdirectories.

10. (Optional) Reboot the system so that the system comes up with a clean registry.

Verify that all Java Studio Enterprise services were removed.

a. Open the Control Panel dialog.

• (Windows 2000 systems) Choose Start > Control Panel > Settings.
• (Windows XP systems) Choose Start > Control Panel.

b. Double-click Administrative Tools.

The Administrative Tools dialog is displayed.

c. Double-click Services.

The Services dialog is displayed.

d. Scroll down in the list of services to find the Sun Java Studio Enterprise 7 entries.

If you have uninstalled the entire Java Studio Enterprise product, then you should not see any related entries.

Be sure that you have tried running the uninstaller provided with Java Studio Enterprise before using these steps. Normally, the uninstaller completes the uninstallation of the products that you select.

1. Enable client access to the X server.

% xhost + your-local-machine

2. Set the DISPLAY environment variable to display to your local system.

For example, if you use the C shell, type:

% setenv DISPLAY your-local-machine:0.0

3. Become a superuser.

4. Verify that all Java Studio Enterprise servers are stopped.

a. If the stopservers script is still available, run the script. For example:

# /opt/SUNWjstudio/bin/stopservers.sh

If the stopservers script is not available, you may need to locate the process id for each server and stop it separately. For example:

% ps -ef | grep appservd

If the server is running, kill the process. Repeat for each server process. Refer to Appendix D for the Solaris process name corresponding to the servers that you have installed.

5. Verify that all Java Studio Enterprise component product packages were removed.

# pkginfo | egrep -i "Sun ONE|Sun Java"

If you still see packages, see To Manually Remove Packages.

6. Verify that the uninstaller package was removed.

# pkginfo | grep -i "SUNWjstudio"

7. Edit /var/sadm/install/productregistry to remove Java Studio Enterprise entries.

Backup the file before doing manual edits. See also To Manually Edit Product Registry File.

8. Remove (if found) /var/sadm/install/.JavaStudio.

9. Remove /var/opt/SUNWappserver7 and /etc/opt/SUNWappserver7 (if you installed Application Server).

10. Remove /var/opt/SUNWam and /etc/opt/SUNWam (if you installed Access Manager).

11. Remove /var/opt/SUNWps and /etc/opt/SUNWps (if you installed Portal Server).

12. Remove java-studio-install-dir/SUNWwbsvr (if you installed Web Server).

13. Remove the remaining files in the java-studio-install-dir.

# rm -r java-studio-install-dir

14. Disable client access to the X server and exit from superuser privileges.

# xhost - your-local-machine

# exit

Removing Java Studio Enterprise Packages Manually

TABLE 15-2 lists the packages installed during Java Studio Enterprise installation. Use this list as a reference to be sure you removed all of the packages. It is recommended that you only remove these packages manually if the uninstaller wizard failed to remove them.

Java Studio Enterprise component products are listed in the table for reference only and the Sun ONE names are used for correspondence to the software packages.

1. (Directory Server) If you need to manually remove the packages for Directory Server, follow these steps first:

a. Start the Directory Server instance. For example:

# cd /opt/SUNWdirserver/slapd-instance-name

# ./start-slapd

b. Unconfigure Directory Server.

# /usr/sbin/directoryserver unconfigure

c. Unconfigure Directory Server Administration Console.

# /usr/sbin/mpsadmserver unconfigure

2. Remove any Java Studio Enterprise component product packages that have not been removed using the pkgrm command.

Do this carefully and in the order described in TABLE 15-2. Failure to remove the packages in this order may result in unexpected problems due to package dependencies. If you are uncertain how to do this, contact your system administrator.

Java Studio Enterprise keeps a metadata record of all the packages and zip units that are installed. This information is stored in a file called productregistry. This productregistry file follows XML markup standards and is platform independent. The location of this file is as follows:

• (Solaris OS) - /var/sadm/install
• (Microsoft Windows 2000) - %SystemDrive%/WINNT/system32
• (Microsft Windows XP Professional) - %SystemDrive%/WINDOWS/system32

A typical product registry might look like this:

<productregistry>

  <version>0.6</version>

    <components>

      <compid>Looking Glass                                              <compversion>1.0                                                      <uniquename>Project Looking Glass</uniquename>                                                        <compinstance>                                                                <parent>Java Desktop System                                                                      <instance>1                                                                           <version>1.0</version>                                                                      </instance>                                                                </parent>                                                                 <children>                                                                       <compref>Java 3D API                                                                       <instance>1                                                                             <version>1.0</version>                                                                         </instance>                                                                         </compref>                                                                  </children>

                <comptype>FEATURE</comptype>                                                                  <location>/opt/lookingglass</location>                                                                    <dependent>                                                                            <compref>Java Desktop System                                                                                   <instance>1                                                                                           <version>1.0</version>                                                                                     </instance>                                                                             </compref>                                                                  </dependent>                                                                  <required>                                                                            <compref>Java 3D API                                                                                   <instance>1                                                                                    <version>1.0</version>                                                                                    </instance>                                                                              </compref>                                                          </compinstance>                                                 </compversion>

         </compid>

       </components>

</prodregistry>

As shown in the example each product is identified by a compid tag. Associated with a compid, there can be single or multiple versions and associated with a version there can be single or multiple instances. For each instance, there is a comptype tag, which can be a component, feature or product. Associated with a compinstance there can be single or multiple entries for required components or children components.

Manual editing of the product registry file is NOT a recommended approach, but if it is necessary to recover from a corrupted installation or a failed uninstallation, it may be edited as follows:

1. Make a backup copy of the productregisty file for safekeeping.

2. Remove the entire entry for the particular compid.

Remove from the <compid> tag to the corresponding </compid> tag. Do this carefully.

3. Remove all the required/children packages for that entry.

Sometimes one compid can have multiple versions of the same product. Care must be taken to remove entries for the correct version.

Depending on the component products installed, you may see one or more of the compid entries listed in TABLE 15-3.

The following table lists the Sun Java Studio Enterprise 7 product registry compids for Solaris OS machines.

Sun Java Studio Enterprise 7 Installation Guide

817-7971-10

Copyright © 2004, Sun Microsystems, Inc. All Rights Reserved.