Release Notes for IBM Support Assistant 5.0 Beta 3

#IBM Support Assistant 5.0 Beta 3 - Release Notes

--------------------------------------------

Release Notes contents:

* Configuration Options
* Installing IBM Support Assistant
* Getting Started
* Starting and Stopping the Server
* Installing Tools
* System requirements
* Known issues
* Contacting IBM

--------------------------------------------

##Configuration Options

###Case files
By default the IBM Support Assistant application will look under the
directory <Install_dir>/ISA5/isa as the location for "case files". To
change the location for these files, modify the 'filestore.root' property in
the file ISA5/isa.properties.

**Example:**
filestore.root=/projects/ isa
After changing the value of filestore.root property, make sure that the
directory it point to is writable and contains:
sub-directory 'cases'
sub-directory 'log' containing sub directory 'tools'
**Example of complete directory structure**
/projects
/ isa
/cases
/log
/tools

###JVM Max Heapsize
By default, the Web based Memory Analyzer is configured with a limited
maximum heap size. This may not be sufficient for analysis of very large
heapdumps. If the IBM Support Assistant Team Server host is a 64-bit machine
and has adequate real memory, then the Web based Memory Analyzer can be run
with a maximum heapsize larger than the default.

To modify the maximum Java heapsize configuration for Web based Memory
Analyzer, edit the '<Install_dir>/ToolBox/bin/start_mat' script. Find the
'MAT_MAXHEAP' variable, and change the value of this variable as desired. A
useful estimate is to allow 1.2 times the size of the subject heapdump for
Web based Memory Analyzer maximum heapsize.

###Port configuration
The default port used for the IBM Support Assistant application is **10911**
and users will automatically be redirected to a secure port at **10943**.
These ports may be changed by modifying the value of the ISA_PORT and
ISA_SSL_PORT variables in the 'start_isa' script. Ensure that the new ports
selected are not currently in use. The application will not start if the
ports are already in use.

The Memory Analyzer tool runs on a different server and uses a default port
of **10912**. The port for the Memory Analyzer server may be changed by
modifying the MAT_PORT variable value in the
'<Install_dir>/ToolBox/bin/start_mat' script. Ensure that the new port
selected is not currently in use. The application will not start, if the
port selected is already in use.

You may need to modify your firewall configuration to allow access to the
ports used by IBM Support Assistant and any tools that run on the server(s).

###X11 DISPLAY
On Linux, IBM Support Assistant makes use of X11 to generate images included
in problem determination analysis output. If the DISPLAY environment
variable is not valid, then some analysis output may indicate:

Xlib: connection to ":0.0" refused by server

**TIP** In a ' headless' configuration, an X11 virtual frame buffer can be
used. The relevant Red Hat RPM is:

xorg-x11-server- Xvfb-1.1.1-48.76.el5_6.4

With this RPM installed,a virtual frame buffer accessible by way of
"DISPLAY=:1" can be set up with the command:

/ usr/bin/ Xvfb :1 -screen 0 1024x768x16 &

If DISPLAY is not set, ISA will try "DISPLAY=:1" as a default.


--------------------------------------------

##Installing

###Team Server or Desktop application
IBM Support Assistant 5.0 Beta 3 is now installed with IBM Installation
Manager 1.5.2 or later.

Detailed instructions for installing with IBM Installation Manager are
available here: http://www.ibm.com/support/docview.wss?uid=swg27036160

###EAR deployment
Using the WebSphere Application Server admin console, you can install the
IBM Support Assistant JEE application in an existing WebSphere Application
Server just as you would install other enterprise applications. The 'fast
path' install via the admin console can typically be used. You will also
need to separately install individual tool WAR files for some analysis
tools.

The IBM Support Assistant EAR file and tool WAR files are obtained using IBM
Installation Manager. The required EAR file is an optional in the IBM
Installation Manager when installing IBM Support Assistant. There is not a
separate installation package for the EAR deployment option and you will
need to follow standard enterprise application deployment steps. Please
refer to your WebSphere Application Server instructions for documentation
on how to deploy EAR files.

The WAR files for tools are available in the
<ISA_install>/ wlp/ usr/servers/ isa/ dropins folder on the file system. These
WAR files can be deployed to an existing WebSphere Application Server using
standard web application deployment steps. Note that not all tools are
delivered as WAR files - primarily desktop tools which are started via Java
WebStart are deployed as WAR files. Many other tools, such as
report-generator tools, are installed into the <ISA_install>/ Toolbox folder
and will not require deployment to WebSphere Application Server.

Detailed instructions for the EAR deployment option are available here:
http://www.ibm.com/support/docview.wss?uid=swg27024926

--------------------------------------------

##Getting Started
IBM Support Assistant 5.0 Beta 3 ships with a default "[0000] Example Case".
This case contains a README.html file which documents a small tutorial to
walk through the process of using IBM Support Assistant to resolve a problem.
By using this tutorial, each user of the application can easily learn how to
leverage cases, files, tools and reports in IBM Support Assistant.
If the example case is deleted and you would like to restore it, you can
simply unzip the 0000_example_case.zip file found in the
<ISA_install>/ isa/cases directory. You may need to refresh your browser to
pick up the 0000 example case from the file system.

--------------------------------------------

##Starting and Stopping Server:
Note: The embedded server that comes with the product needs write access
to the install directory tree. Therefore it is recommended that the user
who installed the product also be the user that starts the server.

###Windows environments:
* Start Server:
To access shortcut icons for typical Windows installations, click on
Start->All Programs->IBM Support Assistant 5 Beta 3->Start IBM Support
Assistant 5, or you may open a command prompt and change the current
directory to the <install_location>/ISA5 folder and run the
start_isa.bat script to start the server.
* Stop Server:
To access shortcut icons for typical Windows installations, click on
Start->All Programs->IBM Support Assistant 5 Beta 3->Stop IBM Support
Assistant 5, or you may open a command prompt and change the current
directory to the <install_location>/ISA5 folder and run the
stop_isa.bat script to start the server.

### Linux environments:
* Start Server:
Linux IBM Installation Manager only supports the IBM Support Assistant 5.0
Beta 3 desktop quick launch icon for GNOME2 and KDE3 desktops. If you are
using a GNOME2 or KDE3 desktop, simply start the server by clicking on the
Start IBM Support Assistant 5 icon from the Application or Development
folder. If you are not running a GNOME2 or KDE3 desktop, then open a
terminal window and change the current directory to <install_location>\ISA5.
Then run the start_isa.sh script to start the server.
* Stop Server:
If you are using a GNOME2 or KDE3 desktop, simply stop the server by
clicking on the Stop IBM Support Assistant 5 icon from the Application or
Development folder. If you are not running a GNOME2 or KDE3 desktop, then
open a terminal window and change the current directory to
<install_location>\ISA5. Then run the stop_isa.sh script to start
the server.

--------------------------------------------

##Installing Tools
* Problem determination tools can be installed, updated and uninstalled
through the IBM Support Assistant Tools Administration view in addition to
using IBM Installation Manager. Refer to the InfoCenter documentation for
more details on using the Tools Administration view to manage tools.

Note: Managing tools through the Tools Administration view will only be
possible if IBM Support Assistant is initially installed through IBM
Installation Manager.

--------------------------------------------

##System requirements

###Operating Systems and architecture
* Linux RedHat 5 Update 6 (x86-64) - See configuration notes above about X11
display requirements
* Windows 2008 Server with SP2, Windows 2008 Server x64 with SP2,
Windows 7 with SP1 (x86-32 and x86-64)

###Hard disk space
* Minimum 900MB (additional space may be required for optional tool add-ons,
logs, case artifacts and optional EAR file for enterprise deployments)

###Memory
* Minimum 512MB physical memory (1GB or more recommended, depending on
artifacts analyzed by diagnostic tools).

###Browsers
* Internet Explorer 8 or 9
* Firefox 10 ESR or higher
* Google Chrome Version 26 or higher

###WebSphere Application Servers
* When deploying IBM Support Assistant as an EAR into an existing WebSphere
Application Server, v7.0.0.21 or higher is required.

--------------------------------------------

##Known Issues for Beta

###Installation and Configuration
* The product does not support installation into a directory path that
contains '.' characters or space characters.
* On Windows systems, the IBM Support Assistant application must be installed
on the C: drive
* When extracting the all-in-one zip to a long path name in Windows on C:
drive, then the unzip will fail to extract several Health Center files
because they are too long. To avoid this issue IBM recommends to extract to
a shorter path than (e.g., C:\Users\isa5\Downloads\isa-win-x86-64_5.0.0.0).
If the files are extracted to a shorter path (e.g., C:\IBM\isa5), then all
files are extracted successfully.
* The 'filestore.root' property in isa.properties is case-sensitive and
requires the exact path to work properly.
( eg. filestore.root=c:\\ISA5 versus filestore.root=c:\\isa5)
* If configuring isa.properties on a Windows installation, all backslashes in
a file path should be changed to double-backslashes ('\\') or single forward
slashes ('/')
* If deploying the IBM Support Assistant tools to an existing WebSphere
Application Server, the Deployment Manager heap size should be increased to
512 MB to accommodate WAR files over 50 MB.
* When installing or upgrading a tool with the IBM Support Assistant
Administration Console, the user is prompted to enter their IBM ID and
password. If the user has the browser's autocomplete function enabled, the
user will be prompted to save the user ID and password in the browser's
password manager. Once saved, the next time the install or upgrade dialog is
displayed, the user will be able to use the saved information. The user id
and password are saved on all supported browsers, however, on Internet
Explorer 8 and Internet Explorer 9, if the install or upgrade dialog is
displayed a second time before reloading the Administration Console and the
same user id is selected, the password field will not be automatically
filled in as expected.
Workaround:
Because the information has been saved, simply reload the Administration
Console page in the browser window. The next time the install or upgrade
dialog is displayed, the user will see the last saved password automatically
filled for the entered IBM ID.
* Launching the desktop versions of Health Center, Memory Analyzer and Garbage
Collection and Memory Visualizer (GCMV) on a Linux system must be done
from the command line. Before launching from the command line the following
system property must be set:

JAVAWS_VM_ARGS=-Dswing.defaultlaf=javax.swing.plaf.metal.MetalLookAndFeel

Once the JAVAWS_VM_ARGS property is set the desktop tool may be launched
using the javaws command from a 1.6+ JRE.

To launch Health Center:
javaws
http://<host>:<port>/isa5/com.ibm.java.diagnostics.healthcenter.jws/launch.jnlp

To launch Memory Analyzer:
javaws http://<host>:<port>/isa5/com.ibm.java.diagnostics.memory.analyzer.jws/launch.jnlp

To launch Garbage Collection and Memory Visualizer (GCMV)
javaws http://<host>:<port>/isa5/com.ibm.java.diagnostics.visualizer.jws/launch.jnlp

###Web Tools
* IBM Support Assistant requires fully qualified domain names when starting
sessions with Web tools. If you attempt to launch a Web tool and the host
name in the URL for the tool's browser window doesn't match the IBM
Support Assistant's host name, then you may need to update your DNS
configuration or 'hosts' file.

* When you install web tools such as "Memory Analyzer Web Edition" you must
restart IBM Support Assistant before the tool can be used. This is necessary
because web tools run in separate application servers which are started at
the same time as IBM Support Assistant.

* Periodically a 404 error may be returned when you launch Memory Analyzer
Web Edition. If this occurs then stop IBM Support Assistant and restart it.

###Desktop Tools
* NOTE: Running a desktop tool uses Java WebStart technology to launch the
tool from the browser as a Java process. This does not require or use a
Java browser plugin. Instead, the tool runs as a normal Java process on the
local machine and does not execute in the browser environment. Only a Java
JRE installed on the local system is required to launch the jnlp (Java
WebStart) tool.
* When running desktop tools with Oracle Java 1.7 update 7 on Windows 7 64-bit
you might see a security warning saying that the application's digital
signature has expired. Then if you click the "Run" button you might see a
popup with the message "Failed to validate certificate. The application
will not be executed." The problem is related to online certificate
validation and Oracle has documented a workaround in their bug database:
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=7197652.

Note that after implementing the workaround you might still see the security
warning saying that the certificate has expired, but the tool should launch
successfully.
* When IBM Support Assistant 5.0 launches the Health Center via Java Web Start
into an Oracle JRE, the tool fails to connect to health center agents
running in IBM JVMs. You can work around the problem by changing the
transport protocol the health center agent uses to communicate with Java
applications. To change the transport protocol set the following argument on
any IBM JVMs the Health Center will monitor.

-Xhealthcenter:transport= jrmp

For additional information about this workaround, see technote:
www.ibm.com/support/docview.wss? uid=swg21622012

###Miscellaneous
* If a case has been scanned by the Automated Analysis tool and additional
files are added to the case, a subsequent scan with the Automated
Analysis tool will not automatically load the new scan results in the user
interface. The scan status icon will show a refresh is required and
clicking on the scan status icon will reveal a hyper link message that
reads: "New scan results are available for review. Click here to discard the
current results and load the new results". Clicking the link is required to
see the new scan results. However after clicking the link, the browser
will reload the user interface and the case will not be reloaded in the UI
as expected. The user must select the case from the case selector dropdown
to see the new scan results.
* In some instances the left and right side of the User Interface on the
Tool Administration panel will not be in sync. This sometimes happens when
you try to use a filter Tag. For example, the Install button is visible,
although the selected tool has already been installed or the Uninstall
button is visible, although the tool has never been installed. If you run
into this scenario, you can simply select "All Tags" to resolve the issue.

--------------------------------------------

##Contacting IBM
* Support requests and feedback about the IBM Support Assistant 5.0 Beta are
conducted through the ISA developerWorks forum. Requests and comments can
be submitted at:

http://www.ibm.com/developerworks/forums/post!default.jspa?forumID=935

Enjoy!