IBM Rational Agent Controller, Version 6.0.0.1 Installation Guide


For Rational Application Developer, Version 6.0.0.1 / Rational Web Developer, Version 6.0.0.1 / Rational Software Architect, Version 6.0.0.1


(C) Copyright IBM Corporation 2004, 2005. All Rights Reserved.

Contents

Installing Agent Controller

  • Hardware prerequisites
  • Supported platforms
  • Supported JVMs
  • Locating the installation files
  • Installing Agent Controller on a workstation (AIX, HP-UX, Linux, Windows, Solaris)
  • Uninstalling previous versions of Agent Controller
  • Installing Agent Controller
  • Installing Agent Controller silently
  • Starting and stopping Agent Controller on a Windows workstation
  • Starting and stopping Agent Controller on a non-Windows workstation
  • Uninstalling Agent Controller on a Windows workstation
  • Uninstalling Agent Controller on a non-Windows workstation
  • Installing Agent Controller on the OS/400 (iSeries)
  • Uninstalling previous versions of Agent Controller
  • Installing Agent Controller
  • Starting and stopping Agent Controller on the OS/400 (iSeries)
  • Uninstalling Agent Controller on OS/400 (iSeries)
  • Installing Agent Controller on the OS/390 (z/OS)
  • Uninstalling previous versions of Agent Controller
  • Installing Agent Controller
  • Starting and stopping Agent Controller on the OS/390 (z/OS)
  • Uninstalling Agent Controller on the OS/390 (z/OS)
  • Using the Agent Controller security feature
  • Known problems and limitations
  • Agent Controller may fail to start on non-Windows platforms
  • Other errors during installation and uninstallation

    • Notices and trademarks

  • Notices
  • Programming interface information
  • Trademarks and service marks

    • Installing Agent Controller

    Agent Controller is a daemon that allows client applications to launch and manage local or remote applications and provides information about running applications to other applications. You must install Agent Controller separately before you can use the following tools:

    Notes:

    Hardware prerequisites

    Supported platforms

    Note for Linux: The Hyades Data Collection Engine feature of Agent Controller is compiled using libstdc++-libc6.2-2.so.3 shared library. Ensure that this shared library exists under the /usr/lib directory. If it does not exist, you have to install the RPM package compat-libstdc++ that comes with the operating system installation media.

    Agent Controller has been tested on the following platforms:

    Agent Controller has not been tested on the following platforms, but it is expected to run on these platforms:

    Agent Controller is not available for the following platforms:

    Supported JVMs

    In general, Agent Controller works with JVM version 1.4 and above. Here are the JVM versions (java -fullversion) that Agent Controller has been tested on:

    Locating the installation files

    The Agent Controller installation files that you extracted to a temporary directory are located in the directories listed below:

    Installing Agent Controller on a workstation (AIX, HP-UX, Linux, Windows, Solaris)

    Uninstalling previous versions of Agent Controller

    If you have a previous version of Agent Controller or any software derived from the Hyades Data Collection Engine, stop it, uninstall it, and clean up any left-over files before installing this version of Agent Controller. The following files may be left behind after uninstalling:

    Windows: 

    %RASERVER_HOME%\*.* (directory where Agent Controller is installed)
%SystemRoot%\system32\piAgent.dll (Windows' system32 directory)
%SystemRoot%\system32\LogAgent.dll
%SystemRoot%\system32\hcbnd.dll
%SystemRoot%\system32\hcclco.dll
%SystemRoot%\system32\hccldt.dll
%SystemRoot%\system32\hccls.dll
%SystemRoot%\system32\hcclserc.dll
%SystemRoot%\system32\hcclsert.dll
%SystemRoot%\system32\hcclsm.dll
%SystemRoot%\system32\hcjbnd.dll
%SystemRoot%\system32\hclaunch.dll
%SystemRoot%\system32\hcthread.dll
%SystemRoot%\system32\piAgent.dll
%SystemRoot%\system32\rac.dll
%SystemRoot%\system32\sysperf.dll

    Linux, AIX, HP-UX, Solaris: 

    $RASERVER_HOME/* (directory where Agent Controller is installed
/usr/lib/libpiAgent.so (or .sl on HP-UX)
/usr/lib/libLogAgent.so
/usr/lib/libhcbnd.so
/usr/lib/libhcclco.so
/usr/lib/libhccldt.so
/usr/lib/libhccls.so
/usr/lib/libhcclserc.so
/usr/lib/libhcclsert.so
/usr/lib/libhcclsm.so
/usr/lib/libhcjbnd.so
/usr/lib/libhclaunch.so
/usr/lib/libhcthread.so

    Installing Agent Controller

    1. Log in as Administrator (or root).
    2. Change to the directory where you unzipped the installation files for the appropriate platform.
    3. Run the program setup.exe. For non-Windows platforms, run setup.bin.
    4. Click Next on the welcome screen to proceed.
    5. Close all Eclipse platforms before continuing with the installation. Click Next to continue.
    6. Read the license agreement.
    7. Select Approve and click Next to proceed.
    8. You are informed that any existing Agent Controller will be removed. Click Next to proceed.
    9. Specify the path where Agent Controller should be installed and click Next to proceed.
    10. Select the Agent Controller features you would like to install:

      Click Next to proceed.

    11. Specify the path of the Java run-time environment (JRE) executable program java.exe or java which Agent Controller should be using. The JRE entered here will be used by Agent Controller for launching Java applications. Therefore, you may want to change the JRE path pre-filled by the installer program.
      Note:
      The JRE you provide at this time will be used both to run Agent Controller and for Agent Controller to launch Java applications. You may, however, later configure Agent Controller to a use separate JRE for each of these functions. For details, refer to Agent Controller help topic Configuring Applications to be launched by the Agent Controller.
    12. Optional: Specify the paths of IBM WebSphere Application Server version 5.0 (Windows only) and 5.1 if "Remote Support for WebSphere Application Server" was selected.
    13. Specify which hosts can access Agent Controller. The choices are:

      Click Next to proceed.

    14. If Security was selected in step 9 above: Choose the security setting.

      Click Next to proceed.

    15. Click Next on the summary screen to proceed.
    16. Click Finish after file transfer has completed.

    Installing Agent Controller silently

    You can run the installation process silently using the following parameters with the setup command:


    Parameter Description
    Required Parameters   
    -silent
    		tells the installer to run silently 
    -P installLocation
    		specify the installation path 
    -W javaHome_win.path
    		(Windows) specify the fully-qualified path of the java.exe executable 
    -W javaHome_unix.path
    		(non-Windows)specify the fully-qualified path of the java executable 
    -W hostList.type
    		specify how clients can connect to Agent Controller (ALL, LOCAL, CUSTOM)
    • ALL: allow any client
    • LOCAL: allow only localhost
    • CUSTOM: allow a list of clients (also requires the -W hostList.hosts parameter) 
    -W security.type
    		specify whether security should be turned on (true, false)
    • true: enable security (also requires the "-W security.users" optional parameter)
    • false: disable security
       
    Optional Parameters   
    -W wasHome_win.was510path
    		(Windows) specify the installed location of IBM WebSphere Application Server 5.1 
    -W wasHome_unix.was510path
    		(non-Windows) specify the installed location of IBM WebSphere Application Server 5.1 
    -W wasHome_win.was500path
    		(Windows) specify the installed location of IBM WebSphere Application Server 5.0 
    -W wasHome_unix.was500path
    		(non-Windows) specify the installed location of IBM WebSphere Application Server 5.0 
    -W hostList.hosts
    		specify the client hostnames, separated by commas (if hostList.type="CUSTOM") 
    -W security.users
    		specify which users can connect to Agent Controller (if security.type = "true") 
    -P hyadesdc_ibm_runtimeAnalysis_feature.active=false
    		specify to not install the Runtime Analysis feature (by default it is installed during silent install)
    Note:
    If you are installing Agent Controller silently over an unsecured connection, use parameter security.type.="false".

    Windows example: 

    setup.exe
  -silent
  -P installLocation="D:\IBM\AgentController"
  -W javaHome_win.path="d:\jdk1.4.1\jre\bin\java.exe"
  -W wasHome_win.was510path="d:\WebSphere5.1\AppServer"
  -W wasHome_win.was500path="d:\WebSphere5.0\AppServer"
  -W hostList.type="CUSTOM"
  -W hostList.hosts="host1,host2"
  -W security.type="true"
  -W security.users="user1,user2"

    Non-Windows example: 

    setup.bin
  -silent
  -P installLocation="/opt/IBM/AgentController"
  -W javaHome_unix.path="/opt/java1.4.1/jre/bin/java"
  -W wasHome_unix.was510path="/opt/WebSphere5.1/AppServer"
  -W wasHome_unix.was500path="/opt/WebSphere5.1/AppServer"
  -W hostList.type="CUSTOM"
  -W hostList.hosts="host1,host2"
  -W security.type="true"
  -W security.users="user1,user2"

    Using a response file

    You can create a response file (for example, setup.rsp) to store all the above parameters, instead of specifying them on the command line: 

    # Start of response file
-P installLocation="D:\IBM\AgentController"
-W javaHome_win.path="d:\jdk1.4.1\jre\bin\java.exe"
-W wasHome_win.was510path="d:\WebSphere5.1\AppServer"
-W wasHome_win.was500path="d:\WebSphere5.0\AppServer"
-W hostList.type="CUSTOM"
-W hostList.hosts="host1,host2"
-W security.type="true"
-W security.users="user1,user2"
# End of response file

    To install using the response file:

    Windows: setup.exe -silent -options d:\temp\setup.rsp

    Non-Windows: setup.bin -silent -options /tmp/setup.rsp

    Starting and stopping Agent Controller on a Windows workstation

    Starting and stopping Agent Controller on a non-Windows workstation

    Uninstalling Agent Controller on a Windows workstation

    Uninstalling Agent Controller on a non-Windows workstation

    1. Run the program uninstall.bin from the installation location's _uninst directory (for example, /opt/IBM/AgentController/_uninst).
    2. Follow the on-screen instruction to complete the uninstallation.
    3. To perform a silent uninstallation, use the command uninstall.bin -silent.

    Installing Agent Controller on the OS/400 (iSeries)

    Uninstalling previous versions of Agent Controller

    If you have a previous version of Agent Controller or any software derived from the Hyades Data Collection Engine, stop it and uninstall it before installing this version.

    Installing Agent Controller

    1. On the iSeries host, create a library called HYADESDC and another library called IBMRAC: 
      CRTLIB HYADESDC
CRTLIB IBMRAC
    2. On the iSeries host, in the HYADESDC library, create an empty save file called HYADESDC.SAVF: 
      CRTSAVF HYADESDC/HYADESDC
    3. On the iSeries host, in the IBMRAC library, create an empty save file called IBMRAC.SAVF: 
      CRTSAVF IBMRAC/IBMRAC
    4. (Not for Rational Web Developer) On the iSeries host, in the IBMRAC library, create an empty save file called IBMRTA.SAVF: 
      CRTSAVF IBMRAC/IBMRTA
    5. Use FTP to add the file IBMRAC.SAVF from the installation CD to the library IBMRAC located on the iSeries host using BINARY mode transfer.
    6. Use FTP to add the file HYADESDC.SAVF from the installation CD to the library HYADESDC located on the iSeries host using BINARY mode transfer.
    7. (Not for Rational Web Developer) Use FTP to add the file IBMRTA.SAVF from the installation CD to the library IBMRAC located on the iSeries host using BINARY mode transfer.
    8. Restore the save file HYADESDC.SAVF located on the iSeries host to the library HYADESDC, by typing: 

      RSTOBJ OBJ(*ALL) SAVLIB(HYADESDC) DEV(*SAVF) SAVF(HYADESDC/HYADESDC)
    9. Restore the save file IBMRAC.SAVF located on the iSeries host to the library IBMRAC, by typing: 

      RSTOBJ OBJ(*ALL) SAVLIB(IBMRAC) DEV(*SAVF) SAVF(IBMRAC/IBMRAC)
    10. (Not for Rational Web Developer) Restore the save file IBMRTA.SAVF located on the iSeries host to the library IBMRAC, by typing: 

      RSTOBJ OBJ(*ALL) SAVLIB(IBMRAC) DEV(*SAVF) SAVF(IBMRAC/IBMRTA)
    11. Start QShell and create, on the integrated file system (IFS), the /opt/hyadesdc directory.
    12. Restore the save file HYADESIFS.SAVF in HYADESDC to the IFS directory /opt/hyadesdc. For example: 

      RST DEV('/QSYS.LIB/HYADESDC.LIB/HYADESIFS.FILE') OBJ('/opt/hyadesdc/*')
    13. Restore the save file IBMRACIFS.SAVF in IBMRAC to the IFS directory /opt/hyadesdc. For example, type the following command on one line: 

      RST DEV('/QSYS.LIB/IBMRAC.LIB/IBMRACIFS.FILE') OBJ('/opt/hyadesdc/*') ALWOBJDIF(*ALL)
    14. (Not for Rational Web Developer) Restore the save file IBMRTAIFS.SAVF in IBMRAC to the IFS directory /opt/hyadesdc. For example, type the following command on one line: 

      RST DEV('/QSYS.LIB/IBMRAC.LIB/IBMRTAIFS.FILE') OBJ('/opt/hyadesdc/*') ALWOBJDIF(*ALL)
    15. After you have installed Agent Controller, change the directory to the installed location's bin directory /opt/hyades/bin, and run the setup script by typing: 

      ./SetConfig.sh
    16. Follow the on-screen prompt to configure Agent Controller.

    Starting and stopping Agent Controller on the OS/400 (iSeries)

    1. To start Agent Controller, add the HYADESDC and the IBMRAC libraries to the library list: 
      ADDLIBLE HYADESDC
ADDLIBLE IBMRAC
    2. Submit the RAStart job by typing: 

      SBMJOB CMD(CALL RASERVER) JOBD(RASTART)
    3. To stop Agent Controller, terminate the RAStart job by typing: 

      ENDJOB JOB(RASTART)

    Uninstalling Agent Controller on OS/400 (iSeries)

    1. Remove the HYADESDC and IBMRAC library.
    2. Remove the IFS directory /opt/hyadesdc (including all subdirectories and files).

    Installing Agent Controller on the OS/390 (z/OS)

    Uninstalling previous versions of Agent Controller

    If you have a previous version of Agent Controller or any software derived from the Hyades Data Collection Engine, stop it and uninstall it before installing this version.

    Installing Agent Controller

    1. In a UNIX(R) System Services shell, go to the directory where you want to install Agent Controller. It is recommended that you install it in the /usr/lpp/ directory.
    2. Transfer the install images ibmrac.os390.pax and (not for Rational Web Developer) ibmrta.os390.pax to the installation directory.
    3. Issue the following command to extract Agent Controller files: 

      pax -ppx -rf ibmrac.os390.pax
    4. (Not for Rational Web Developer) Change the directory to the installation directory /usr/lpp/IBM/AgentController and type the following command to extract the runtime analysis extensions: 

      pax -ppx -rf ../../ibmrta.os390.pax
    5. Change the directory to the installation bin directory /usr/lpp/IBM/AgentController/bin, and run the makelinks script by typing: 

      ./createLinks.sh
    6. Make the Agent Controller shared object files program controlled by issuing the following commands in a UNIX(R) System Services shell (Note: for Rational Web Developer only issue the first command): 

      extattr +p /usr/lpp/IBM/AgentController/lib/*.so
 

      extattr +p /usr/lpp/IBM/AgentController/plugins/com.ibm.rational.pd.probekit/lib/*.so
    7. After you have installed Agent Controller, change the directory to the installed location's bin directory /usr/lpp/IBM/AgentController/bin, and run the setup script by typing: 

      ./SetConfig.sh
    8. Follow the on-screen prompt to configure the Agent Controller.

    Data Channel usage on z/OS:

    In order to set a large dataChannelSize in the serviceconfig.xml file you may need to increase the maximum shared memory segment size setting on your machine. To do this, increase the IPCSHMMPAGES value in the BPXPRMxx parmlib member. This value is the maximum number of 4K pages that your data channel can be. For example, if you want to set dataChannelSize to 32M, you must set IPCSHMMPAGES to a value greater than 8192.

    To allow Agent Controller to communicate with a large number of agents simultaneously, you must set the IPCSHMNSEGS value in the BPXPRMxx parmlib member to an appropriate value. This value specifies the maximum number of attached shared memory segments for each address space. The default value is 10 so you should increase this to 50.

    For more information about the data channels used by Agent Controller, refer to the online help information for Agent Controller.

    For more information about z/OS BPXPRMXX parmlib members and how to update them, refer to IBM z/OS MVS(TM) Initialization and Tuning Reference.

    Starting and stopping Agent Controller on the OS/390 (z/OS)

    Note: RAServer requires the directories of the JRE that contain executable libraries such as libjvm.so to be added to the LIBPATH environment variable. For example, if you are using the IBM JRE 1.4.1, the LIBPATH variable would be set as follows: 

    export LIBPATH=/usr/lpp/java/IBM/J1.4/bin/classic:/usr/lpp/java/IBM/J1.4/bin:$LIBPATH

    Uninstalling Agent Controller on the OS/390 (z/OS)

    Using the Agent Controller security feature

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

    Known problems and limitations

    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.

    Agent Controller may fail to start on non-Windows platforms

    Agent Controller may fail to start on non-Windows platforms with the following message: 

    RAServer failed to start.

    This failure is usually caused when TCP/IP port 10002 is not free. Agent Controller listens on this port by default. Another process running on the system may be using this port when Agent Controller is started or perhaps Agent Controller was just stopped and then restarted before the port could be released.

    If Agent Controller failed to start, you can start it as follows:

    Other errors during installation and uninstallation

    If you encounter errors during installation or uninstallation, this may be due to the fact that the object files of Agent Controller are loaded by running processes. To ensure the object files can be modified, do the following:

    1. Shut down your Rational software development platform product.
    2. Terminate all java.exe processes that contain either the Java Profiling Agent or the J2EE Request Profiler.

    Notices and trademarks

    Notices

    U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

    This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this documentation in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

    IBM may have patents or pending patent applications covering subject matter described in this documentation. The furnishing of this documentation does not give you any license to these patents. You can send license inquiries, in writing, to:

    IBM Director of Licensing
    IBM Corporation
    North Castle Drive
    Armonk, NY 10504-1785
    U.S.A.

    For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

    IBM World Trade Asia Corporation
    Licensing
    2-31 Roppongi 3-chome, Minato-ku
    Tokyo 106, Japan

    The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR CONDITIONS OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

    This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

    Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

    IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

    Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

    Intellectual Property Dept. for Rational Software
    IBM Corporation
    3600 Steeles Avenue East
    Markham, Ontario
    Canada L3R 9Z7

    Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

    The licensed program described in this documentation and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

    Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

    Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

    All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

    This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples may include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

    COPYRIGHT LICENSE:

    This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.

    Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows:

    © (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp. 2000, 2005. All rights reserved. 

    If you are viewing this information softcopy, the photographs and color illustrations may not appear.

    Programming interface information

    Programming interface information is intended to help you create application software using this program.

    General-use programming interfaces allow you to write application software that obtain the services of this program's tools.

    However, this information may also contain diagnosis, modification, and tuning information. Diagnosis, modification and tuning information is provided to help you debug your application software.

    Warning: Do not use this diagnosis, modification, and tuning information as a programming interface because it is subject to change.

    Trademarks and service marks

    The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both:

    Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

    Windows and Windows NT are trademarks of Microsoft Corporation in the United States, other countries, or both.

    Intel and Pentium are trademarks of Intel 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.

    Other company, product or service names, may be trademarks or service marks of others.