This chapter provides suggestions on how to resolve Communications Suite 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 Communications Suite.
This section contains the following subsections:
If a problem occurs during installation or uninstallation, the first place to look for information on what happened is the installation logs. Messages on installation, uninstallation, and install-time configuration are gathered into the source log files. Informational, warning, and error messages are issued after such operations as user choices, package manipulations, and installation or uninstallation steps. Information that is displayed for each message includes date and time, log level, module ID, and the message text.
There are four types of log files that capture information on an installation or uninstallation:
A summary provides a high-level description of what was installed and configured.
A detail version A file contains completion information.
A detail version B file contains more details on the log messages.
A debug file contains information that is relevant when installation fails. Use the debug file when one of the other logs indicates an error.
After an uninstallation, the uninstaller removes itself, the installer, and the Log Viewer. However, source log files are not removed and are stored in the following locations:
Solaris: /var/sadm/install/logs
Linux: /var/opt/sun/install/logs
The following table lists the formats of the source log files.
Table 10–1 Log File Formats
Logged Entity |
Log File Name Format |
---|---|
Installer |
Sun_Java_Communications_Suite_install.Atimestamp |
Sun_Java_Communications_Suite_install.Btimestamp |
|
Sun_Java_Communications_Suite_log.timestamp |
|
Sun_Java_Communications_Suite_Summary_Report_install.timestamp |
|
Uninstaller |
Sun_Java_Communications_Suite_uninstall.Atimestamp |
Sun_Java_Communications_Suite_uninstall.Btimestamp |
|
Sun_Java_Communications_Suite_UnInstall_log.timestamp |
|
Sun_Java_Communications_Suite_Summary_Report_uninstall.timestamp |
The log messages are stored in Unified Logging Format (ULF). If you find this format difficult to read, you can edit the source files with a text editor such as vi, or you can use the Communications Suite Log Viewer to view the log messages.
The Communications Suite Log Viewer provides a graphical display for viewing the installer log messages in the Sun_Java_Communications_Suite_Install_log.timestamp file or the Sun_Java_Communications_Suite_UnInstall_log.timestamp file. There are three ways to filter messages so that the messages displayed are of sufficient importance or interest: by log level, by module ID, and by content.
Log level. There are eight log levels to choose from: SEVERE, ERROR, WARNING, INFO, CONFIG, FINE, FINER, and FINEST. If you select a log level, then only log records having that log level or are greater in severity are displayed. Selecting FINEST is equivalent to selecting all records for display.
Module ID. The module is the part of the installer that is writing the log message. If you select a module ID (JAVAESConfig, JAVAESInstall, or JAVAESUninstall), only messages associated with the module IDs you selected are displayed.
Content. The content filter prompts you for a string, such as “configure,” and then displays only those messages that contain that string.
Some typical filtering examples:
Display only the SEVERE log messages.
Display only the log messages with a log level greater than or equal to ERROR.
Display only the log messages from installation steps.
Display only the log messages from installation that have a log level greater than or equal to ERROR.
Save the result of a filtered scenario into a file.
The following table summarizes the basic functionality of the Log Viewer.
Table 10–2 Log Viewer Functions
Task |
Capability |
---|---|
Open |
Selects a log file for filter and display. |
Save |
Saves the filtered and translated messages into a file designated by the File>Save As option. |
Save As |
Chooses a separate file into which to write filtered and translated messages. Note: This file cannot exist in the directory used by the installer to store source logs. |
|
Prints the filtered and translated file. |
Exit |
Closes any open output file, closes the input file, and closes the Log Viewer page. |
Filter for Log Level |
Chooses a log level for filtering. |
Filter for Module ID |
Chooses none or one of the module IDs in the file you opened. The list is populated when you have chosen a log file for filtering. |
Filter for Content |
Selects messages that contain a user-defined string. |
Choose Language |
Chooses a translation language. Default is English. This list is populated from the translation resource bundles stored by the installer. |
With this functionality, the Log Viewer can provide filtered information to help with your troubleshooting scenario. The messages that meet your filter criteria are displayed in a single log table. A row in the log table can then be selected for detailed display which allows a message to be displayed in a multiple line format.
Because the Log Viewer operates in read-only mode, multiple users can use the Log Viewer at the same time. After installation, the Log Viewer is located here:
Solaris SPARC: /var/sadm/prod/SUNWcomm-entsys5i/Solaris_sparc
Solaris x86: /var/sadm/prod/SUNWcomm-entsys5i/Solaris_x86
Linux: /var/sadm/prod/sun-comm-entsys5i/Linux_x86
Review the summary file, for example, Sun_Java_Communications_Suite_Summary_Report_install.timestamp.
If a problem occurred, determine which component caused the problem. If multiple problems occurred, address the first problem. You will probably need to look at one or both of the detail logs.
Review the detail logs (A and B), for example, Sun_Java_Communications_Suite_install.Atimestamp.
Examine the debug log, for example, Sun_Java_Communications_Suite_Install_log.timestamp.
A number of product components have installation-time interdependencies. Problems that affect one product component can affect other product components. First, you should familiarize yourself with the information in Sun Java Enterprise System 5 Installation Planning Guide.
Review the summary file and log files to see whether related products have failed. These might provide a clue as to what to fix first.
Check that you have specified correct connection information. For example:
Does the information that you provided when configuring Directory Server match the directory information you provided for product components that use Directory Server?
Does the Access Manager information that you provided for Portal Server or Portal Server SRA match the information you provided for Access Manager? See the Sun Java Enterprise System 5 Installation Guide for UNIX for information on Portal Server installation.
In addition to product component interdependencies, some product components depend on the existence of Solaris packages that might not be installed on the host, and their absence could cause installation failures. Read the “Software Requirements” section of the Release Notes for details.
If a problem occurs starting a product component, examine that product component's log files. Locations of many product component log files are listed in Product Component Troubleshooting Tips.
The following host-level issues can cause installation problems.
Updates. Have you applied the recommended updates (patches)?
Disk Space. How is the disk partitioned, and to what partitions do installation directories point? The installation directories /var/sadm and /etc/opt, or the non-default directories that you specify, need sufficient disk space.
Network Ports. During configuration, you supply port numbers for Communications Suite product components. Check the following:
Examine the standard port numbers in the file /etc/services .
Look at the summary log file to compare your settings with the standards. Did you mistype a port number or set one server to the port that is typically used for another?
Use the command netstat -a to view current port use on the system. Did you assign a port number that was already in use?
IP Addresses. During configuration, you specify IP addresses. Check that you entered the correct IP addresses. These are some questions to resolve:
Does this system have multiple network interfaces, each with its own IP address?
In a high availability configuration, did you specify the IP address of the logical host or the IP address of a cluster node?
If you are having problems starting product components, verify that the procedures outlined in Chapter 6, Completing Communications Suite Postinstallation Configuration 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 product component that relies on Directory Server, problems can be caused by one of these problems:
You specified an incorrect user ID and password for Directory Server.
You specified an incorrect LDAP port.
Directory Server is unreachable.
The interactive modes of the installer check for Directory Server connectivity during installation, but silent mode does not. If you perform a silent installation when Directory Server is not available, installation of Access Manager could fail.
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 product components. If you are installing different product components on different hosts, it is important to ensure that you supply matching passwords on each host.
To resolve password problems, you might need to uninstall and then reinstall. If the uninstall fails, refer to Installation Fails Due to Leftover Files During Uninstallation.
If you have installed product components but are having problems and cannot reinstall or uninstall, check the packages installed using the Solaris pkginfo command or the Linux rpm command. Compare the results with the Communications Suite packages listed in Chapter 5, List of Installable Packages, in Sun Java Enterprise System 5 Installation Reference for UNIX. Additional information is in Installation Fails Due to Leftover Files During Uninstallation.
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
Silent Installation Fails: “State File is Incompatible or Corrupted”
Uninstallation can leave behind product components or packages. In such a case, you must manually remove the product components or packages before you reinstall Communications Suite. 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 product component but the installer reports that the product component is already installed, even though you removed it.
Use the following command to determine whether any packages were partially installed.
Solaris OS: pkginfo -p
Linux:
rpm -qa |grep —I ^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 5 Installation Reference for UNIX to discover what product 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 product components and their packages, with full information, including interdependencies. You can use the prodreg tool to safely uninstall product components and remove packages. Once you have removed a product component with the prodreg tool, you can reinstall.
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 product component. Each product component description starts with a <compid\> tag and ends with a </compid\> tag. Delete the entire entry for the product component.
Verify that the following directories do not contain Communications Suite product components or packages:
/opt
/etc/opt
/var/opt
Run the installer again.
As of the Communications Suite 5 release, shared components are listed in the product registry file after installation.
The uninstaller removes product 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 shared components after an uninstallation, these components are not removed from the product registry. Thus, the next Communications Suite 5 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 Communications Suite 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 Communications Suite components are not using the product registry file.
On Linux there is no equivalent of the graphical product registry that exists on Solaris OS. If you manually removed files on Linux, you must manually edit the product registry file to remove those entries.
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 10, 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?
Suggested Fix. Resolve the problem and regenerate the state file.
The most likely reason for this is that your MANPATH environment variable is not set correctly for the components you installed.
Suggested Fix. Update /etc/MANPATH to point to the new man page directory. Refer to Verifying the MANPATH.
This section addresses the following problems you might encounter during uninstallation.
The installation program places the uninstaller on your system at the following location:
Solaris OS: /var/sadm/prod/SUNWcomm-entsys5
Linux: /var/sadm/prod/sun-comm-entsys5
If the uninstaller is not in this directory, one of the following might have occurred:
Communications Suite was never installed on this host.
The uninstaller previously removed all product components and itself from this host.
During uninstallation, if the uninstaller detects that there are no Communications Suite product 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 product 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 Communications Suite packages listed in Chapter 5, List of Installable Packages, in Sun Java Enterprise System 5 Installation Reference for UNIX. 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 Communications Suite product components.
Brief instructions for stopping processes are contained in Chapter 6, Completing Communications Suite Postinstallation Configuration product component documentation.
Back up all custom configuration and user data you plan to use in subsequent installations.
Reviewing Uninstallation Behavior for Communications Suite Product Components provides some information on configuration and user data that should be backed up. For more information, refer to the product component documentation for each product component.
Use the pkgrm, rpm -e, or swremove command to remove Communications Suite component packages.
Remove any remaining product 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:
Solaris OS: /var/sadm/install/productregistry
Linux: /var/opt/sun/install/productregistry
The uninstaller uses this registry to determine which product 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/logs
Linux: /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:
Solaris OS: /var/sadm/install/productregistry
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 (V2.0) included with Communications Suite reserves the following port numbers by default:
JMX port (TCP) = 11162
SNMP Adaptor port (UDP) = 11161
SNMP Adaptor port for traps (UDP) = 11162
Commandstream Adaptor port (TCP) = 11163
RMI connector port (TCP) = 11164
If you are troubleshooting an installation of Sun Cluster, the port assignments are different because Sun Cluster uses a different version of common agent container. In this case, default ports are as follows:
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 used by the common agent container as described in the following procedure.
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 Verifying the MANPATH.
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 11161 to 11165:
For Sun Cluster, use previously-specified ports.
/opt/SUNWcacao/bin/cacaoadm set-param snmp-adaptor-port=11165 |
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 11161 to 11165:
/opt/sun/cacao/bin/cacaoadm set-param snmp-adaptor-port=11165 |
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 Communications Suite. 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/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.
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.
The tables in this section provide various quick tips on troubleshooting product component problems, including references to useful documentation. This section contains the following subsections:
Topic |
Details |
---|---|
Configuration File |
AMConfig.properties
|
Log and Debug Files |
Log file directory:
|
Debug Mode |
Refer to the Auditing Features chapter in the Sun Java System Access Manager 7.1 Developer’s Guide. |
Topic |
Details |
---|---|
Log Files |
Log file directory:
Application Server instance log directory (default location for the initially created instance):
Message log file name: server.log, for each server instance |
Configuration Files |
|
Troubleshooting |
Refer to the Sun Java System Application Server Enterprise Edition 8.2 Troubleshooting Guide. |
Topic |
Details |
---|---|
Log Files |
Administration Service (csadmind): admin.log Distributed Database Service (csdwpd): dwp.logHTTP Service (cshttpd): http.log Notification Service (csnotifyd): notify.logCalendar Backup Service (csstored): store.log Default log directory:
For more information, refer to Sun Java System Calendar Server 6.3 Administration Guide. |
Configuration File |
Solaris: /opt/SUNWics5/cal/config/ics.conf Linux: /opt/sun/calendar/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.3 Administration Guide. |
Troubleshooting |
Refer to Sun Java System Calendar Server 6.3 Administration Guide. |
Topic |
Details |
---|---|
Log Files |
Default log files: uwc-deployed-path/logs/uwc.log |
Instance Directory |
Solaris OS: /var/opt/SUNWuwc Linux: /var/opt/sun/uwc |
Troubleshooting |
Refer to the Chapter 5, Troubleshooting, in Sun Java System Communications Express 6.3 Administration Guide. |
Topic |
Details |
---|---|
Log Files |
Runtime log file: Solaris: /opt/SUNWcomm/log |
Troubleshooting |
Topic |
Details |
---|---|
Log Files |
Installation log file:
|
Troubleshooting |
Topic |
Details |
---|---|
Log Files |
Server log: xmppd.log Agent calendar log: agent-calendar.log WatchDog log: iim_wd.log Multiplexor log: mux.log.log Default log directory:
For more information, refer to Sun Java System Instant Messaging 7.2 Administration Guide |
Configuration File |
Solaris: /opt/SUNWiim/config/iim.conf Linux: /opt/sun/im/config/iim.conf |
Debug Mode |
To use debug mode, an Instant Messaging administrator sets the iim.log.iim_server.severity configuration parameter in the iim.conf file. Example for the server component: iim.log.iim_server.severity = "DEBUG" Example for the multiplexor component: iim.log.iim_mux.severity = "DEBUG" Example for the watchdog component: iim.log.iim_wd.severity = "DEBUG" |
Troubleshooting |
For further specifics and additional information on troubleshooting, refer to Sun Java System Instant Messaging 7.2 Administration Guide. |
Post-Uninstallation Tasks |
Instant Messaging configuration directories and Instant Messages resources deployed in the web container are not removed during uninstallation and should be removed after uninstallation. To completely remove Instant Messaging from a host, unnecessary directories such as the following should be removed: /opt/SUNWiim/, /var/opt/SUNWiim/, and /etc/opt/SUNWiim/. In addition, resources should be undeployed from the web container using the undeploy all command. |
Topic |
Details |
---|---|
Log Files |
Installation log file:
Broker log file:
|
Troubleshooting |
Refer to the Troubleshooting Problems chapter of the Sun Java System Message Queue 3 2005Q4 Administration Guide. For performance problems, refer to “Analyzing and Tuning a Message Service” in the Sun Java System Message Queue 3 2005Q4 Administration Guide. |
Topic |
Details |
---|---|
Executable Location |
Process log files:
Configure log files:
|
Log Files |
|
Troubleshooting |
Refer to the Sun Java System Messaging Server 6.3 Administration Guide. |
Topic |
Details |
---|---|
Configuration Files |
For Monitoring Console:
For Monitoring Framework:
|
Log Files |
For Monitoring Console:
For Monitoring Framework:
|
Troubleshooting |
If you cannot access Monitoring Console, refer to Troubleshooting the Monitoring Console in Sun Java Enterprise System 5 Monitoring Guide. If you cannot see your monitored components in the Monitoring Console, refer to Troubleshooting the Monitoring Framework in Sun Java Enterprise System 5 Monitoring Guide |
Topic |
Details |
---|---|
Log Files |
There are two types of Web Server log files: the errors log file and the access log file. 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 7.0 Administrator’s Guide. These logs are located in the following directories:
If Web Server configuration fails during Configure Now installation, refer to the following logs for additional information:
|
Configuration File Directory |
|
The following information in this guide is also useful for troubleshooting:
Chapter 6, Completing Communications Suite Postinstallation Configuration contains instructions for performing post-installation configuration.
Chapter 9, Uninstalling Communications Suite Product Components contains information on problems that might occur while uninstalling the software.