r6 - 2015-08-10 - 09:03:29 - StevenBeardYou are here: TWiki >  Deployment Web > DeploymentMonitoring > CLMServerMonitoring > CLMServerMonitoringAgent > CLMServerMonitoringAgentUpgrade

CLM Server Monitoring Agent Upgrade uc.png

Authors: Gerald Mitchell (GeraldMitchell)
Build basis: Collaborative Lifecycle Management 4.0.6 and later for CSM plugin, Collaborative Lifecycle Management 5.0.1 and later for CSM Agent

(Under Construction)

CLM Server Monitoring Agent can be upgraded from 5.0.1 to 5.0.2. It may or may not be necessary, depending on your usage.

Determining if you should upgrade or do a new install.

Questions to Ask:
  • Is there a need to upgrade?
  • Is the stored information still needed?
  • Am I monitoring more than one CLM deployment?
  • Did my CLM deployment topologies change?
  • How is my CSM Agent currently installed and configured?

Note that the rules information is stored in the CLM application configuration files, and so these settings will remain the same on upgrade of CLM and the CSM Agent.

An upgrade might be preferred if:

  • The monitoring information is still needed.
  • A secured WebSphere application server is hosting CLM and the required security and setup is complex to coordinate in your organization.

A new install might be preferred if:

  • Changing your deployment topology. The previous information is not relevant.
  • Many previous performance investigations. The previous information storage may be costly and not needing retention.

The upgrade process

Do I need to upgrade?

First, make sure that there is a need to upgrade. Right now, there are only 2 version of CSM Agent, 5.0.1 and 5.0.2, that are supported releases. It is recommended that you use a new install if you were previously using a Milestone version of CSM Agent in order to avoid version incompatibilities and have the correct code levels for communications with the CLM versions.

Do I meet the system requirements?

Next, determine that the system requirements match the compatible CLM Server Monitoring Agent requirements. (If there is a question, please contact this section owner of the wiki directly.)

Follow the upgrade process

CSM Agent behaves in the same manner as the other Jazz Foundation based applications, and so follows a similar upgrade procedure. If you are used to using the upgrade guide tool in the KnowledgeCenter, treating CSM Agent as if it was a JTS is pretty accurate.

There is no upgrade script for CSM Agent.

The files that are important to move are the data base (or Derby) and the files in /server/conf/csm/

Note that the rules information is stored in the CLM application configuration files (like /server/conf/jts), and so these settings will remain the same on upgrade of CLM and the CSM Agent.

Upgrading CSM Agent when using the Embedded Tomcat

Assumptions in the instructions

  • Moving from CSM Agent 5.0.1 to 5.0.2
  • Assuming the original CLM Server Monitoring Agent install was to /opt/IBM/CSMAgent501 being signified as {CSM_Agent_Old_Install}
  • Assuming the new install is being placed at /opt/IBM/CSMAgent502 signified as {CSM_Agent_New_Install}
  • Hosting the database on DB2
  • no change to the Linux or DB2 needs to occur
  • all commands are enacted as Administrator and root

Installation

Install the new version (CSM5.0.2) through your Installation method (Installation Manager through the Launchpad) * Follow the normal process for a new install. CLM Server Monitoring Agent does a side-by-side install for the upgrade process.

Backup CSM behaviors

Backup the Server Monitoring settings and rules
  • Go to each CLMM applications being monitored, while still running. On the file system, make a backup of:
    • {CLM_app_install}/server/conf/{*}/smarterServer.properties
    • {CLM_app_install}/server/conf/{*}/issueRules.xml

Stop Monitoring

Deactivate existing behaviors for monitoring
  • Log-in to your CSM Agent instance
  • For every project
    • For every JMX connection
      • For every bean
        • Note that the rules are the same as the issueRules.xml settings in the {CLM_app_install}/server/conf/{*}/issueRules.xml that you have backed up
        • Change any monitor rules that you may have set directly into the bean settings through checkboxes or text entry.
        • Assure any monitor settings in the bean are safe to leave while not monitoring
    • It is best to deactivate all of the connections while upgrading

Migrate the /csm information

Remove the default CSM 5.0.2 indices, and replace with the 5.0.1 indices

  • rm -rf {CSM_Agent_New_Install}/server/conf/csm/indices
  • Example: rm -rf /opt/IBM/CSMAgent5.0.2/server/conf/csm/indices

Open the {CSM_Agent_Old_Install}/server/conf/csm/teamserver.properties file and search for com.ibm.team.fulltext.indexlocation.

Check the index locations

  • If the property com.ibm.team.fulltext.indexlocation is pointing to a relative path like com.ibm.team.fulltext.indexLocation=conf/application/indices/workitemindex
  • change this relative path to an absolute path to a stable location in the CLM Server Monitoring Agent 5.0.2 application's teamserver.properties file: com.ibm.team.fulltext.indexLocation=/opt/IBM/CSMAgent5.0.2/server/conf/csm/indices/workitemindex

Open a command prompt and enter the following command to copy the full text indices from previous version to 6.0. Change the source directory according to the location of the index files:

  • copy {CSM_Agent_Old_Install}/server/conf/csm/indices into {CSM_Agent_New_Install}/server/conf/csm/indices
  • Example: cp -R /opt/IBM/CSMAgent5.0.1/server/conf/csm/indices /opt/IBM/CSMAgent5.0.2/server/conf/csm/indices
Replace {CSM_Agent_Old_Install} to {CSM_Agent_New_Install}:
    • /server/tomcat/conf/tomcat-users.xml
Manually merge the following files from {CSM_Agent_Old_Install} to {CSM_Agent_New_Install}:
  • Merge the following:
    • /server/conf/csm/teamserver.properties
  • If you did not customize these files, no migration is required and you don't need to copy or merge, other wise iyou must manually migrate your customized settings over to the newer files.
    • /server/conf/csm/log4j.properties
    • /server/conf/csm/services.xml
    • /server/conf/csm/scr.xml
    • /server/conf/startup_log4j.properties
    • /server/conf/repotools_log4j.properties
    • /server/tomcat/conf/wsjaas.conf
    • /server/tomcat/conf/soap.client.props
    • /server/tomcat/conf/sssl.client.props
    • /server/tomcat/conf/ipc.client.props
    • /server/tomcat/conf/sas.client.props
    • /server/tomcat/conf/server.xml
    • /server/tomcat/conf/logging.properties
    • /server/tomcat/conf/catalina.properties
    • /server/tomcat/conf/catalina.policy
    • /server/tomcat/conf/context.xml
    • /server/tomcat/conf/web.xml
  • Replace any {CSM_Agent_Old_Install} references inside the resulting files with {CSM_Agent_New_Install}.

Verify that the application configuration file is copied from previous installation:

  • The properties that were copied from the previous version of the teamserver.properties file need to point where appropriate.
  • Make sure that the valid, distinct URL in the com.ibm.repository.server.webapp.url property. is retained correctly.
  • The URL for CSM must be the same as the one that was used in the previous version.
  • Ensure the database that is specified in each application's teamserver.properties file exists.

Note: if you were not using Derby instead of DB2 for CSM Agent storage, you need to

  1. rm -rf {CSM_Agent_New_Install}/server/conf/csm/derby/
  2. cp {CSM_Agent_Old_Install}/server/conf/csm/derby/ {CSM_Agent_New_Install}/server/conf/csm/derby/
Note2: if you were not using Derby instead of DB2 for CSM Agent DataWarehousing storage, you need to
  1. locate the DataWarehouse using com.ibm.team.datawarehouse.db..jdbc.location property in {CSM_Agent_New_Install}/server/conf/csm/teamserver.properties
  2. if it is in {CSM_Agent_Old_Install}, move it to {CSM_Agent_New_Install} appropriately, and make sure that com.ibm.team.datawarehouse.db..jdbc.location property in {CSM_Agent_New_Install}/server/conf/csm/teamserver.properties is pointed to the correct location.

Upgrade from the CSM Agent 5.0.2 directory

  • change directory to the new CSM Agent install via cd {CSM_Agent_New_Install}/server/ and issue the following commands:
    • sh ./repotools-csm.sh -addTables
      • After carefully checking the path to the CSm Agent database to confirm it is correct, answer Y and press enter when asked if wanting to proceed.

Start the Tomcat server

As administrator or root, issue the command sh ./{CSM_Agent_New_Install}/server/server.startup

Setup the new /csm

In a web browser, go to the Administration page of the CSM Agent

Note: At this point you may need to get new CSM licenses (You would be told so before the upgrade process) in which case:

  • Log into https://hostname.example.com:9443/csm/admin and click Server > License Key Management.
  • In the Floating License Server section, click Add and upload your version 5.0 license file.
  • After upload is complete, there will be 2 entries in the Floating License Server section. Hover over the version 5.x license entry and click the red X icon to delete the entry. If a warning message is shown, click OK.
  • Go to Users > Client Access License Management, select a token license, and confirm that the list of users that had the version 5.x licenses is present.

Upgrading CSM Agent for WebSphere Application Servers 8.0 and higher (Not yet verified)

Assumptions in the instructions

  • Moving from CSM Agent 5.0.1 to 5.0.2
  • Assuming the existing /csm is on WebSphere Application Server in profile AppSrv01 in /opt/IBM/WebSphere/AppServer/profiles/AppSrv01 and using server1 to host the /csm application.
  • Assuming the upgrade is to the original /csm installed host system and WebSphere server, and that the system is using a Linux operating system
  • Assuming the original CLM Server Monitoring Agent install was to /opt/IBM/CSMAgent501 being signified as {CSM_Agent_Old_Install}
  • Assuming the new install is being placed at /opt/IBM/CSMAgent502 signified as {CSM_Agent_New_Install}
  • Hosting the database on DB2
  • no change to the Linux, WebSphere or DB2 needs to occur
  • all commands are enacted as Administrator and root

Please self-correct paths and behavior if using Tomcat or Windows for now.

Installation

Install the new version (CSM5.0.2) through your Installation method (Installation Manager through the Launchpad) * Follow the normal process for a new install. CLM Server Monitoring Agent does a side-by-side install for the upgrade process.

Backup CSM behaviors

Backup the Server Monitoring settings and rules
  • Go to each CLM application server being monitored, on the file system, while the CLM applications are still running. Make a backup of:
    • {CLM_app_install}/server/conf/{*}/smarterServer.properties
    • {CLM_app_install}/server/conf/{*}/issueRules.xml

Stop Monitoring

Deactivate existing behaviors for monitoring
  • Log-in to your CSM Agent instance
  • For every project
    • For every JMX connection
      • For every bean
        • Note that the rules are the same as the issueRules.xml settings in the {CLM_app_install}/server/conf/{*}/issueRules.xml that you have backed up
        • Change any monitor rules that you may have set directly into the bean settings through checkboxes or text entry.
        • Assure any monitor settings in the bean are safe to leave while not monitoring
    • It is best to deactivate all of the connections while upgrading

Backup the application server profile

Backup the WebSphere profile in use for /csm. Note that this shutsdown the WebSphere application servers on that profile.
  • create a backup directory
    • Example: mkdir /opt/WAS_backup
  • issue the WebSphere Application Server profile backup command
    • Example: /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/backupConfig.sh /opt/WAS_backup/CSMAgent_5.0.1_profile.zip -username {WebSphere_admin_username} -password {WebSphere_admin_username}

uninstall the old /csm

Uninstall the existing /csm from the WebSphere server
  • Restart the server.
  • Log on to the WebSphere Application Server Integrated Solutions Console.
  • Click Applications > Application Types > WebSphere enterprise applications.
  • Click csm_war and then under Detail Properties click Security role to user/group mapping. Write down the security roles mapping for csm_war application because it is needed to map the CLM Server Monitoring Agent for 5.0.2.
  • Click the Enterprise Applications link and then stop and uninstall csm_war.
  • When you are prompted to save the changes to the master configuration, save them.

Setup JAZZ_HOME for the new version

  • Click Servers > Server Types > WebSphere application servers.
  • Click the server name to open it. The default server name is server1.
  • Under Server Infrastructure section, click Java and Process Management > Process definition.
  • Under Additional Properties, click Java Virtual Machine. *
Under Additional Properties, click Custom properties.

Stop the appropriate WebSphere Application Server profile server.

  • Example: /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin /stopServer.sh server1 -profile AppSrv01 -user {Websphere_admin_userid} -password {WebSphere_admin_password}

Remove the application-related contents from the following directories in the profile:

  • /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/temp
  • /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/temp/wscache
  • a csm_war directory might be in the profile and can be removed.

Remove the csm-related log files form the following logs directory in the profile:

  • /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs

Migrate the /csm information

Remove the default CSM 5.0.2 indices, and replace with the 5.0.1 indices

  • rm -rf {CSM_Agent_New_Install}/server/conf/csm/indices
  • Example: rm -rf /opt/IBM/CSMAgent5.0.2/server/conf/csm/indices

Open the {CSM_Agent_Old_Install}/server/conf/csm/teamserver.properties file and search for com.ibm.team.fulltext.indexlocation.

Check the index locations

  • If the property com.ibm.team.fulltext.indexlocation is pointing to a relative path like com.ibm.team.fulltext.indexLocation=conf/application/indices/workitemindex
  • change this relative path to an absolute path to a stable location in the CLM Server Monitoring Agent 5.0.2 application's teamserver.properties file: com.ibm.team.fulltext.indexLocation=/opt/IBM/CSMAgent5.0.2/server/conf/csm/indices/workitemindex

Open a command prompt and enter the following command to copy the full text indices from previous version to 6.0. Change the source directory according to the location of the index files:

  • copy {CSM_Agent_Old_Install}/server/conf/csm/indices into {CSM_Agent_New_Install}/server/conf/csm/indices
  • Example: cp -R /opt/IBM/CSMAgent5.0.1/server/conf/csm/indices /opt/IBM/CSMAgent5.0.2/server/conf/csm/indices

Manually merge the following files from {CSM_Agent_Old_Install} to {CSM_Agent_New_Install}:

  • Merge the following:
    • /server/conf/csm/teamserver.properties
  • If you did not customize these files, no migration is required and you don't need to copy or merge, other wise iyou must manually migrate your customized settings over to the newer files.
    • /server/conf/csm/log4j.properties
    • /server/conf/csm/services.xml
    • /server/conf/csm/scr.xml
    • /server/conf/startup_log4j.properties
    • /server/conf/repotools_log4j.properties
  • Replace any {CSM_Agent_Old_Install} references inside the resulting files with {CSM_Agent_New_Install}.

Verify that the application configuration file is copied from previous installation:

  • The properties that were copied from the previous version of the teamserver.properties file need to point where appropriate.
  • Make sure that the valid, distinct URL in the com.ibm.repository.server.webapp.url property. is retained correctly.
  • The URL for CSM must be the same as the one that was used in the previous version.
  • Ensure the database that is specified in each application's teamserver.properties file exists.

Note: if you were not using Derby instead of DB2 for CSM Agent storage, you need to

  1. rm -rf {CSM_Agent_New_Install}/server/conf/csm/derby/
  2. cp {CSM_Agent_Old_Install}/server/conf/csm/derby/ {CSM_Agent_New_Install}/server/conf/csm/derby/
Note2: if you were not using Derby instead of DB2 for CSM Agent DataWarehousing storage, you need to
  1. locate the DataWarehouse using com.ibm.team.datawarehouse.db..jdbc.location property in {CSM_Agent_New_Install}/server/conf/csm/teamserver.properties
  2. if it is in {CSM_Agent_Old_Install}, move it to {CSM_Agent_New_Install} appropriately, and make sure that com.ibm.team.datawarehouse.db..jdbc.location property in {CSM_Agent_New_Install}/server/conf/csm/teamserver.properties is pointed to the correct location.

Upgrade from the CSM Agent 5.0.2 directory

  • change directory to the new CSM Agent install via cd {CSM_Agent_New_Install}/server/ and issue the following commands:
    • sh ./repotools-csm.sh -addTables
      • After carefully checking the path to the CSm Agent database to confirm it is correct, answer Y and press enter when asked if wanting to proceed.

Install the new /csm

Start the WebSphere Application Server with

    • /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/bin/startServer.sh server1

Log on to the WebSphere Application Server Integrated Solutions Console

    • Example: https://hostname.example.com:9043/ibm/console/logon.jsp.
    • Click Applications > Applications Types > WebSphere enterprise applications.
    • Install the csm.war from __{CSM_Agent_New_Install}__/server/server/webapps (or __{CSM_Agent_New_Install}__/server/server/tomcat/webapps if you chose to install the Tomcat too in Installation Manager)

Map the security roles appropriately for csm_war, which we recorded before the previous version uninstall.

Start the csm_war from the Integrated Solutons Console in the Applications > Applications Types > WebSphere enterprise applications view.

Check the server log files in the /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs directory, specifically the /ffdc incidents, the csm.log, csm-patch.log if available, the server1/SysteOut.log, and the server1/SystemErr.log

Setup the new /csm

In a web browser, go to the Administration page of the CSM Agent

Note: At this point you may need to get new CSM licenses (You would be told so before the upgrade process) in which case:

  • Log into https://hostname.example.com:9443/csm/admin and click Server > License Key Management.
  • In the Floating License Server section, click Add and upload your version 5.0 license file.
  • After upload is complete, there will be 2 entries in the Floating License Server section. Hover over the version 5.x license entry and click the red X icon to delete the entry. If a warning message is shown, click OK.
  • Go to Users > Client Access License Management, select a token license, and confirm that the list of users that had the version 5.x licenses is present.

Validate the new /csm

Run diagnostics on each server and verify that the diagnostics completed successfully:

Make sure that the projects load and the project dashboard loads with the data from before the upgrade.

Return to monitoring CLM Applications

Check the each project JMX Connection by returning the appropriate JMX connections to active and verify connection to the CLM servers.
  • Reactivate the Monitors where appropriate after verifying the rules.

You should now be monitoring CLM with CSM Agent 5.0.2!

Related topics: Deployment web home, Deployment web home

External links:

Additional contributors: TWikiUser, TWikiUser

Edit | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r6 < r5 < r4 < r3 < r2 | 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