r1 - 2015-03-10 - 21:38:58 - GeraldMitchellYou are here: TWiki >  Deployment Web > DeploymentMonitoring > CLMServerMonitoring > CLMServerMonitoringAgent > CLMServerMonitoringCSMAgentSetupWAS

CLM Server Monitoring Agent Setup for WebSphere installation todo.png

Authors: GeraldMitchell
Build basis: CLM 4.0.6 or higher, CSM Agent 5.0.1 or higher


Designed to monitor Collaborative Lifecycle Management deployments, the CLM Server Monitoring (CSM) Agent provides reports and visualizations to identify key problem areas related to product user activity and resource bottlenecks identified by the CLM Server Monitoring plug-in This page is specifically for the setup of
  • CLM Server Monitoring Agent 5.0.1 or higher
  • Being installed on a WebSphere Application Server profile that does NOT include the CLM to be monitored
  • Monitoring CLM applications at version 4.0.6 or higher , running on WebSphere Application Server profiles


  • CLM Server to be monitored
    • Jazz Team Server, Rational Team Concert, Rational Quality Management from CLM 4.0.6 or higher Installation
    • WebSphere Application Server or Apache Tomcat
        • NOTE: Support for application server information during monitoring is not supported for Tomcat at this time. Tomcat must use the IBM JDK; the Oracle JDK is not currently supported for Tomcat.
        • Follow instructions for JMX for WAS: To enable JMX on WebSphere
        • Follow instructions for unsecured JMX for Apache Tomcat: To enable JMX on Tomcat
    • For Rational DOORS Next Generation support, CLM must be at least version 5.0.1
    • See the CLM version specific documentation for other CLM and application-related requirements
    • The CLM Server to be monitored must be started, setup, and running with the plugin enabled to connect CLM Server Monitoring Agent to the CLM server. * CLM Server Monitoring Agent
    • x86-64 hardware
    • Windows or Linux, 64-bit operating system
    • LAN connection to the CLM instance to be monitored
    • All Sizing requirements are similar to the CLM 5.0.2 JTS application.

Installation instructions

  • CLM Server Monitoring Agent is installed through the Installation Manager using the launch pad under custom installation for CLM 5.0.1 and above.

  • WARNING: The CLM Server Monitoring Agent is not recommended to be installed in the same Java Virtual Machine as any CLM application(s). This means that it should not be installed in the same application server instance.
    • Do NOT install the CLM Server Monitoring Agent into the CLM embedded Tomcat instance.
    • Do NOT install CLM Server Monitoring Agent into the same WebSphere application server cell as the CLM instance.
    • CLM and CSM Agent can run on the same machine. but should not be in the same application server JVM instance. CSM Agent deployment location should be considered carefully for production deployments, as they will use the same memory, disk storage, and processing power and the CLM Server Monitoring Agent would then affect CLM performance as reflected in the CSM Agent.
    • CSM Agent does JVM monitoring and would itself affect the results, affecting performance like memory and processing usage conflicts, causing javacores to have additional impacts, disk space contention, and other possible side effects.

Initial Configuration of CLM WebSphere

It is assumed herein that the CLM!WebSphere is

For each application server instance that is supporting a CLM application, the following steps need to be applied:

Initial Configuration of CSM Agent on WebSphere Application Server

Installation setup for CSM Agent on WebSphere Application Server to a CLM on a WebSphere Application Server

Follow the instructions for Install the CSM Agent application on WebSphere. The war for CSM is csm.war and context is /csm

Installation setup for the WebSphere Application Server to host the CSM Agent

The following steps are listed for convenience. Please follow instructions in the KnowledgeCenter of the CLM version you are installing for latest instructions.

Initial State: WebSphere® Application Server is already installed. On Unix systems, ensure that the Open File Limit value is properly set. For more information, see Planning to install on UNIX and Linux systems. The database is created. If you use the default Derby database for evaluation purposes, ensure the location to the database in the teamserver.properties file is an absolute path.


  1. Go to {!JazzInstallDir}/server/conf/app where JazzInstallDir is where you installed CSM Agent and app is a directory for csm.
  2. Open teamserver.properties for editing.
  3. Locate the Derby database location com.ibm.team.repository.db.jdbc.location=conf/csm/derby/repositoryDB, and change the location with an absolute path. For example, com.ibm.team.repository.db.jdbc.location=C:/Progra~1/IBM/JazzTeamServer/server/conf/jts/derby/repositoryDB.
  4. The Java™ 2 Security option must be turned off. If this option is turned on in WebSphere Application Server, the web application will not start.
    1. In WebSphere Integrated Solutions Console, click Security > Global security.
    2. Under Java 2 security, clear the check box for Use Java 2 security to restrict application access to local resources.
    3. Ensure that the Enable administrative security and Enable application security check boxes are selected.
  5. Ensure that the Use available authentication data when an unprotected URI is accessed application server security setting is selected. If you are using the Integrated Solutions Console for the server, use the following steps to verify this setting:
    1. In WebSphere Integrated Solutions Console, click Security > Global security > Web and SIP security > General settings.
    2. Click the Use available authentication data when an unprotected URI is accessed check box.
    3. Click OK and Save directly to the master configuration.
  6. To ensure that the LTPA cookies are secure, enable the Requires SSL setting:
    1. In WebSphere Integrated Solutions Console, click Security > Global security > Web and SIP security > Single sign-on (SSO).
    2. Click the Requires SSL check box.
    3. Click OK and Save directly to the master configuration.
  7. Add the following session management custom property to avoid SESN0008E error message when a user logs out without terminating the session:
    1. In WebSphere Integrated Solutions Console, click Servers > Server Types > WebSphere application servers.
    2. Click the appropriate server (for instance "server1") and then in the Container Settings section, click Session management.
    3. In the Additional Properties section, click Custom properties.
    4. Click New and enter the following information: Name: InvalidateOnUnauthorizedSessionRequestException Value: true
    5. Click Apply and save directly to the master configuration. 1. To improve performance of the operating procedures, change the WebContainer thread pool size settings:
    6. In WebSphere Integrated Solutions Console, click Servers > Server Types > WebSphere application servers.
    7. Click server1 and then in the Additional Properties section, click Thread pools.
    8. In the Thread pools page, click WebContainers.
    9. Enter 200 in the Minimum Size and Maximum Size fields.
    10. Click OK and save directly to the master configuration.

Installation setup for CSM Agent application on WebSphere Application Server

The following steps are listed for convenience. Please follow instructions in the KnowledgeCenter of the CLM Server Monitoring Agent version you are installing for latest instructions.

  1. Open the Admin console for the WebSphere Application Server.
  2. Click Applications > New Application > New Enterprise Application.
  3. Under Path to the new application, select Remote file system.
  4. Under Full path enter the path to the csm.war web application file: If you installed Apache Tomcat with IBM® Installation Manager, the directory that contains the web applications is:


If you did not install Apache Tomcat with IBM Installation Manager, the directory that contains the web applications is the one that you defined during installation. The default directory is:


  1. Click Next to accept all default options until you reach the Map context roots for web modules page.
  2. In the Map context roots for web modules, set Context Root to /csm, and click Next.
  3. Click Finish.
  4. Verify that the jts_war application was installed correctly and click Save directly to the master configuration.
  5. Map security roles to a user or repository group:
    1. Go to Applications > Application Types > WebSphere enterprise applications.
    2. Click the csm_war application, and open it for editing.
    3. In the Detail properties section, click Security role to user/group mapping.
    4. Select a specific repository group, such as JazzAdmins or JazzUsers, and click Map groups. These repository groups are associated with every Jazz™ implementation and must be mapped to a particular group that contains the authorized users. If you are using LDAP, these groups must be set up on the LDAP server prior to completing this mapping. If you are mapping these repository groups to individual users, select the repository group and click Map Users.
    5. Enter a search string to return your group names from the LDAP server. Click Search to run the query.
    6. From the list of available groups that is returned, select the particular group and move it to the Selected column.
    7. Click OK to map the LDAP groups to the Jazz repository groups.
    8. Map the appropriate LDAP group for all Jazz repository groups: JazzAdmins JazzProjectAdmins JazzDWAdmins JazzUsers JazzGuests Note: Do not enable the All authenticated? option. 1. Save the changes. Note: If in the future there will be changes to the LDAP configuration level, you must remap the security roles to the user or repository group for the CSM application.
  6. Click Applications > Application Types > WebSphere enterprise applications.
  7. Select the check box next to csm_war; click Start. A green arrow should appear indicates that the application started.

If connecting CSM Agent to a CLM application hosted on a different WebSphere Application Server

In addition this further step are required if the WebSphere Application server hosting CSM is not in the same realm as the CLM applications they are monitoring (default for stand alone, non-ND WAS)
  1. In the WebSphere Integrated Solutions console to Global Security-> Java Authentication and Authorization Service ->Application logins
  2. Click on WSLogin
  3. Click on com.ibm.ws.security.common.auth.module.WSLoginModuleImpl
  4. Ensure that "Use login module proxy" is set and that use_realm_callback and use_appcontext_callback are set to true
  5. You will also need to import the CLM Application Server's certificate into the node default trust store. To do this go to the WebSphere Integrated Solutions Console and navigate to Security->SSL certificate and key management->Key stores and certificates->NodeDefaultTrustStore and click the "Retrieve from port" button. In the dialog that follows specify the https port of the CLM application we will be monitoring to retrieve the certificate (ex. 9443). You can enter something recognizable as "alias".

CLM Server Monitoring Agent instructions

  1. Start the CSM agent Application Server and application.
    • Make sure the application server is started and that the CSM application is started using the WebSphere Administration Console.
  2. Run the setup by using the public URL of CLM Server Monitoring. Example: https://<hostname.domain>:9443/csm/setup
    • Follow the instructions

CLM Server Monitoring Agent Configuration instructions

CLM Server Monitoring Agent 5.0.1, and higher first steps

Adding CLM Friends (5.0 and higher)

In order for the CSM agent to be able to collect javacores and other artifacts that are a result of plug-in actions, the CSM Agent needs to log into the Application and fetch this information securely. To simplify this operation, a friend relationship needs to be established between the applications being monitored and the CSM agent. To do this we add the applications being monitored as friends, and in the case where no SSO is enabled identify a user in the CLM application who will act on behalf of the CSM agent.
  1. Go to the CSM Administration page at /admin and click "Friends (Outbound)" in the left hand menu. Then click the "Add..." link on the right.
  2. In the Add Friend dialog add the information as it applies the friend server you are adding:
    • Name: Any recognizable name
    • Root Services URI: /rootservices
    • OAuth secret: A secret/password used for this trust relationship (any value)
    • Re-type secret: Retype above entry
    • Trusted: Set to true
  3. Click "Create Friend"
    On successful completion the following message will appear then click next.
  4. Authorize the provisional key. Click "Grant access for the provisional key". You may be asked to log into the CLM application at this point in order to grant access.
  5. Approve the request when asked. The "Consumer Name" is what the CSM server will be recognized as in the consumer list.
  6. Once finished the friend will be added to Friends List:

If SSO is not enabled between CSM and the CLM applications (most likely true)

  1. Login into the application friend we just added through and navigate to the administration interface at /admin. Go to "Consumers (Inbound)". The CSM server consumer we just added should be listed there. We want to add the user that the consumer (CSM) will use locally to fetch the Java cores. This user must be a Jazz Admin. Click the pencil beside the CSM consumer.
  2. Edit Consumer Key Properties and add the Jazz Admin user be selecting "Select User..."
    Selection_551.png The functional user should now be set:
    and the consumer user added to the consumer list entry on the consumer page.

Configuring the WAIT reporting tool

When Java cores are fetched several properties need to be specified in order for the Java cores to be uploaded to WAIT once the activity is complete. These properties can be specified in the /admin advanced properties page.
  • WAIT Server: The WAIT server to use for uploading the reports
  • WAIT Server Email: The email address used by the WAIT Server for generating the reports
  • WAIT Server User: Specified if the WAIT server is protected by a username
  • WAIT Server Password: Specified if the WAIT server is protected by a username

CLM Server Monitoring project creation

  1. Users can be created and assigned "CLM Server Monitoring - User (Early Access)" CALs. Ten licenses are included in the preview.
  2. Go to https://<hostname.domain>:9443/csm/admin#action=com.ibm.team.process.manageProjectAreas and click "Create a Project Area" called "CLM Server Monitoring."
    • You will need to deploy the process templates to get the CLM Server Monitoring template.
    • At a minimum, you will need to add a Jazz Admin user to the project (for JMX Connection User) along with any other users who you want to have access.
  3. Click "Save."
  4. Assign the "Team Member" role to any users assigned to the project.
  5. Click "Save."

CLM Server Monitoring JMX connection setup

Depending on the application server you want to monitor, follow the instructions in the !WebSphere Application Server or the Tomcat section. (Where the CLM applications are installed).
  1. Go to https://<hostname.domain>:9443/csm/web/projects/CLM%20Server%20Monitoring#action=com.ibm.team.dashboard.viewDashboard to access the project you created.
  2. Select JMX Connections -> Create-> Create Connection.
Connecting to WebSphere (JVM)
  1. Complete the connection information:
    • The connection ID: This must be a unique string or number. You cannot have two connections with the same ID.
    • The connection Name: This is optional but can help you find your connection in a list.
    • The connection Type: Choose !WebSphere because the application you are trying to monitor is deployed to WebSphere Application Server.
    • Select the Jazz user that will be used to create problem records. The user must be assigned a CSM User CAL and be a Jazz Admin user
    • Select the Secure Connection check box if the JMX server on your application only accepts secure connections. If you select this check box, you also need to complete the User Name and Password fields. This is the WebSphere Application Server admin user name and password. The Realm field is the authentication realm of the CLM application's application server. This can be found on the CLM application server WebSphere Integrated Solutions console in Global Security->Realm name. You can also find this value from JConsole login window (the first field).
    • Enter the Host Name and Port: This is the host name of the server to monitor and the port used by the JMX server. Use the value used for HOST and PORT from the JConsole script.
    • Use JSR160RMI (, RMI or SOAP) as the protocol. Ensure that whatever protocol is used, that the connector is enabled on the CLM application server's connector configuration as specified in To enable JMX on WebSphere
  2. Click "Save".

CLM Server Monitoring connection activation

To successfully activate a connection, you must first ensure that CLM Server Monitoring is enabled on the server that you want to monitor. See Jazz monitoring through JMX for details on how to enable JMX monitoring. To activate a connection, perform the following steps.
  1. Go to https://<hostname.domain>:9443/csm/web/projects/CLM%20Server%20Monitoring#action=com.ibm.team.server.monitoring.agent.jmx.viewConnections.
  2. Select JMX Connections -> Browse-> Connections.
  3. Click the connection to activate.
  4. Select the Activate check box and save your changes.
  5. If the connection is successfully activated, you see the list of available domains displayed in the Provided Domains section.

CLM Server Monitoring configuration

  1. Click the domain of the activated connection. Example: team.server./jazz@9443
  2. Ensure that the AllMonitorsEnabled and DiagnosticsEnabled check boxes are selected.
  3. Add rules, based on the example rules at CLMServerMonitoringRules.
    image below from CSM Agent 4.0.6. CSM Agent 5.0 and higher use a different format for rules. see CLMServerMonitoringRules.
  4. Click "Save".

CLM Server Monitoring threshold modification

  1. Navigate to one of the domains of the activated connection and click one of the monitors. Example: Request
  2. Enter a new value in the Threshold field and save your changes.

Usage scenario

Related topics:
Using WAIT in the CLM Server Monitoring Agent

Related topics: Deployment web home, Deployment web home

External links:

Additional contributors: TWikiUser, TWikiUser

Edit | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r5 | r4 < r3 < r2 < r1 | More topic actions...
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use. Please read the following disclaimer.
Ideas, requests, problems regarding the Deployment wiki? Create a new task in the RTC Deployment wiki project