The IBM® Support Assistant Lite tool is provided as an aid for troubleshooting problems with 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 tracing levels set, as well as by reducing the effort required to send the appropriate log information into IBM Support. In this help guide, we tell you how to get up and running with the IBM Support Assistant Lite tool.
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.
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. This will create a subdirectory \ISALite in this target directory.
Regardless of whether you will be using the IBM Support Assistant Lite tool in 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. If Java is not available on the PATH, you will have to set the JAVA_HOME environment variable manually. The IBM Support Assistant Lite tool requires a JRE at the level 1.4.2 or higher (1.5 or higher on Windows 7 64 bit), so 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. The Microsoft JVM/JDK and gij (GNU libgcj) are not supported. 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 is at a level lower that 1.4.2. In this case you should set the JAVA_HOME variable manually to point to a JRE of the proper level.
You will need to issue the following launch script:
If a GUI is not available, the tool should start in command line mode automatically. If console mode is desired even if a GUI is available, specify "-console" on the command line. In some instances, it will not be possible to determine that a GUI is not available and the tool will not start. In these instances, the tool will need to be restarted using "-console".
By default, the ISA Lite installation directory is used for storing files created during execution. On some systems, the ISA Lite installation directory will be read only. In this instance, use the -useHome parameter. This parameter will cause temporary files to be written to the systems temporary directory and persistent files written to the user home directory.
Once the IBM Support Assistant Lite tool has been started in GUI mode, the graphical interface shown below will be displayed.
Before the tool can be used to perform data collection and analysis, you must first select a problem type in the Problem Type window as demonstrated below.
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: <pmrnumber>.<branchnumber>.<countrycode>.<short description>.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. A script may also ask you for 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, you can send the results to IBM Support. You can choose between FTP, which is unencrypted and HTTPS, which is encrypted, for the file transfer. The name of the zip file the tool sends to IBM Support will be the filename entered in the Output Filename/Path box, with the server hostname and current timestamp appended to it.
Example: if the Output Filename/Path filename used was 34143.055.000.logs.zip, the name of the zip file sent to IBM would be
34143.055.000.logs.zip-<hostname>-<currentTimestamp>.zip.
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 does not 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 is not 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.
When IBM Support Assistant Lite runs in command-line console mode, there are no selection lists or entry fields for user input. Instead, available choices are presented as numbered lists and you enter the number of your selection followed by the Enter key. Input fields are transformed into prompts, at which you enter your response and press Enter.
To stop the collector tool, type quit in console mode.
The tool will prompt for file names. On Unix platforms, using "~" as a designation of the user's HOME directory is not supported. If a "~" is used, a subdirectory under the present working directory by the name of "~" will be referenced.
The console mode also provides you with a silent collection feature 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 tool 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 tool in command-line console mode with the -record option, followed by the name of the response file, For example, in a Linux environment, you would run:
./runISALite.sh -console -record 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:
./runISALite.sh -console 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.
Starting with ISA Lite V1.3.4, the response file format has changed to be more human readable/editable. The file looks very much like a Java properties file, with comments that start with '#', and a series of key-value pairs.
There is now a way to add pauses to these new response files (using your favorite editor). The following is a brief summary of the two new keys supported:
Notes
By default, the version of the tool (and its various sub-components) is printed to the console from which it was launched. When running in GUI mode, version information can also be found using the Help->About menu option. If Java is not available, or the Java application is unable to start, you can also get the version of the tool by running the launch scripts with the "-version" option.
When using the "-version" option, the launch scripts will print out the version information without actually invoking the tool.
IBM, the IBM logo and AIX are trademarks or registered trademarks of International Business Machines Corportation in the United States or other countries or both:
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.