IBM Support Assistant Lite Tool for WebSphere Process Server Quick Start Guide Version 1 Release 3.0 Introduction The IBM Support Assistant Lite for WebSphere Process Server tool is provided as an aid for troubleshooting IBM WebSphere Process Server and other IBM software products. The tool focuses on automatic collection of problem data; it also provides symptom analysis support for the various categories of problems encountered by IBM software products. Information pertinent to a type of problem is collected and analyzed to help identify the origin of the problem under investigation. The tool assists customers by reducing the amount of time it takes to reproduce a problem with the proper RAS tracing levels set (trace levels are set automatically by the tool), as well as by reducing the effort required to send the appropriate log information into IBM Support. In addition, the tool performs symptom analysis to help streamline the problem determination process. In this quick start guide, we tell you how to get up and running with the IBM Support Assistant Lite for WebSphere Process Server tool. Step-by-Step In most cases, the following sequence of steps will get you up and running with the tool. If you run into problems, or if you would like more information on any of these steps, you can refer to the sections below that follow this one. 1. Install the tool by extracting the files from the archive file that you downloaded. * Extract the tool to any directory you choose. * See the sections below for details of how to perform the extractions. 2. Run the tool in either the Swing GUI mode or the command-line console mode. * Follow the procedure described below for setting the JAVA_HOME environment variable. Once you have done this, you can then execute the launch script. * Once you have started the tool, follow the instructions below for interacting with it as it performs a collection. Tool Installation In all cases, installation of the IBM Support Assistant Lite tool is simply a matter of extracting the files from the archive that you downloaded. The files can be extracted to any file system location you choose on the system where you will be running the tool. Extraction on Windows Once you have downloaded the ISALiteForWPS_Win.zip archive, you can use any zip utility to unzip it to your chosen target directory. The operation will create a subdirectory \ISALite in this target directory. Extraction on Linux, AIX, HP-UX, and Solaris Once you have chosen the target directory where you want to install the tool, you can use the following procedure to install it. 1. Download the ISALiteForWAS_Unix.tar.gz file to the target directory you chose. 2. Navigate to this directory and issue the command gzip -d ISALiteForWPS_Unix.tar.gz to extract the .tar file from the .gz archive. 3. Then issue the command tar -xvf ISALiteForWPS_Unix.tar. This will create a subdirectory / ISALite under your target directory. Tool Usage Setting the JAVA_HOME Environment Variable Regardless of whether you will be using the IBM Support Assistant Lite tool in Swing GUI mode or in command-line console mode, you use the same procedure to start it: you invoke the appropriate launch script from a command line. In the case of a Windows system, these launch scripts are batch files. For the other environments, they are shell scripts. Since the tool is implemented as a Java application, it is necessary to set the JAVA_HOME environment variable before the tool can start. You have two options for setting the JAVA_HOME variable manually. 1. You can invoke the WebSphere Application Server setupCmdLine script, and let it set the JAVA_HOME variable. On a Windows system, this script is available in the directory location %WAS_HOME%\bin\setupCmdLine.bat. You invoke it by typing "setupCmdLine" or "setupCmdLine.bat" from this directory. On Linux, AIX, HP-UX, and Solaris systems, it is available in the directory location $WAS_HOME/bin/setupCmdLine.sh. You invoke it by typing ". ./setupCmdLine.sh" from this directory. 2. You can set the JAVA_HOME variable explicitly. Since the IBM Support Assistant Lite tool requires a JRE at the level 1.4.2 or higher, you must first make sure that a suitable JRE is installed on the system where the tool will be running. If it is, then you will need to issue an operating-system-specific command to set the JAVA_HOME variable to point to this JRE. For example, if you have jdk1.4.2 installed at c:\jre1.4.2 on a Windows platform, you would set JAVA_HOME using the following command: SET JAVA_HOME=c:\jre1.4.2 On a Linux, AIX, HP-UX, or Solaris platform, the exact command syntax to set JAVA_HOME varies depending on which shell you are using. For example, if you are using bash shell and you have the JDK installed in /opt/jre142, you would set JAVA_HOME using the following command: export JAVA_HOME=/opt/jre142 After installing the tool into one of the default locations, you may find that it fails to start with the error message "ERROR: This tool requires JRE 1.4.2 or greater to run." This message indicates that the JRE included with WebSphere Process Server, which the tool automatically uses when it has been installed into one of the default locations, is at a level lower that 1.4.2. In this case you should install the tool into a different location and then follow the instructions in this section to set the JAVA_HOME variable manually to point to a JRE of the proper level. Starting the Tool in Swing GUI Mode Once you have insured that the JAVA_HOME variable will point to a JVM at the correct level, all that remains is to issue the correct launch script. For the Swing GUI mode, this script will be the following: * For the Windows environment, it will be the runISALite.bat script in the tool's \ISALite directory. * For the Linux, AIX, HP-UX, and Solaris environments, it will be the runISALite.sh script in the tool's /ISALite directory. Starting the Tool in Command-Line Console Mode Once you have insured that the JAVA_HOME variable will point to a JVM at the correct level, all that remains is to issue the correct launch script. For the command-line console mode, this script will be the following: * For the Windows environment, it will be the runISALiteConsole.bat script in the tool's \ISALite directory. * For the Linux, AIX, HP-UX, and Solaris environments, it will be the runISALiteConsole.sh script in the tool's /ISALite directory. Interacting with the Tool in Swing GUI Mode Before the tool can be used to perform data collection and analysis, you must first select a problem type in the Problem Type window. Next, you need to highlight the problem type you want to run. Other than Problem Type, the only input field value that you must supply on the main GUI is a filename for the data collection zip file. At this point, the filename can be anything you want: you might, for example, use the filename Install_failed_2007_01_03. If you do not supply it, the tool will automatically append the "zip" extension to it. If you have a PMR open for the problem you're performing the collection for, however, and if you'll be letting the tool FTP the collection results in to IBM Support automatically, then at the FTP step the tool will enforce a specific file-naming convention required by IBM Support: the file name must begin with three specific fields: ....zip. An example of a filename of this type would be 34143.055.000.logs.zip. For compatibility with a previous format, commas are also accepted in place of the first three periods (but not in place of the fourth one prior to the "zip" extension). However, periods are the preferred delimiter. With these values filled in the next step is to press the Collect Data button. As it proceeds, the collection script will ask you for any additional information it needs to complete its collection activities. Most WebSphere Process Server scripts ask for the WebSphere Process Server root directory. A script may also ask you for additional configuration information, for information about the sequence of events leading up to the problem you are dealing with, or for your preferences regarding how it should complete the collection. Once it has all the information it needs, the script will proceed with the remainder of the collection. When the tool completes the data collection and analysis operations, you can FTP the results to IBM Support. The name of the zip file the tool sends to IBM Support via FTP will be the filename entered in the Output Filename/Path box, with the server hostname and current timestamp appended to it. Collection details for each WebSphere Process Server problem type can be found in their corresponding MustGather documents: Problem type MustGather General http://www.ibm.com/support/docview.wss?rs=2307&context=SSQH9M&dc=DB520&dc=D600&dc=DB530&dc=D700&dc=DB500&dc=DB540&dc=DB510&dc=DB550&q1=Mustgather&uid=swg21239895 Selective Trace http://www.ibm.com/support/docview.wss?uid=swg21268429 Validation of the Collection Zip File Name The automation at the IBM Support FTP site ftp.emea.ibm.com is entirely dependent on the file-naming convention described on the IBM Support Assistant Lite tool's main GUI. If it receives a file with a name that doesn't follow this convention, then that file is never seen by IBM Support. Consequently, before the tool invokes an FTP operation to send a collection zip file to ftp.emea.ibm.com, it validates the collection zip file's name against the convention. If the file name isn't in the correct form, you will be presented with a pop-up window so that you can correct the file name. The current file naming convention for the FTP site is the one documented here, where the individual fields in the composite file name are separated by periods. Previously, however, the convention was to use commas as the separators. Since the FTP site still handles files named according to the previous convention, the IBM Support Assistant Lite tool's validation logic accepts both periods and commas as delimiters. Interacting with the Tool in Command-Line Console Mode The console mode provides you with command-line control of the IBM Support Assistant Lite tool's collection scripts. The tool includes several features to assist you when you interact with it in console mode, including one that lets you record your responses from a console-mode session in a file and then use the file to drive subsequent executions of the same collection script. To achieve this, you first create a "response file" that contains the answers to all the questions for a certain run through the data collector. The next time the same data collection needs to be executed, you simply provide the response file when starting the portable collector and the answers that were previously provided will be used to answer all the questions. Response files can be tweaked and modified to vary the answers to perform different data collections too. To create a response file, you simply invoke the portable collector with the -record option, followed by the name of the response file, For example, in a Linux environment, you would run: ./startcollector.sh -record wps61-response.txt When running in this mode, you will be taken to an ordinary interactive session, where you supply the responses to the script's prompts. In addition to influencing the current collection, however, your responses are also saved in the file that you named. Once the interactive session has completed, you can use this response file to execute the same script in the future without the need for explicit user input. For example, to run the tool in silent mode in a UNIX environment using the response file that you recorded, run: ./startcollector.sh wps61-response.txt The response file is a plain text file, so you can edit it to change the user's responses as needed. For example, if you want to run the tool on a different system than the one on which the response file was recorded, you might need to adjust some of the values in the response file. When using response files, remember that sensitive information, such as user names and passwords, might be stored in these files, so it is important that you manage these files in a manner that prevents unauthorized access to sensitive information. Also, not all data collections are suitable for the silent collection option. Some data collections always require some interaction with the user. For example, you might be asked to reproduce the problem during the data collection so the appropriate log and trace files are collected. In this case, silent collection is not capable to record and reproduce this step. Trademarks The following terms are trademarks of the IBM Corporation in the United States or other countries or both: AIX IBM The IBM logo WebSphere Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. HP-UX is a registered trademark of Hewlett-Packard Company. Other company, product, or service names may be trademarks or service marks of others.