Before using this information and the product it supports, read
the information in Notices.
Copyright International Business Machines Corporation 2000, 2012. US Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Rational® Agent Controller
is a daemon process that enables client applications to launch and
manage local or remote applications, and enables clients to receive
application data from agents within host processes and 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.
Component testing tool to run test cases. Agent Controller must
be installed on the systems on which you run the test cases.
Tools for enabling Java code
coverage statistic collection on remote WebSphere® Application Server.
Tools for remote profiling on the following versions of WebSphere Application Server:
You should install Agent Controller behind a firewall.
For 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.
Compatibility of this version of Agent Controller with other
versions
Compatibility with earlier versions: The new Agent Controller
supports all the features in previous versions, and no new changes
have been introduced that would break compatibility with existing
agent controller versions. However, you will not be able to use new
features if the agent that implements that feature has not been packaged
with the older agent controller version (for example, attempting to
profile Java 6.0 or later JVMs,
with an agent controller that has not been bundled with the Java 6.0 profiler).
Forward compatibility: In general, this is supported, with
the same caveat as above, that some older functionality may have been
removed from new Agent Controller versions.
Hardware and software requirements for z/OS
This topic lists the hardware and software requirements for installing Rational Agent Controller,
version 8.3.5.
Supported platforms
Agent Controller 8.3.5 is supported on the following platforms:
Table 1. Platform support for Rational Agent Controller V8.3.5
Operating system
Processor architecture
z/OS®,
Version 1.12
s/390 (31-bit or 64-bit)
z/OS,
Version 1.11
s/390 (31-bit or 64-bit)
z/OS,
Version 1.10
s/390 (31-bit or 64-bit)
z/OS,
Version 1.9
s/390 (31-bit or 64-bit)
Note:
The bit version of Rational Agent Controller must be the same
as the bit version of WebSphere Application Server on which it will
be profiling.
31-bit versions of Rational Agent Controller can
run on 64-bit operating systems that are running in a mode that supports
31-bit applications. In this situation, the server instance on WebSphere
Application Server must also be running in 31-bit mode. To change
the server to 31-bit mode:
Start the server. The server tells you what mode it is in when
it starts.
When you install Agent Controller, a runtime environment for Java technology is installed.
In general, Agent Controller works with Java virtual machine version 1.5 and later.
For profiling application running on Java virtual
machine 1.4, use Rational Agent
Controller version 7.x.
Installing and uninstalling Agent Controller on 31-bit z/OS
You can install Rational Agent
Controller on 31-bit z/OS
Before you begin
If you have an earlier version of Rational Agent Controller installed on your
computer, uninstall it before installing this version.
Procedure
To install Rational Agent
Controller on 31-bit z/OS operating
system:
In a UNIX System
Services shell, change to the directory where you downloaded the installation
files for Rational Agent
Controller.
Extract the contents of the compressed file that you downloaded
by entering the following command:unzip rac.zos.31bit.zip
The contents of the compressed file are extracted
into a new subdirectory of the current directory named RACzOS31bit.
Change to the RACzOS31bit subdirectory.
Extract the contents of the file rac.zos.31bit.pax by
entering the following command: pax -r -f rac.zos.31bit.pax
-pp
Change to the jre subdirectory of
the RACzOS31bit directory.
Extract the contents of the file rac.jre.31bit.pax by
entering the following command: pax -r -f rac.jre.31bit.pax
-pp
Enter the following commands to set the environment variables
for Rational Agent Controller.
In the commands that follow, <Rational Agent Controller
directory> is the directory that you used to extract the
contents of the installation files.
Change to the <Rational Agent Controller
directory>/RACzOS31bit/bin directory.
Run the following command: ./SetConfig.sh.
The configuration program for Rational Agent
Controller starts. At the prompts, you can either press Enter to accept
the default value shown, or you can enter a different value.
Tip:
In most cases, you must change the value of Network access
mode to ALL or CUSTOM (along with the list of clients) so that remote
client computers can communicate with Rational Agent Controller.
The prompts
are:
Specify the fully qualified path of "java" (e.g. /usr/java1.4/jre/bin/java):
This prompt lists the JRE used by Rational Agent
Controller. The default value is the JRE supplied with Rational Agent Controller (/<Rational
Agent Controller directory>/RACzOS31bit/jre/J6.0/bin/java).
If you want to use a different JRE, enter the path to its java file.
Network access mode (ALL=allow any host, LOCAL=allow
only this host, CUSTOM=list of hosts): This prompt lists
the hosts that are allowed to access Rational Agent Controller. Enter one of
the following options:
ALL allows any client to access Agent Controller.
LOCAL (the default selection) allows only the
local host to access Agent Controller.
CUSTOM allows only a list of clients that you
specify to access Agent Controller. Use a comma-separated list of
host names to specify which computers can access Agent Controller.
Security enabled. (true/false):
The default value is false. Communication
is not be encrypted and access control is limited to the defined host
list.
If you enter true, then communication is
encrypted and all connections are forced to authenticate for Secure
Sockets Communications. You can type a comma-separated list of users
that can connect to Agent Controller. These users are required to
authenticate to use the tool.
If you enabled security in the previous step, then enter
the following commands:
To uninstall Rational Agent Controller, delete the directory
where you extracted the Rational Agent
Controller installation files.
Installing and uninstalling Agent Controller on 64-bit z/OS
You can install Rational Agent
Controller on 64-bit z/OS
Before you begin
If you have an earlier version of Rational Agent Controller installed on your
computer, uninstall it before installing this version.
Procedure
To install Rational Agent
Controller on 64-bit z/OS operating
system:
In a UNIX System
Services shell, change to the directory where you downloaded the installation
files for Rational Agent
Controller.
Extract the contents of the compressed file that you downloaded
by entering the following command:unzip rac.zos.64bit.zip
The contents of the compressed file are extracted
into a new subdirectory of the current directory named RACzOS64bit.
Change to the RACzOS64bit subdirectory.
Extract the contents of the file rac.zos.64bit.pax by
entering the following command: pax -r -f rac.zos.64bit.pax
-pp
Change to the jre subdirectory of
the RACzOS64bit directory.
Extract the contents of the file rac.jre.64bit.pax by
entering the following command: pax -r -f rac.jre.64bit.pax
-pp
Enter the following commands to set the environment variables
for Rational Agent Controller.
In the commands that follow, <Rational Agent Controller
directory> is the directory that you used to extract the
contents of the installation files.
Change to the <Rational Agent Controller
directory>/RACzOS64bit/bin directory.
Run the following command: ./SetConfig.sh.
The configuration program for Rational Agent
Controller starts. At the prompts, you can either press Enter to accept
the default value shown, or you can enter a different value.
Tip:
In most cases, you must change the value of Network access
mode to ALL or CUSTOM (along with the list of clients) so that remote
client computers can communicate with Rational Agent Controller.
The prompts
are:
Specify the fully qualified path of "java" (e.g. /usr/java1.4/jre/bin/java):
This prompt lists the JRE used by Rational Agent
Controller. The default value is the JRE supplied with Rational Agent Controller (/<Rational
Agent Controller directory>/RACzOS64bit/jre/J6.0/bin/java).
If you want to use a different JRE, enter the path to its java file.
Network access mode (ALL=allow any host, LOCAL=allow
only this host, CUSTOM=list of hosts): This prompt lists
the hosts that are allowed to access Rational Agent Controller. Enter one of
the following options:
ALL allows any client to access Agent Controller.
LOCAL (the default selection) allows only the
local host to access Agent Controller.
CUSTOM allows only a list of clients that you
specify to access Agent Controller. Use a comma-separated list of
host names to specify which computer can access Agent Controller.
Security enabled. (true/false):
The default value is false. Communication
is not encrypted and access control is limited to the defined host
list.
If you enter true, then communication is
encrypted and all connections are forced to authenticate for Secure
Sockets Communications. You can type a comma-separated list of users
that can connect to Agent Controller. These users are required to
authenticate to use the tool.
If you enabled security in the previous step, then enter
the following commands:
To uninstall Rational Agent Controller, delete the directory
where you extracted the Rational Agent
Controller installation files.
Setting the runtime environment to use with Agent Controller
on z/OS
Rational Agent
Controller is bundled with a runtime environment for Java technology. The supplied runtime environment
is installed in the <Rational Agent Controller
directory>/RACzOS64bit/jre
About this task
Agent Controller is bundled with a runtime environment
for Java technology.
In
general, Rational Agent
Controller works with Java virtual
machine version 1.5 and above.
If you want to change run runtime
environment used by Rational Agent
Controller, run the configuration program for Rational Agent Controller.
Procedure
In a UNIX System
Services shell, change to the <Rational Agent
Controller directory>/RACzOS64bit/bin directory.
Run the following command: ./SetConfig.sh.
The configuration program for Rational Agent
Controller starts.
The Specify the fully qualified path of "java"
(e.g. /usr/java1.4/jre/bin/java) prompt lists the runtime
environment for Java technology
used by Rational Agent
Controller. The default value is the runtime environment for Java technology supplied with Rational Agent Controller (For
64-bit: /<Rational Agent Controller directory>/RACzOS64bit/jre/J6.0/bin/java.
For 31-bit: /<Rational Agent Controller directory>/RACzOS31bit/jre/J6.0/bin/java).
If you want to use a different runtime environment, enter the path
to its java file.
To complete
the configuration program, see the installation instructions.
What to do next
You can use the runtime environment that you specify to run
Agent Controller, and this runtime environment is used by Agent Controller
to launch Java applications.
You can, however, configure Agent Controller to a use separate runtime
environment for Java technology
for each of these functions. For details, see the Agent Controller
help topic "Configuring Applications to be launched by Rational Agent Controller."
Setting the file permissions for profiling on z/OS
If you are profiling on z/OS,
then you must have read and execute permissions on the following directories
(and all directories in their path):
If you are profiling on z/OS,
then you must have read and execute permissions on the following directories
(and all directories in their path):
All directories in the path to these directories also must
have read and execute permission. For example, if <Rational
Agent Controller installation directory> is /opt/IBM/RAC,
then you need read and execute permissions on each of the /opt, /opt/IBM, /opt/IBM/RAC and /opt/IBM/RAC/lib/ directories.
You can provide the correct permissions by running the command
umask 022 when you start Rational Agent
Controller.
Starting and stopping Agent Controller on z/OS
You must start and stop Rational Agent Controller in a UNIX System Services shell.
To start Rational Agent
Controller on 31-bit z/OS:
In a UNIX System Services
shell, change to the <Rational Agent Controller
directory>/RACzOS31bit/bin directory.
Run the following commands:
umask 022
./ACStart.sh
To start Rational Agent
Controller on 64-bit z/OS:
In a UNIX System Services
shell, change to the <Rational Agent Controller
directory>/RACzOS64bit/bin directory.
Run the following commands:
umask 022
./ACStart.sh
To stop Rational Agent
Controller on 31-bit z/OS:
In a UNIX System Services
shell, change to the <Rational Agent Controller
directory>/RACzOS31bit/bin directory.
Run the following command: ./ACStop.sh.
To stop Rational Agent
Controller on 64-bit z/OS:
In a UNIX System Services
shell, change to the <Rational Agent Controller
directory>/RACzOS64bit/bin directory.
Run the following command: ./ACStop.sh.
Note:
In Agent Controller might fail to start if TCP/IP port 10002
is not free.
If the port is not free, the following error message
displays:
RAServer failed to start.
Agent Controller listens on TCP/IP port 10002 by
default. The port might be in use by process, or if Agent Controller
was stopped and then restarted in rapid succession, the port might
not be released before Agent Controller restarts/
To start Agent
Controller after it fails to start:
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.
Working with 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 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 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 are not 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,
where <rac_install_dir> is the installation
directory of Agent Controller. Replace these samples with a keystore
containing meaningful certificates.
Additional security configuration for z/OS
If security is enabled in the
agent controller configuration, then BPX.DAEMON privileges are required
for the agent controller. Speak with your system administrator to ensure
that the Agent Controller binaries and libraries have the appropriate
privileges. The following set of files typically require program-control
privileges in order to allow security to run. (extattr +p)
<RAC_INSTALL_DIR>/bin/ACServer
<RAC_INSTALL_DIR>/bin/tptpProcessController (all
files, including libTPTPUtil and libtptpCCTL)
<JAVA_INSTALL_DIR>/jre/J6.0/bin/classic/* (all
files in this directory)
<JAVA_INSTALL_DIR>/jre/J6.0/lib/* (or,
more generally, the lib directory of the JVM specified in the serviceconfig.xml
file)
<JAVA_INSTALL_DIR>/jre/J6.0/lib/s390/j9vm/* (where
s390 is either s390 or 390x, for 31or 64 bit.)
<JAVA_INSTALL_DIR>/jre/J6.0/lib/s390/* (where
s390 is either s390 or 390x, for 31 or 64 bit.)
<JAVA_INSTALL_DIR>/jre/J6.0/lib/s390/default/* (where
s390 is either s390 or 390x, for 31 or 64 bit.)
If you do not set this configuration, then you will get messages
in the z/OS log similar to
the following example when the user ID and password is entered in
the workbench when it performs "Attach to Agent" in the Profiling
and Logging Perspective: BPXP015I HFS PROGRAM /opt/racv822/bin/ACServer
IS NOT MARKED PROGRAM CONTROLLED. BPXP014I ENVIRONMENT MUST BE CONTROLLED
FOR DAEMON (BPX.DAEMON) PROCESSING.
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:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 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.
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.
All
statements regarding IBM's future direction or intent are subject to change
or withdrawal without notice, and represent goals and objectives only.
Trademarks
and service marks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at www.ibm.com/legal/copytrade.html