Installing IBM Rational Performance Tester

The following chart summarizes how each product interacts when you attempt to install another product that contains the Rational Software Development Platform.

• Upgraded products. When a product is upgraded, the existing product is removed and replaced. If a newly upgraded product is uninstalled, the entire product is removed from the system. For example, if you install Application Developer, upgrade to Software Architect, and then uninstall Software Architect, all plug-ins, including the development platform, are uninstalled. To replace Application Developer, you must reinstall Application Developer.
• Shell Share products. If two or more products are installed in a shell sharing scenario, the development platform is left in place until the last product is uninstalled. For example, if Application Developer and Performance Tester are installed, and you uninstall Application Developer, Performance Tester (and the development platform) remain on the system.

When you go to the Start menu (or the equivalent menu for Linux), the top-level menu is always IBM Rational, regardless of which product you have installed.

One subfolder for each product is available from the top-level menu. These subfolders contain links to product-specific information (such as readme files), and a launchpoint for the Rational Software Development Platform. The launchpoint has the name of the product.

You can also start the common development platform directly from the IBM Rational menu using a launchpoint labeled Rational Software Development Platform.

The following tables list supported platform and system requirements for CPU, RAM, disk space, network interface, and display. System requirements are the same for Performance Tester and Agent Controller. See the Release Notes for the latest updates.

You do not need a license key to install Rational Performance Tester. However, you do need license keys if you plan to emulate a load of more than five concurrent virtual users. For example, you can run Performance Tester with four virtual users and no license key (on a trial basis, for example), but if you choose to run ten virtual users, you must purchase a virtual tester license key pack supporting 5 or more additional virtual users. License keys are sold in groups called virtual tester license key packs. These packs come in groups of 5, 50, 100, 250, 500, 1000, 2500, 5000, 10,000, 20,000, 50,000, and 100,000 virtual testers.

Virtual tester license key packs are not divisible. Performance Tester checks out a pack when it runs a test with more than five virtual testers. If you have a license pack for 50 virtual testers, and Performance Tester initiates a test with 25 virtual testers on machine A, then machine B is limited to five virtual testers until the test initiated from machine A is completed.

On the other hand, virtual tester license key packs are additive. Performance Tester on a specific machine can check out multiple license keys from a given license server to run a test. For example, machine A can check out two 50 virtual tester license key packs to run a test with 100 virtual users.

When you purchase Performance Tester through Passport Advantage, the Passport Advantage software shipment or download contains a document called Important Licensing and Installation Information. That document contains the following information:

• List of product components
• License key type required for each component (for example, the driver components require floating licenses.)
• The product account number
• Instructions for obtaining the license key for each component

You can use either that document or the Proof of Entitlement certificate to obtain license keys from IBM.

To obtain license keys:

1. Go to http://www.ibm.com/rational/support/licensing..
2. Click Rational Licensing and Download Center.
3. Register with IBM Web Management (IWM) and click Request and Manage License Keys.
4. Follow the instructions, using the information in the Important Licensing and Installation Information document or the Proof of Entitlement certificate to obtain license keys. License keys will be sent to you in a file with a .upd file extension.

You use license keys to authenticate with a Rational License Server. If you use other Rational products, you probably have access to a license server. If you do not, follow the procedures in the IBM Rational Software License Management Guide to set up a license server. You can download this publication at no charge from http://www.ibm.com/shop/publications/order.

On Linux, you can install a Rational License Server directly from the launchpad. On the Linux launchpad, click Install IBM Rational Common Licensing Server for Linux. This option is currently not available from the Windows launchpad.

License servers and clients can run on different platforms. For example, if a license server is already running on a Linux computer, you do not need to install a license server on Windows to serve Windows clients.

This section describes additional steps you may need to perform before installing the product.

To install Rational Performance Tester on a Windows or Linux system:

1. On Windows, log in as Administrator. On Linux, log in as root.
2. Insert the Performance Tester CD in the CD-ROM drive. On Windows, the launchpad application starts if Autorun is enabled. On Linux, you must start the launchpad.bin file from the root directory of the CD-ROM.
3. On the launchpad, click Install IBM Rational Performance Tester. The installation wizard opens the Welcome page. Click Next when you are ready to proceed.
4. Review the license agreement. If you agree to the terms, click I accept the terms of the agreement and click Next.
5. Specify the directory where you want to install the local components. It is recommended that you accept the default directory location. Click Next.
6. On the Features page, select the features you want to install.
   • Language Pack: Installs support for languages other than English.
   • Examples for Eclipse Plug-In Development: Installs samples of Eclipse Plug-In implementations.

   Click Next when you are ready to proceed.

7. Specify either the typical (default) or custom installation of Agent Controller. Click Next.
8. On Windows, indicate whether you want the License Key Administrator to start automatically at the end of the installation process. Click Next.
   Note: To start the License Key Administrator manually, click Start > All Programs > Rational Software > Rational License Key Administrator
9. On the Summary page, review the options you have selected. When you are ready to begin the installation, click Next.
10. When the installation is complete, click Finish to exit the wizard. Unless you selected the custom installation of Agent Controller, you return to the launchpad. To exit the launchpad, click Exit.
11. After exiting from the launchpad, start Rational Performance Tester and adjust the Java Virtual Machine heap size.
    1. Click Window > Preferences.
    2. Expand Test.
    3. Click Performance Test Workbench.
    4. In Java Virtual Machine heap size, type the memory size recommended on the screen.
    5. Click OK.

Before you install the product, verify that you have sufficient space.

• You must have approximately 1.5 GB of disk space to store the full set of downloadable images.
• On Windows, your environment variable TEMP or TMP must point to a valid temporary directory with at least 500 MB free.
• On Linux, you need at least 500 MB free space in /tmp.

To download and create the electronic installation image:

1. Download all required parts and desired optional parts to the same temporary directory. If any optional parts are needed later, download the additional optional parts and rerun the extraction tool before attempting the installation.
   Note: When upgrading from one Rational Software Development Platform product to another using the electronic images, ensure that you download and extract the same set of images for the new product that you downloaded and extracted for the original product. The same components installed in the original product will be automatically installed in the upgraded product. For example, if the Language Pack was originally installed, when upgrading you will need to download and extract the Language Pack into the new product installation image.
2. Start the extractor wizard.
   • On Windows, launch the extractor.exe file located in your temporary directory. This starts the wizard that creates the installation image.
   • On Linux, modify the permissions on the extractor.bin file that is located in this temporary directory by typing chmod +x extractor.bin. Then, execute the file by typing ./extractor.bin.
3. Follow the instructions in the wizard to specify where you want to create the image and which features you want to include.
4. After the image is created, decide when to install the product.
   • To install the product immediately, click Finish.
   • To install the product later, clear the Start the installation wizard check box. When you are ready to run the installation program, launch disk1\launchpad.exe from the directory where you created the installation image.
5. Follow the instructions described in Installing Rational Performance Tester from the CD-ROM.

You can place a copy of the installation image on a network drive so that users can install across a network.

To run the installation program from a network drive, you must either work with a downloaded electronic image of Rational Performance Tester or copy the contents of the CD as described below.

You need approximately 1.5 GB of disk space to store the contents of the Windows, Linux, and Agent CDs on the disk. To copy the core installation files from the CD:

1. For a Windows installation, create a temporary directory on a network drive where you want to store the image (for example, network_drive:\install_image).
2. Insert the Rational Performance Tester installation CD for Windows into your CD drive.
3. Under the temporary directory, create a subdirectory called disk1. This subdirectory must be called disk1 and it must be lowercase.
4. Copy all the files and directories on the installation CD to the disk1 subdirectory in the temporary directory.
5. Repeat steps 3 and 4 to copy the contents of the Linux and Agent CDs to their own subdirectories. (On Linux, be sure to log in as root.)

If you do not want to interact with the installation wizard, you can run the Rational Performance Tester installation program silently.

To uninstall Rational Performance Tester on a Windows system:

To uninstall Rational Performance Tester on a Linux system:

1. Log in as root.
2. Change directory to install_dir/rpt_prod/_unist.
3. Run uninstall.bin.

Agent Controller is installed automatically after Rational Performance Tester is installed.

To perform a custom installation of Agent Controller on a local Windows system where Rational Performance Tester is installed:

1. Specify the custom Agent Controller installation when installing Rational Performance Tester.
2. When the Agent Controller Welcome screen opens, click Next.
3. Ignore any warnings about checking to make sure that the Eclipse platform is not running. Click Next to continue.
4. Read and accept the license agreement and click Next to proceed.
5. If you have an existing installation of Agent Controller, you are informed that it will be removed. Click Next to proceed.
6. Specify the path where Agent Controller should be installed and click Next to proceed.
7. Select Agent Controller features you would like to install and click Next to proceed. You should accept the default, which selects all features.
   • Hyades Data Collection Engine: Framework provided by the Eclipse open source project for launching and profiling local or remote Java applications. Required.
   • IBM Rational Plugins: Must be selected in order to select the remaining features in this list.
   • Logging: an event-based logging framework for profiling and tracing applications. Required.
   • Component Test: Legacy support for manual test enablement. Required.
   • Runtime Analysis: Functionality for probe insertion, code coverage, and leak analysis. Required.
   • Security: Creates a secure data communication channel between the Eclipse workbench and Agent Controller. Recommended.
   • Remote support for WebSphere Application Server: Functionality for connecting to a remote WebSphere Application Server, version 5.0 or 5.1, for activities such as deployment, administration, and performance analysis. Not used by Rational Performance Tester.
8. Specify the path of the Java run-time environment (JRE) that Agent Controller should be using and click Next to proceed. Rational Performance Tester requires JRE versions 1.4.2 or later. This requirement is met when installing from the Rational Performance Tester installation media and should not be changed. The JRE entered here will be used by Agent Controller for launching Java applications.
9. If Remote Support for WebSphere Application Server was selected in step 7, specify the paths of IBM WebSphere Application Server version 5.0 and 5.1 and then click Next . Because Rational Performance Tester does not use these features, you can leave this page blank.
10. Specify which hosts can access Agent Controller and then click Next . This setting affects system security. The choices are:
    • Any computer: The least secure setting. Any other machine with access to this machine can execute an arbitrary program that runs with administrator/root privilege.
    • This computer only (default) : The most secure setting. This is the recommended setting.
    • Specific computers: Not recommended, but if you use this feature be sure to use commas to separate host names in a list.
11. If Security was selected in step 7, choose one of the following security settings and then click Next to proceed.
    • Disable: Communication will not be encrypted and access control will be limited to the defined host list. (Default selection.)
    • Enable: Communication will be encrypted and all connections will be forced to authenticate for Secure Sockets Communications. Under Users, list the users that can connect to Agent Controller. (Use commas to separate user names.) These users will be required to authenticate to use the tool.
12. Click Next on the summary screen to proceed.
13. Click Finish after file transfer has completed.

Before you install Agent Controller, verify that the Eclipse Platform is not running. If necessary, exit Eclipse.

1. Insert the installation CD into a CD-ROM drive on a remote Windows system that does not have Rational Performance Tester installed.
   Note: You must install Agent Controller using the installation CD and not from another system where Agent Controller is already installed.
2. Log in as an Administrator. Because Agent Controller runs as a system service, you should use a user ID with administrator privileges to install Agent Controller. Otherwise, the Agent Controller service might fail to install or start.
3. If autorun is disabled, run launchpad.exe from the root of the first installation CD.
4. From the launchpad, select Install Rational Performance Tester Agent Controller. Follow the wizard instructions.

By default, the Agent Controller service starts when it is installed and then whenever you start the computer. For more information about working with Agent Controller, see the online help.

To install or upgrade Agent Controller:

1. Log in as root.
2. Navigate to the root directory of the CD-ROM and start launchpad.bin.

See the online help for more information about working with Agent Controller.

On Linux platforms, the Agent Controller process (RAServer) does not start automatically. You must start it yourself.

To start Agent Controller:

1. Change directory to $RASERVER_HOME/bin.

   where by default $RASERVER_HOME is /opt/IBM/Rational/SDP/6.0/IBM_Agent_Controller.

2. Type ./RAStart.sh.

If Agent Controller fails to uninstall successfully, there might be Java processes that contain either the Java Profiling Agent or the J2EE Request Profiler running. You must end these processes before you can uninstall Agent Controller successfully. For more information about profiling an application, see the online help.

To uninstall Agent Controller on a Linux system:

1. Close Rational Performance Tester.
2. Log in as root.
3. In the root directory, navigate to the _uninst.bin file.
4. Run _uninst.bin.

The following list contains hints and tips for using the Agent Controller security feature on all platforms:

• Authentication is provided by the operating system. Only users specified at installation time are allowed to authenticate. If the user name ANY is provided, any valid user name and password pairs are forwarded to the operation system for authentication. Otherwise, only listed pairs are forwarded.
• When security is enabled, the users specified at installation time are required to authenticate with the operating system before any information can be exchanged with Agent Controller. The workbench user must provide a valid user name and password combination that is an operating system user name and password.
• Domain name passwords are not authenticated. You must provide local user name and password pairs. (Windows only)
• No key management capabilities are provided. Agent Controller uses Java keystores for security.
• A sample keystore and exported certificate are in the Agent Controller directory \plugins\com.ibm.etools.pd.security\security for Windows, and /plugins/com.ibm.etools.pd.security/security for Linux. Replace these with a keystore containing meaningful certificates.

This section covers known problems and limitations related to installing and uninstalling Agent Controller. Except where otherwise noted, the following information applies to all operating systems that are supported for Agent Controller.

RAServer failed to start.

You must install license keys to run more than five virtual users. This section tells you how to do this.

RATIONAL_LICENSE_FILE=@[SERVER]

The Rational Software Development Platform product you purchased entitles you to a free license of Rational ClearCase LT.

If you do not have the ClearCase LT product media, you must download and install the latest supported version of ClearCase LT.

If you already have the ClearCase LT v2002.05 or ClearCase LT v2003.06 product media, you must download and install the latest ClearCase LT patches to support the ClearCase LT integration with the Rational Software Development Platform product.

For instructions about how to obtain the latest supported version of ClearCase LT, and the latest required patches that are supported with the IBM Rational Software Development Platform, go to IBM Rational Support Technote number 1188585: www.ibm.com/support/docview.wss?uid=swg21188585. Or, go to http://www.ibm.com and enter 1188585 in the Search box.

Before installing Rational ClearCase LT, read the release notes and installation documentation for the product. This documentation is available online from the IBM Publications Center at http://www.ibm.com/shop/publications/order. Also refer to http://www.ibm.com/software/rational/support/documentation. To open Acrobat PDF files, you must have installed the Adobe Reader software, which you can download from http://www.adobe.com/products/acrobat/readstep2.html.

On Windows, download the latest IBM Rational ClearCase LT Release Notes for Windows, the Rational Software Desktop Products Installation Guide, and Rational Software Server Products Installation Guide for Windows from the IBM Publications Center at http://www.ibm.com/shop/publications/order, as follows:

1. Select your country/region on the Welcome page of the Publications Center.
2. Click on the Search for Publications link. The Quick Publications Center search page opens.
3. To download the Rational Software Desktop Products Installation Guide for Windows, Version 2003.06.13:
   1. Type S126-5304-01 in the Publication number field and press Enter.
   2. On the resulting page, choose your preferred method of downloading the document.
4. To download the Rational Software Server Products Installation Guide for Windows, Version 2003.06.13:
   1. Type S126-5300-01 in the Publication number field and press Enter.
   2. On the resulting page, choose your preferred method of downloading the document.
5. To download the Rational ClearCase LT Release Notes for Windows:
   1. Type GI11-4669-03 in the "Publication number" field and press Enter.
   2. On the resulting page, choose your preferred method of downloading the document.

On Linux, download the latest Rational ClearCase LT Release Notes and Rational ClearCase LT Installation Guide for Linux from the IBM Publications Center at http://www.ibm.com/shop/publications/order.

1. Select your country/region on the Welcome page of the Publications Center.
2. Click on the Search for Publications link. The Quick Publications Center search page opens.
3. To download the ClearCase LT Installation Guide for Version 2003.06.00 and later, UNIX edition:
   1. Type S126-5310-00 in the Publication number field and press Enter.
   2. On the resulting page, choose your preferred method of downloading the document.
4. To download the Rational ClearCase LT Release Notes for UNIX:
   1. Type GI11-6232-00 in the Publication number field and press Enter.
   2. On the resulting page, choose your preferred method of downloading the document.

Refer to the ClearCase LT Desktop Installation Guide for details on preparing to install the product.

1. From the root directory of the installation image, run setup.exe. The Rational Setup Wizard will open. Click Next to continue.
2. On the Product Selection screen, choose Rational ClearCase LT. Click Next to continue.
3. Choose a deployment method:
   • Enterprise deployment (create a network release area and customize it using Siteprep).
   • Desktop Installation from CD image. (Refer to the Desktop Installation Guide to learn about selecting a deployment type.)
4. For enterprise deployment:
   • Follow the instructions in the dialog box to complete the configuration process.
   • Select Done when you have completed all the configuration steps.
5. For desktop installation from the CD image:
   • Select installation of either both the client and server software or only the client software. Click Next to continue.
   • The Setup wizard opens. Click Next to continue.
   • The next screen displays the message There are some product-specific warnings for this installation: STOP! Before proceeding with this install, please close all applications and disable anti-virus software. Before continuing with the installation, go to the Web address provided in the warning message (http://ibm.com/support/docview.wss?rs=203&context=SW000&q1=1135295&uid=swg21135295 ). Read the document and take any steps required to prevent potential system corruption. Click Next to continue.
6. Follow the on-screen instructions to complete the configuration process. By default, Rational ClearCase LT is installed in the system_drive:\Program Files\Rational\ directory. Select Done when you have completed the configuration steps.
7. Select Install to begin the installation.

By default, Red Hat Enterprise Linux 3.0 and SuSE Linux Enterprise Server (SLES) Version 9, set the locale for US installations to a Unicode locale (en_US.UTF-8), and might also do so for international installations. ClearCase LT does not support Unicode locales. Therefore, you must explicitly set your locale to a non-Unicode setting. You can change the locale as follows:

• For Red Hat Enterprise Linux 3.0, set the value of LANG in the /etc/sysconfig/i18n file to a non-Unicode locale. Possible locales to use are the C locale or en_US.iso885915. Once you have set the LANG environment variable to a value that ClearCase supports, make sure that the SUPPORTED variable in the i18n file also contains this value. If it does not, add this value to the SUPPORTED variable.
• For SuSE Linux Enterprise Server (SLES) Version 9, turn off UTF-8 encoding as follows:
  1. Launch the YaST Control Center. (For example, from the SuSE icon in the bottom corner of the screen, select SuSE > System > YaST.)
  2. In YaST, select System.
  3. Select Choose Language.
  4. Click the Details button.
  5. Clear the Use UTF-8 encoding field and then click OK.
  6. Click Accept.
  7. Log out, then log back in.

To install Rational ClearCase LT Version 2003.06.00 on Linux:

1. Log in as root user by typing: su
2. From the directory where you downloaded Rational ClearCase LT, extract the contents of the ClearCase LT download file to a release area as follows:
   1. Enter mkdir /usr/ccase_lt_rls to create the release area directory. The instructions that follow assume you used /usr/ccase_lt_rls as the release directory. If you specified a different name, you will need to use it in place of /usr/ccase_lt_rls.
   2. Enter uncompress <cclt_filename.Z> where <cclt_filename.Z> is the name of the compressed ClearCase LT download tar file. The resulting file will have the extension .tar instead of .tar.Z. For example, if the file is named C54UANA.tar.Z, the command uncompress C54UANA.tar.Z produces a file named C54UANA.tar.
   3. Expand the tar file into the release area directory by entering the command tar xvf <cclt_filename> -C /usr/ccase_lt_rls where <cclt_filename> is the name of the uncompressed ClearCase LT tar file.
   Note: The extracted files include the product documentation. Refer to the Release Notes and Installation Guide before continuing the installation process. For an explanation of the purpose of a release area, see the Installation Guide.
3. Prepare your release area by running site_prep and follow the instructions:

   cd /usr/ccase_lt_rls/rhat_x86/clearcase/install ./site_prep

4. Enter the values for the prompts per your requirements. When prompted to provide the ClearCase LT license host, specify the hostname of your machine. Refer to the Rational ClearCase LT Installation Guide for additional details on running site_prep.
5. Install ClearCase by running install_release and follow the instructions:

   ./install_release

   Enter the values for the prompts per your requirements. The following is an example for a ClearCase LT Client installation on SuSE Linux Enterprise Server (SLES) Version 9:

   1. Choose Local Install.
   2. Accept the license agreement.
   3. Choose Standard install.
   4. Choose 3. ClearCase LT Client installation.
   5. When the install_release program ends, it displays a message saying that it completed with no errors. The message also gives the location and name of the Log file. Refer to the Rational ClearCase LT Installation Guide for additional details on running install_release.
6. Add the ClearCase executable file to your search path.

   For example, if you are using a Bourne shell, you can run the following command to modify your path:

   PATH=${PATH}:/opt/rational/clearcase/bin export PATH

   Refer to the Installation Guide for detailed instructions and for additional information on customizing the client host's environment for ClearCase LT.

7. If you have not already installed Rational Performance Tester, do so now.
8. To verify that ClearCase has been installed correctly, run the following command from a non-root user ID. If the command succeeds, the host is able to acquire a ClearCase LT license. If an error message is returned, consult the ClearCase LT documentation.

   cleartool hostinfo -long

9. Start the Rational Development platform and make sure that you can connect to ClearCase.
   Note: By default, the release area is the location for the extracted installation files, including the files for the uninstall program. If you delete this directory, you will not be able to run the uninstall program.

When you have Rational Performance Tester installed on the same computer as Rational ClearCase LT, you do not need to configure Rational ClearCase LT licensing. However, if you install Rational ClearCase LT without Rational Performance Tester, you will need to configure ClearCase LT licensing. For details on how to configure licensing, see the ClearCase LT installation guide.

The Rational ClearCase LT license that is included with Rational Performance Tester does not include a license for the Rational ClearCase Web interface. To use the Rational ClearCase Web interface, you must purchase additional Rational ClearCase or ClearCase LT licenses. For more information on obtaining licenses, contact IBM Rational Support at 1-800-IBM-SERV (1-800-426-7378).

For information on using Rational ClearCase, refer to the ClearCase online help.

If diagram files have been checked into Versioned Object Bases (VOBs) in your ClearCase environment before patching or setting up the environment as described above, run the following command to change the file type of the elements in the VOB so that they can be merged properly:

cleartool find . -name *.emx -exec "cleartool chtype -force xtools2 %CLEARCASE_PN%"

To uninstall Rational ClearCase LT on a Windows system:

1. Close Rational Performance Tester.
2. Open the Control Panel, then open the Add/Remove Programs window. Select Rational ClearCase LT and click Change/Remove to uninstall.
3. Follow the instructions in the wizard to uninstall the product.

To uninstall Rational ClearCase LT on a Linux system:

1. Log in as root user by typing: su
2. Run install_release from the release area directory. For example, if the release area is located in the /usr/ccase_lt_rls directory, type:

   cd /usr/ccase_lt_rls/rhat_x86/clearcase/install ./install_release

3. Select Local Deinstall to remove software from the local computer.