IBM Agent Controller V7.0.1 Installation Guide

IBM Agent Controller V7.0.3.3
Installation Guide

Contents

 

 

 

 

 

Introduction

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:

  • Profiling tools to profile your applications. Agent Controller must be installed on the same system as the application that you are profiling.
  • Logging tools to import remote log files. Agent Controller must be installed and running on the remote system from which the log files are imported.
  • Component testing tool to run test cases. Agent Controller must be installed on the systems on which you run the test cases.
  • Tools for remote application testing on WebSphere(R) Application Server version 5.0 or 5.1. (Agent Controller does not have to be installed for remote publishing of applications; or for local application publishing or testing.) Note that WebSphere Application Server version 6.0 has this functionality built in, so Agent Controller is not required on version 6.0 target servers.

Notes:

  • It is highly recommended that you install Agent Controller behind a firewall.
  • For more information on the security implications of using Agent Controller, refer to the Agent Controller documentation.
  • The online documentation for Agent Controller is not installed until the software is installed. At that time, the documentation is added to the online help.
  • Before installing Agent Controller version 7.0.3.3, you must uninstall the previous version of Agent Controller using the instructions provided below.

Refer to the instructions below for more information on silently installing Agent Controller.

Hardware prerequisites

  • Windows(R), Linux(R)/IA32: Intel(R) Pentium(R) II processor minimum. Pentium III 500 MHz or higher is recommended.
  • AIX(R): PowerPC(R) 604e 233MHz (IBM(R) RS/6000(R) 7043 43P Series) minimum
  • HP-UX: PA8500 300MHz (HP Workstation C3000) minimum
  • Solaris: UltraSPARC-IIi 300MHz (Sun Ultra 10 Workstation) minimum
  • OS/400(R): iSeries(TM) (as required by the operating system)
  • z/OS(R), LINUX/S39: zSeries(R) (as required by the operating system)
  • Linux/ppc64: POWER5(TM) processor based pSeries(R) and iSeries (as required by the operating system)
  • 512 MB RAM minimum (768 MB RAM is recommended)
  • Disk space:
    • You will require 170 MB minimum disk space for installing
  • Display resolution:
    • 800 x 600 display minimum (1024 x 768 recommended)

 

Supported platforms

Note for Linux: The 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 7.0.3.3 has been tested on the following platforms:

  • AIX v5.2, v5.3, and 5L on PowerPC (32-bit)
  • z/OS V1R4, V1R5, V1R6 and V1R7 on zSeries (32-bit)
  • OS/400 V5R2, V5R3 and V5R4 on iSeries
  • Linux 2.4 and 2.6 kernel. Examples of supported distributions include:
    • Red Hat Linux Advanced Server v2.1 on Intel IA32
    • Red Hat Enterprise Linux AS release 3 on PowerPC (64-bit)
    • Red Hat Enterprise Linux (RHEL) v3.0 and v4.0
    • SuSE Linux Enterprise Server (SLES) v9 on Intel IA32
    • SuSE Linux Enterprise Server (SLES) v8 on zSeries (32-bit)
  • Windows 2000 Server or Advanced Server (SP4) on Intel IA32
  • Windows 2000 Professional (SP3) on Intel IA32
  • Windows 2003 Server Standard and Enterprise (SP1) on Intel IA32
  • Windows 2003 Server Enterprise x64 Edition (SP1) on EM64T (64-bit)
  • Windows XP Professional (SP2) on Intel IA32
  • HP-UX v11.0, v11i on PA-RISC
  • Sun Solaris v8, v9, and v10.0 on SPARC

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

  • Connectiva Linux Enterprise Edition 1.0 on Intel IA32
  • Red Flag Advance Server v4.0, v4.1 on Intel IA32
  • SuSE Linux v7.0.3.3 on Intel IA32
  • SuSE Linux Desktop 9.0 on Intel IA32
  • SuSE Linux Standard Edition 9.0 on Intel IA32
  • SuSE Linux Enterprise Server (SLES) 9 on Intel IA32
  • TurboLinux Enterprise Server v8 on Intel IA32
  • United Linux v1.0 on Intel IA32
  • Windows NT(R) 4.0 (service pack 6a) on Intel IA32
  • Windows Server 2003, Standard Edition on Intel IA32
  • Windows Server 2003, Enterprise Edition on Intel IA32
  • Windows Server 2003, Datacenter Edition on Intel IA32

Supported JVMs

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

  • AIX: J2RE 1.4.1 IBM AIX build ca1411-20040301
  • AIX: J2RE 1.5.0 IBM AIX build pap32devifx-20060310 (SR1)
  • HP-UX: J2RE 1.4.2.03-040401-18:59-PA_RISC2.0
  • Linux for Intel IA32: J2RE 1.4.1 IBM build cxia321411-20040301; J2RE 1.4.2 IBM.
  • Linux for Intel IA32: J2RE 1.5.0 IBM Linux build pxi32dev-20060511 (SR2)
  • Linux for PPC64: J2RE 1.4.2 IBM build cxp64142-20040917 (JIT enabled: jitc)
  • Linux for PPC64: J2RE 1.5.0 IBM Linux build pxp64devifx-20060310 (SR1)
  • Linux for OS/390: J2RE 1.4.1 IBM build cx3901411-20040301
  • Linux for OS/390: J2RE 1.4.2 IBM build cx390142-20050609
  • z/OS: J2RE 1.4.1 IBM z/OS Persistent Reusable VM build cm1411-20030930
  • z/OS: J2RE 1.5.0 IBM z/OS build pmz31dev-20051104a
  • OS/400: J2RE 1.4 IBM
  • OS/400: J2RE 1.5 IBM
  • Solaris SPARC: Sun JavaTM 2 Standard Edition (build 1.4.2_04-b05)
  • Solaris SPARC: 1.5.0_06-b05
  • Windows: IA32 J2RE 1.4.1 IBM Windows 32 build cn1411-20040301a; J2RE 1.4.2 IBM Windows 32; Sun Java 2 Standard Edition (build 1.4.2_04-b05)
  • Windows_IA32: 1.5.0_04-b05,J2RE 1.5.0 IBM Windows 32 build pwi32dev-20051222
  • Windows_EM64T (64-bit): Sun Java 2 Runtime Environment, Standard Edition (build 1.5.0_06-b05) v1.5.0 06

Note:

Agent Controller 7.0.3.3 is bundled with IBM JRE 1.5 SP4 for Win_ia32, Win_em64T, Linux_ia32, Linux PPC, Solaris, OS390 AIX and IBM JRE 1.4 for HP-UX and Linux 390.   The IBM JRE will be installed under <install_dir>/jre where <install_dir> is the path you select as the installation root.  This JRE 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 Agent Controller.

Locating the installation files

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

  • For Linux on Intel IA32: <temp_dir>/linux_ia32
  • For Windows IA32: <temp_dir>\win_ia32
  • For Windows IPF: <temp_dir>\win_ipf
  • For Windows EM64T: <temp_dir>\win_em64tFor AIX: <temp_dir>/aix_powerpc
  • For HP-UX: <temp_dir>/hpux
  • For OS/400: <temp_dir>/os400
  • For Linux on z/Series: <temp_dir>/linux_s390
  • For Linux on Intel IA32: <temp_dir>/linux_ia32
  • For Linux on PPC64: <temp_dir>/linux_ppc64
  • For Solaris: <temp_dir>/solaris_sparc
  • For Windows on Intel IA32: <temp_dir>\win_ia32
  • For Windows on Intel Extended Memory 64 Technology (64-bit): <temp_dir>\win_em64t
  • For Windows on Intel Itanium systems (64-bit): <temp_dir>\win_ipf
  • For z/OS: <temp_dir>/os390

 

Agent Controller on Windows

Note:

Before installing Agent Controller version 7.0.3.3, you must uninstall the previous version of Agent Controller.

You can silently install Agent Controller version 7.0.3.3, and without first uninstalling Agent Controller version 6.0 (all releases) or Agent Controller version 6.1 (all releases), by using the parameter -P hyadesdc_product.patch=True. By using this method, your previous installation configuration gets migrated; all of the previous installation parameters are preserved. Use the following commands:

            setup.exe -silent -P hyadesdc_product.patch=True

Installing Agent Controller

  1. Log in as Administrator user.
  2. Change directory 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. Close all Eclipse platforms before continuing with the installation.
  5. Click Next on the welcome screen to proceed.
  6. Read the license agreement.
  7. Select I accept the terms in the license agreement and click Next to proceed.
  8. Specify the path where Agent Controller should be installed and click Next to proceed.
  9. Optional: Specify the version of IBM WebSphere Application Server.  If you don’t have IBM WebSphere Application Server installed, just leave the default select and click Next to proceed.
  10. Optional: Specify the paths of IBM WebSphere Application Server version 5.0 (Windows only) and 5.1 if "V5.0 or V5.1” was selected in step 9 above. Click Next to proceed.
  11. Specify which hosts can access Agent Controller. The choices are:
    1. This computer only allows only the local host to access Agent Controller.
    2. Specific computers allows a specified list of clients to access Agent Controller. If you select this option, and if Security was selected in step 9 above, click Next to proceed to the Access List panel. Type a comma-separated list of host names that can access Agent Controller.
    3. Any computer allows any client to access Agent Controller (Default selection).

Note:

If you use an authentication mechanism such as Lightweight Directory Access Protocol (LDAP), selecting "Any computer" will require that you disable the Agent Controller user authentication after the installation process is completed. Refer to the Agent Controller documentation for details.

12.  Click Next to proceed.

  1. Choose the security setting

Note:

If you selected "Any computer", then security is enabled by default (refer to "Enable" below). Communications will be encrypted and all connections will be authenticated. To disable security, refer to the Agent Controller documentation.

    1. Disable: Communication will not be encrypted and access control will be limited to the defined host list. (Default selection except for "Any computer".)
    2. Enable: Communication will be encrypted and all connections will be forced to authenticate for Secure Sockets Communications.

If Enable is selected, click Next and under Security type a comma-separated list of users that can connect to Agent Controller. These users will be required to authenticate to use the tool.

Click Next to proceed.

  1. Click Install on the summary screen to install Agent Controller.
  2. Click Finish after the installation has completed.

 

Uninstalling Agent Controller

  • Agent Controller can be removed from the Add/Remove Programs dialog under Control Panel.
  • To perform a silent uninstallation, run the command uninstall.exe -silent from the installation location's _uninst directory (for example, C:\Program Files\IBM\AgentController\_uninst).

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

Starting and stopping Agent Controller

  • On Windows, the Agent Controller system service (RAService.exe) will be started automatically.
  • Use the Windows Services dialog under Control Panel to start or stop the Agent Controller service (Start > Settings > Control Panel > Administrative Tools > Services>IBM Rational(R) Agent Controller).

 

Agent Controller on AIX, Solaris, HP-UX and Linux

Installing Agent Controller in console mode

Note:

Before installing Agent Controller version 7.0.3.3, you must uninstall the previous version of Agent Controller.

You can silently install Agent Controller version 7.0.3.3, and without first uninstalling Agent Controller version 6.0 (all releases) or Agent Controller version 6.1 (all releases), by using the parameter -P hyadesdc_product.patch=True. By using this method, your previous installation configuration gets migrated; all of the previous installation parameters are preserved. Use the following commands:

setup.bin -silent -P hyadesdc_product.patch=True

Refer to the instructions below for more information on silently installing Agent Controller.

On AIX, Solaris, HP-UX and Linux, it’s recommended that you install Agent Controller using console mode.   To do this

    1. Log in as root .
    2. Change directory to the directory where you unzipped the installation files for the appropriate platform.
    3. type command ‘./setup.bin –console’

Then you need to following the on-screen instruction to finish the installation.

Installing Agent Controller silently

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

 

Parameter

Description 

-silent

Optional: tells the installer to run silently otherwise you will get an install wizard with passed inputs. 

-P installLocation

Optional:  specifies the installation path. The default installation path is '$D(install)/IBM/AgentController'.

Examples:

for Windows: C:\Program Files\IBM\AgentController

for UNIX(R)/Linux: /opt/IBM/AgentController

 
-V licenseAccepted=true
 

Required


 

 
-V VAccessLocal
-V VAccessCustom
-V VAccessAll

Optional: specifies how clients can connect to Agent Controller (ALL, LOCAL, CUSTOM) Set only one of the variable "true". By default, VAccessLocal="true"

  • Any computer:           VAccessAll="true"           : allow any client
  • This computer only :   VAccessLocal="true"       : allow only localhost (default)
  • Specific computers :   VAccessCustom="true"    : allow a list of clients (also requires the -V VHosts parameter)
 
-V VHosts

Required if VAccessCustom="true""

specifies the client hostnames, separated by commas 

-V VSecurity

Optional: (true, false)

default: "false" 

-V VUsers

Required: if VSecurity="true"

specifies which users can connect to Agent Controller 

-V VWAS6
-V VWAS5

Optional:

-V VWAS6="true" (default) : If WAS V6 is used

-V VWAS5="true" : If WAS V5.x is used 

-V VWAS6
-V VWAS_HOME_V50
-V VWAS_HOME_V51

Optional: if -V VWAS5="true"

specifies the installed location of IBM WebSphere Application Server 5.1 and 5.0

Examples:

Installing from the command line:

setup.exe/setup.bin
  -silent
  -P installLocation="D:\IBM\AgentController"
  -V licenseAccepted=true
  -V VAccessCustom="true"
  -V VHosts="host1,host2"
  -V VSecurity="true"
  -V VUsers="user1,user2"
  -V VWAS5="true"
  -V VWAS_HOME_V51="D:\WebSphere5.1\AppServer"
  -V VWAS_HOME_V50="D:\WebSphere5.0\AppServer" 
 

Installing using a response file:

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

setup.exe/setup.bin -silent -options responsefile.txt

Contents of the response file:

      # Start of response file
 
           -P installLocation="D:\IBM\AgentController"
           -V licenseAccepted=true
           -V VAccessCustom="true"
           -V VHosts="host1,host2"
           -V VSecurity="true"
           -V VUsers="user1,user2"
           -V VWAS5="true"
           -V VWAS_HOME_V51="D:\WebSphere5.1\AppServer"
           -V VWAS_HOME_V50="D:\WebSphere5.0\AppServer"
 
      # End of response file

Starting and stopping Agent Controller

  • On non-Windows platforms, the Agent Controller process (RAServer) does not start automatically. You must start it yourself.
  • Important: The following environment settings for non-Windows platforms must be set before starting Agent Controller.
    • Linux, AIX, Solaris, HP-UX, z/OS: RAServer requires the directories of the JRE that contain executable libraries such as libjvm.so to be added to the library path environment variable. The table below shows the path variable setting for each platform, based on default installation locations of the JVMs supported for the platform.
    • Solaris: /usr/sbin must be added to the PATH environment before starting Agent Controller. Enter the following commands to set the path: 
      PATH=/usr/sbin:$PATH
      export PATH
    • AIX: For certain JVMs, the LDR_CNTRL environment variable needs to be set to USERREGS to work properly with the Agent Controller. To set this variable, run the following command before running the RAStart.sh script: 
export LDR_CNTRL=USERREGS

 

Note:

                   The path you enter must match the path for the JRE you will specify when you install Agent Controller. The JRE you specify will be used by                                        Agent Controller for launching Java applications.   Here are some examples using JVM 1.4.

 

Platform

Library path setting

AIX 

LIBPATH=/usr/java14/jre/bin:/usr/java14/jre/bin/classic:$LIBPATH
export LIBPATH
 

HP-UX 

SHLIB_PATH=/opt/java1.4/jre/lib/PA_RISC/server:/opt/java1.4/jre/lib/PA_RISC:$SHLIB_PATH
export SHLIB_PATH

Linux/IA32 

LD_LIBRARY_PATH=/opt/IBMJava2-141/jre/bin/classic:/opt/IBMJava2-141/jre/bin:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH

Linux/PPC64 

LD_LIBRARY_PATH=/opt/IBMJava2-ppc64-142/jre/bin:/opt/IBMJava2-ppc64-142/jre/bin/classic:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH

Linux/390 

LD_LIBRARY_PATH=/opt/IBMJava2-s390-141/jre/bin/classic:/opt/IBMJava2-s390-141/jre/bin:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH

Solaris 

LD_LIBRARY_PATH=/usr/j2sdk1.4.2_04/jre/lib/sparc/server:/usr/j2sdk1.4.2_04/jre/lib/sparc:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH

z/OS 

LIBPATH=/usr/lpp/java/IBM/J1.4/bin/classic:/usr/lpp/java/IBM/J1.4/bin:$LIBPATH
export LIBPATH
    • To start the Agent Controller process, change to the installation location's bin directory (for example, /opt/IBM/AgentController/bin) and run  ./RAStart.sh
    • To stop the Agent Controller process, change to the installation location's bin directory (for example, /opt/IBM/AgentController/bin) and run ./RAStop.sh
 

Uninstalling Agent Controller

  1. Run the program ‘uninstall.bin –console’ from the installation location's _uninst directory (for example, /opt/IBM/AgentController/_uninst).
  2. Follow the on-screen instruction to complete the uninstallation.

Or

1.                               To perform a silent uninstallation using the command uninstall.bin -silent.

When uninstalling RAC V6.x or V7.x on UNIX platforms, you will need to manually remove any residual files. To do this, stop the Agent Contoller, uninstall it, and clean up any of the following files which may be left behind after uninstalling:

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

 

Uninstalling Agent Controller that has multiple references on a workstation

Agent Controller version 7.0.3.3 prevents mutliple instances of the product from being installed on a single workstation. When additional installations are performed, either by stand-alone install or as an embedded install inside a product, Agent Controller records a reference to the name of the product that is initiating the new installation.

If Agent Controller has been installed multiple times - in other words, there are multiple reference counts - either by stand-alone install or as an embedded install inside a product, it can be uninstalled only when the last referencing product is uninstalled; the last referencing product still requires Agent Controller.

If you attempt to uninstall Agent Controller while it is still required by another product, the uninstallation will not proceed and you will receive a message "This product cannot be uninstalled as it is required by another product."

Agent Controller on OS/400 (iSeries)

Installing Agent Controller

If you have a previous version of Agent Controller, stop it and uninstall it before installing this version.

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.      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.

5.      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.

6.      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)

7.      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)

8.      Start QShell and create, on the integrated file system (IFS), the /opt/hyadesdc directory.

9.      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/*')

10.  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)

If you wish to install the National Language packs, complete steps 11 through 16 below. If not, proceed to step 17.

11.  On the iSeries host, in the HYADESDC library, create two empty save files called HYADESNL1.SAVF and HYADESNL2.SAVF: 

     CRTSAVF IBMRAC/HYADESNL1
     CRTSAVF IBMRAC/HYADESNL2

12.  Use FTP to add the NL files HYADESNL1.SAVF and HYADESNL2.SAVF from the installation CD to the library HYADESDC located on the iSeries host using BINARY mode transfer.

13.  On the iSeries host, in the IBMRAC library, create two empty save files called IBMRACNL1.SAVF and IBMRACNL1.SAVF: 

     CRTSAVF IBMRAC/IBMRACNL1
     CRTSAVF IBMRAC/IBMRACNL2

14.  Use FTP to add the NL files IBMRACNL1.SAVF and IBMRACNL2.SAVF from the installation CD to the library IBMRAC located on the iSeries host using BINARY mode transfer.

15.  Restore the save file HYADESNL1.SAVF and HYADESNL2.SAVF in HYADESDC to the IFS directory /opt/hyadesdc. For example, type the following commands on one line: 

     RST DEV('/QSYS.LIB/HYADESDC.LIB/HYADESNL1.FILE') OBJ ('/opt/hyadesdc/*') ALWOBJDIF(*ALL)
     RST DEV('/QSYS.LIB/HYADESDC.LIB/HYADESNL2.FILE') OBJ ('/opt/hyadesdc/*') ALWOBJDIF(*ALL)

16.  Restore the save file IBMRACNL1.SAVF and IBMRACNL2.SAVF in IBMRAC to the IFS directory /opt/hyadesdc. For example, type the following commands on one line: 

     RST DEV('/QSYS.LIB/IBMRAC.LIB/IBMRACNL1.FILE') OBJ('/opt/hyadesdc/*') ALWOBJDIF(*ALL)
     RST DEV('/QSYS.LIB/IBMRAC.LIB/IBMRACNL2.FILE') OBJ('/opt/hyadesdc/*') ALWOBJDIF(*ALL)

17.  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

18.  Follow the on-screen prompt to configure Agent Controller.

Starting and stopping Agent Controller

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)

or, change the directory to the installed location's bin directory /opt/hyades/bin, and run the stop script: 

./RAStop.sh

Uninstalling Agent Controller

1.      Remove the HYADESDC and IBMRAC library.

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

Agent Controller on z/OS (OS/390)

Installing Agent Controller

If you have a previous version of Agent Controller, stop it and uninstall it before installing this version.

1.    Log in as Root.  In a UNIX 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, tptpdc.os390.pax to the installation directory.

3.    Issue the following command to extract Agent Controller files:

                         pax -ppx -rvf ibmrac.os390.pax

4.    Issue the following command to extract the test and performance tools (TPTP) Agent Controller files:

                         pax -ppx -rvf tptpdc.os390.pax

5.    Change the directory to the installation bin directory /bin, and run the script to create links to the Agent Controller libraries by typing: 

            ./createLinks.sh

6.    Make the Agent Controller shared object files program controlled by issuing the following commands in a UNIX System Services shell:

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

If you wish to install the National Language packs, complete steps 7 and 8 below. If not, proceed to step 9.

7.    Transfer the NL install images tptpdc.nl1.os390.pax, tptpdc.nl2.os390.pax, ibmrac.os390.nl1.pax, ibmrac.os390.nl2.pax to the installation directory.

8.    Issue the following command to extract Agent Controller files: 

     pax -ppx -rf tptpdc.nl1.os390.pax
     pax -ppx -rf tptpdc.nl2.os390.pax
     pax -ppx -rf ibmrac.os390.nl1.pax
     pax -ppx -rf ibmrac.os390.nl2.pax

9.    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

10.Follow the on-screen prompt to configure 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 MVSTM Initialization and Tuning Reference.

Starting and stopping Agent Controller

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

·         Start the server by logging in as root, opening the /usr/lpp/IBM/AgentController/bin directory and issuing the command: 

     ./RAStart.sh

·         To stop the server, log in as root, open the /usr/lpp/IBM/AgentController/bin directory, and issue the command: 

     ./RAStop.sh

Uninstalling Agent Controller on the

·         If you ran createLinks.sh when installing Agent Controller, then go to the /usr/lpp/IBM/AgentController/bin directory and issue the command: 

     ./removeLinks.sh

·         Remove the IBMRAC directory and all of its subdirectories by issuing the following command: 

     rm -rf /usr/lpp/IBM/AgentController

 

Using the Agent Controller security feature

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 will be allowed to authenticate. If the user name ANY is provided, any valid user name and password pairs will be forwarded to the operation system for authentication, otherwise only listed pairs will be forwarded.

·                When security is enabled, the users you 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.

·                (Windows only) Domain name passwords will not be authenticated. You must provide local user name and password pairs.

·                There are no key management capabilities provided. Agent Controller uses Java keystores for security.

·                A default keystore and exported certificate are in the Agent Controller directory <rac_install_dir>\security for Windows, and <rac_install_dir>/security for Linux. Where <rac_install_dir> is the installation directory of Agent Controller.These are samples only. You should replace these with a keystore containing meaningful certificates.

·                 

Compatibility

In Agent Controller 6.0.0.1 (and earlier), communication between the workbench and Agent Controller was conducted through two channels:

  • a bidirectional control channel for carrying commands back and forth between the workbench and Agent Controller
  • a unidirectional data channel for carrying data collected by agents back to the workbench

Only the former of these, the control channel, could be encrypted by turning on the security feature. Information on the data channel was always unencrypted. Also, only the control channel could negotiate firewalls between the workbench and Agent Controller.

In version 6.0.1, Agent Controller introduces the notion of multiplex mode, in which data collected from agents can be communicated back to the workbench along the control channel, which can be optionally encrypted and can negotiate firewalls.

This raises some compatibility matters: Can you use an earlier workbench (specifically version 6.0.0.1) with a newer Agent Controller (version 6.0.1 or later)? In general the answer is ‘Yes’, but not if you want to take advantage of the multiplexing features in version 6.0.1 or later. That is, if you want to use the multiplex mode so that the channel that your data is using is encrypted and can negotiate firewalls, then you must also upgrade the workbench to version 6.0.1 or later.

Workbench/Agent Controller compatibility summary

Backward compatibility (using an older workbench with a version 6.0.1 Agent Controller): Yes, they are compatible, in that the new Agent Controller supports all the features in previous versions (for example, Security on the control channel). However, you will not be able to use new features, including multiplexing (returning data via the control channel so that it can be secure).

Forward compatibility (using a 6.0.1 or later workbench with an older Agent Controller): No, in general, is not supported.

Cross-version Inter-Agent-Controller compatibility: Some products or tools (such as IBM Performance Optimization Toolkit) require that Agent Controllers on multiple hosts (apart from the workbench) "discover" and communicate with each other. Changes made from one version to the next surrounding this function mean that if you need to use this function, you must use either Agent Controller version 6.0.0.1  or Agent Controller version 6.0.1 or later on all involved hosts. That is, you cannot mix and match versions when using dynamic discovery between Agent Controller instances.

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:

  • If port 10002 is being used by another process, you can change the port number by editing the serviceconfig.xml file. This is described in the documentation.

Note:

If the communication port number that is configured in the serviceconfig.xml file has been changed, then the property INSTANCE_RAC_PORT_NUM_ID that is defined in the WebSphere Application Server configuration needs to be changed to the same port number.

  • If Agent Controller was just stopped, wait a few minutes and try to start it again.

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 Eclipse workbench.
  2. Terminate all java.exe processes that contain either the Java Profiling Agent or the J2EE Request Profiler.

Notices and trademarks

Notices

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 document 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 document. The furnishing of this document does not grant 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-0032, 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 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:

IBM Corporation
U59/600
3600 Steeles Ave East,
Markham, ON; L3R 9Z7
Canada

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 document 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.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate 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.

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

(C) (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. (C) Copyright IBM Corp. 2007. 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 the IBM Corporation in the United States or other countries or both:

  • AIX
  • CICS
  • ClearCase
  • ClearQuest
  • Cloudscape
  • DB2
  • DB2 Universal Database
  • DRDA
  • HACMP
  • IBM
  • Informix
  • iSeries
  • MVS
  • OS/390
  • OS/400
  • POWER5
  • PowerPC
  • pSeries
  • Rational
  • RS/6000
  • Tivoli
  • Tivoli Enterprise
  • TotalStorage
  • TXSeries
  • WebSphere
  • xSeries
  • z/OS
  • zSeries

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.

Intel, Intel Xeon, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Linux is a registered 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.

 

(C) Copyright IBM Corporation 2000, 2007. All Rights Reserved.