Upgrading from a previous version on Tomcat

• Creating databases for asset lifecycles in DB2
• Creating databases for asset lifecycles in Oracle
• Creating databases for asset lifecycles in Microsoft SQL Server

Migrate your Rational Licensing Server to Rational Common Licensing V8.1.2 or later. For more information, see Migrating from Rational Licensing Server v7.1.x or earlier to Rational Common Licensing.

Rational License Key Server is included with the Rational Asset Manager installation media. You can also retrieve the latest version of Rational License Server through your Passport Advantage account, or through the IBM Support Portal.

This process requires that you shut down all applications that use Rational Licensing Server, uninstall your existing Rational Licensing Server, update your license files, and install Rational Common Licensing server. For Windows, see Configuring a license server for Windows; for AIX® or Linux, see Configuring a license server for UNIX.

1. Find and extract the archive_extract_location\apps\tomcat\sharedLib.zip file.
2. Copy the entire contents of the extracted sharedLib.zip file to the tomcat_install_directory\lib directory.

Extract the library files for Rational Licensing Key Server V8.1.2 to the tomcat_install_directory\lib folder:

1. Find and extract the archive_extract_location\sharedLibs\rlsclients_rlsibmratl_812.zip file.
2. From the extracted .zip file, find the file rlsibmratl812.zip for your operating system and architecture. For example, the file for 32-bit Windows is in the win32 directory.
3. Extract the contents of the appropriate rlsibmratl812.zip file.
4. Copy the entire contents of the extracted rlsibmratl812.zip file to the tomcat_install_directory\shared\lib directory. For Tomcat 6 or 7, copy the entire contents of the extracted rlsibmratl812.zip file to the tomcat_install_directory\lib directory.

Modify the startup script for the Tomcat server for Rational Asset Manager

1. Find the Tomcat startup file and open it in a text editor. On Windows, this file is tomcat_install_directory\bin\startup.bat. On Linux, AIX, or Linux for zSeries, it is tomcat_install_directory/bin/startup.sh.
2. Search for a line that includes JAVA_OPTS=.
   • If the JAVA_OPTS environmental variable is already set, add the following option and value:
     • 

       -Djava.library.path="tomcat_install_directory\shared\lib"

     • 

       -Djava.library.path=tomcat_install_directory/shared/lib

   • If the JAVA_OPTS environmental variable is not set, type the following text:
     • 

       set JAVA_OPTS=-Djava.library.path="tomcat_install_directory\lib"

     • 

       export JAVA_OPTS="-Djava.library.path=tomcat_install_directory/lib"

1. In a text editor, open the tomcat_install_directory\conf\server.xml file.
2. Search for the following text:

   <!--
   <Valve className="org.apache.catalina.authenticator.SingleSignOn" />
   -->

3. Uncomment the <Valve> element:

   <Valve className="org.apache.catalina.authenticator.SingleSignOn" />

4. If you are not running Tomcat as a service, in a text editor, open the startup.bat file (on Microsoft Window) or the startup.sh file (on Linux). Add the following line to the file. For Microsoft Windows:

   SET JAVA_OPTS=" -Dorg.apache.catalina.authenticator.Constants.SSO_SESSION_COOKIE_NAME=JSSOSESSIONID"

   For Linux:

   export JAVA_OPTS=" -Dorg.apache.catalina.authenticator.Constants.SSO_SESSION_COOKIE_NAME=JSSOSESSIONID"

5. If you are running Tomcat as a service, add the following options to the service install command that you use to install Tomcat as a service: --JvmOptions "-Xrs; -Dorg.apache.catalina.authenticator.Constants.SSO_SESSION_COOKIE_NAME=JSSOSESSIONID"

• If you are upgrading from V7.1.1.1 or earlier: Install and configure the included Rational Team Concert. Proceed to step 15.
• If you are upgrading from V7.2 or later: Update the included Rational Team Concert. Proceed to step 32.

• If you need to install and configure Rational Team Concert: Proceed to step 16.
• If you have an existing Rational Team Concert application and want to configure it to work with Rational Asset Manager: Proceed to step 24.

1. Create a security certificate that identifies your Tomcat server for Rational Team Concert for SSL connections. You can use the Java™ JDK keytool command to create a self-signed certificate. Alternatively, you can request a certificate that is signed by a trusted certificate authority.
   For more information about creating self-signed certificates with the keytool command, see the Oracle Java documentation. You can create a self-signed certificate with the following example keytool command:

   keytool -genkey -alias tomcat -keystore tomcat_for_rtc_install_directory/.keystore

   When you run that command, you will be prompted for a password for the keystore file. The default password is changeit, but you should specify a different one. You will have to remember that password to input it into the server.xml file later.

   If you are using an IBM JRE, many versions include the IBM tool ikeyman in the IBM_Java_JRE_install_location/jre/bin/ directory. You can use this tool to create and manage security certificates on the server. For more information about using the iKeyman tool, see iKeyman User's Guide.

   We also include a simple certificate in the rtc_install_dir/jazz/server/ folder; the certificate file is ibm-team-ssl.keystore

2. In the tomcat_for_rtc_install_directory\conf\server.xml file, find the <Connector> tag with the attribute scheme="https". The default file includes an example <Connector> tag for port 8443 that is commented out.
3. Copy and paste the following text:

   <Connector port="8443"
        maxHttpHeaderSize="8192" 
        maxThreads="150"
        minSpareThreads="25" 
        maxSpareThreads="75"
        enableLookups="false"
        disableUploadTimeout="true"
        connectionTimeout="20000"
        acceptCount="100"
        scheme="https"
        secure="true" 
        clientAuth="false"
        keystoreFile="keystore_file"
        keystorePass="keystore_password"
        sslProtocol="keystore_protocol"
        algorithm="keystore_algorithm"
        URIEncoding="UTF-8"
   />

   Where:

   • keystore_file is the file name of your keystore file. It can be an absolute path, or relative from the root directory of your Tomcat server (tomcat_for_rtc_install_directory). If you used the simple command above, this will be .keystore. If you use the included certificate, this will be rtc_install_dir/jazz/server/ibm-team-ssl.keystore .
   • keystore_password is the password for the keystore file. If you use the included keystore file, this is ibm-team .
   • keystore_protocol is the protocol for the keystore. Most likely it is TLS or SSL_TLS. If you use the included keystore file, this is SSL_TLS .
   • keystore_algorithm is the X509 algorithm for the keystore. Most likely it is SunX509 or IbmX509, depending on the source of the certificate. If you use the included keystore file, this is IbmX509 .
4. You can change the port value to use a port besides 8443 for the non-SSL connector (by default, port 8080). If you change the port value, change the value of the redirectPort attribute to match your port number for the SSL connector.

For more information about configuring SSL for Tomcat, see Apache Tomcat 7 SSL Configuration HOW-TO and Apache Tomcat Configuration reference.

Copy the appropriate .jar file from your database provider:

• Copy the ojdbc6.jar file to the rtc_install_dir/jazz/server/oracle folder (you might need to create the oracle folder).

  You can download the file from Oracle.

• Copy the following file to the rtc_install_dir/jazz/server/sqlserver folder (you might need to create the sqlserver folder):
  • sqljdbc4.jar (You can download this file from Microsoft.)

1. Find the Tomcat startup file and open it in a text editor. On Windows, this file is tomcat_for_rtc_install_directory\bin\startup.bat. On Linux, AIX, or Linux for zSeries, the file is tomcat_for_rtc_install_directory/bin/startup.sh.
2. In the startup file, type the following text:
   • Replace each space character in the rtc_install_dir with %20:

     set ORACLE_JDBC=oracle_jar_dir
     set SQLSERVER_JDBC=sqlServer_jar_dir
     set JAZZ_INSTALL_DIR=rtc_install_dir
     set JAVA_OPTS=-Djava.awt.headless=true -Djava.library.path="tomcat_for_rtc_install_directory\shared\lib" -DSQLSERVER_JDBC="%SQLSERVER_JDBC%" -DORACLE_JDBC="%ORACLE_JDBC%" -DDB2I_JDBC="%DB2I_JDBC%" -DDB2Z_JDBC="%DB2Z_JDBC%" -Dorg.eclipse.emf.ecore.plugin.EcorePlugin.doNotLoadResourcesPlugin=true -DJAZZ_HOME=file:///%JAZZ_INSTALL_DIR%\jazz\server\conf -Dcom.ibm.team.repository.tempDir=%TEMP% -Xmx700M

   • 

     ORACLE_JDBC=oracle_jar_dir
     SQLSERVER_JDBC=sqlServer_jar_dir
     JAZZ_INSTALL_DIR=rtc_install_dir
     export JAVA_OPTS="-Djava.awt.headless=true -Djava.library.path=tomcat_for_rtc_install_directory/shared/lib -DSQLSERVER_JDBC=$SQLSERVER_JDBC -DORACLE_JDBC=$ORACLE_JDBC -DDB2I_JDBC=$DB2I_JDBC -DDB2Z_JDBC=$DB2Z_JDBC -Dorg.eclipse.emf.ecore.plugin.EcorePlugin.doNotLoadResourcesPlugin=true -DJAZZ_HOME=file://"$JAZZ_INSTALL_DIR"/jazz/server/conf -Dcom.ibm.team.repository.tempDir=$TEMP_DIR -Xmx700M"

   Where:

   • rtc_install_dir is the extracted directory of the RTC-server.zip file. On Windows, replace each space character in rtc_install_dir with %20
   • oracle_jar_dir is the directory for the ojdbc6.jar file (rtc_install_dir/jazz/server/oracle)
   • sqlServer_jar_dir is the directory of the sqljdbc4.jar file (rtc_install_dir/jazz/server/sqlserver)
   • tomcat_for_rtc_install_directory is the installation directory for the Tomcat server
   • If you are installing Rational Asset Manager and Rational Team Concert on the same application server, use this JAVA_OPTS system variable to replace the one that you created when you configured the startup script for the Tomcat server for Rational Asset Manager; this declaration still includes the -Djava.library.path option.

1. In the rtc_install_dir/jazz/server/conf/ramjazz/ directory, find the teamserver.properties file and rename it to teamserver.derby.properties.
2. Find the appropriate file for your database server:
   • For DB2 on Windows: teamserver.db2.win32.properties
   • For DB2 on Linux, AIX, or Linux for zSeries: teamserver.db2.linux.properties
   • teamserver.oracle.properties
   • teamserver.sqlserver.properties
3. Rename the file to teamserver.properties.

• 
  1. Find the following lines:

     com.ibm.team.repository.db.vendor = DB2
     com.ibm.team.repository.db.jdbc.location=//localhost:50000/JAZZ:user=db2admin;password={password};
     com.ibm.team.repository.db.jdbc.password=db2admin

  2. Edit the value of com.ibm.team.repository.db.jdbc.location for your DB2 server location, and the name of the database for lifecycles:
     1. Replace localhost:50000 with the location and port for the DB2 database.
        Tip: In the DB2 command window, type db2 get dbm cfg, and then find the line that contains SVCENAME, which indicates the DB2 port name or number. If this command displays a number, use it as the port number (in place of 50000 in the earlier example). If the command returns a non-numeric name, determine what port number was assigned for this name and use that port number. On Linux, the /etc/services file contains the mapping between port names and numbers; on Windows, the C:\windows\system32\drivers\etc\services file contains the mapping. For more information, ask your database administrator or see the database documentation.
     2. Replace JAZZ with the name of the database for lifecycles.
     3. Replace db2admin with the user name for the DB2 database.
        Note: The DB2 user must have permissions to create tables, table spaces, and to modify the database configuration. DB2 users are created by the operating system.
  3. In the com.ibm.team.repository.db.jdbc.password property, specify the user password.
     Note: Do not change the password={password} text in the com.ibm.team.repository.db.jdbc.location property.
  4. In the teamserver.properties file, add the following properties:
     Where:

     • unsecure_port is the unsecured port for your Tomcat server (by default, 8080)
     • secure_port is the secure port number for your Tomcat server (by default, 8443)
     • team_temp_dir is an absolute path to a directory for storing temporary files

     com.ibm.team.scm.tmpdir=team_temp_dir
     com.ibm.team.repository.server.repourl.port.http=unsecure_port
     com.ibm.team.repository.user.registry.type=UNSUPPORTED
     com.ibm.team.repository.ws.allow.admin.access=false
     com.ibm.team.repository.server.repourl.port.https=secure_port

• 
  1. Find the following lines:

     com.ibm.team.repository.db.vendor = ORACLE
     com.ibm.team.repository.db.jdbc.location=thin:jazzDBuser/{password}@localhost:1521/ORCL
     com.ibm.team.repository.db.jdbc.password=jazzDBpswd

  2. Edit the value of com.ibm.team.repository.db.jdbc.location for your Oracle server location and the name of the database for lifecycles:
     1. Replace jazzDBUser with the user name for the Oracle database (for example, RAMSCHEMA.
     2. Replace @localhost:1521 with the location and port for the Oracle database. If the location is not localhost, you must precede the location with two forward slashes (//); for example, @//oracleserver.example.com:1521.
     3. Replace ORCL with the name of the lifecycle database; for example, rtcdb.
  3. In the com.ibm.team.repository.db.jdbc.password property, replace JazzDBpswd with the password for the Oracle that user you specified earlier.
     Note: Do not change the {password} text in the com.ibm.team.repository.db.jdbc.location property.
  4. In the teamserver.properties file, add the following properties:
     Where:

     • unsecure_port is the unsecured port for your Tomcat server (by default, 8080)
     • secure_port is the secure port number for your Tomcat server (by default, 8443)
     • team_temp_dir is an absolute path to a directory for storing temporary files

     com.ibm.team.scm.tmpdir=team_temp_dir
     com.ibm.team.repository.server.repourl.port.http=unsecure_port
     com.ibm.team.repository.user.registry.type=UNSUPPORTED
     com.ibm.team.repository.ws.allow.admin.access=false
     com.ibm.team.repository.server.repourl.port.https=secure_port

  5. If you are using Oracle 11: In the teamserver.properties file, add the following property:

     com.ibm.team.repository.db.override.versioncheck=true

• 
  1. Find the following lines:

     com.ibm.team.repository.db.vendor = SQLSERVER
     com.ibm.team.repository.db.jdbc.location=//localhost:1433;databaseName=jazz;user=jazzDBuser;password={password}
     com.ibm.team.repository.db.jdbc.password=jazzDBpswd

  2. Edit the value of com.ibm.team.repository.db.jdbc.location for your SQL Server location and the name of the database for lifecycles:
     1. Replace @localhost:1433 with the location and port for the SQL Server database.
     2. Replace jazz with the name of the lifecycle database; for example, RTCDB.
     3. Replace jazzDBUser with the user name for the SQL Server database.
  3. In the com.ibm.team.repository.db.jdbc.password property, replace JazzDBpswd with the password for the SQL server user that you specified earlier.
     Note: Do not change the {password} text in the com.ibm.team.repository.db.jdbc.location property.
  4. In the teamserver.properties file, add the following properties:
     Where:

     • unsecure_port is the unsecured port for your Tomcat server (by default, 8080)
     • secure_port is the secure port number for your Tomcat server (by default, 8443)
     • team_temp_dir is an absolute path to a directory for storing temporary files

     com.ibm.team.scm.tmpdir=team_temp_dir
     com.ibm.team.repository.server.repourl.port.http=unsecure_port
     com.ibm.team.repository.user.registry.type=UNSUPPORTED
     com.ibm.team.repository.ws.allow.admin.access=false
     com.ibm.team.repository.server.repourl.port.https=secure_port

1. Open a command-line window and navigate to the rtc_install_dir/jazz/server/ directory.
2. Enter the following command:
   • 

     repotools.bat -createTables teamserver.properties=conf\jazz\teamserver.properties

   • 

     ./repotools.sh -createTables teamserver.properties=conf/jazz/teamserver.properties

• For file-based security:
  1. In a text editor, open the tomcat_for_rtc_install_directory\conf\tomcat-users.xml file.
  2. Between the <tomcat-users> tags, paste the following text:

     <role rolename="JazzUsers"/>
     <role rolename="JazzAdmins"/>
     <role rolename="JazzDWAdmins"/>
     <role rolename="JazzGuests"/>

  3. Add a user named admin and assign that user the admin, manager, and JazzAdmins roles. To add this user, you can copy and paste the following text between the <tomcat-users> tags:

     <user username="admin" password="" roles="admin,manager,JazzAdmins" />

     If you are installing the applications on the same Tomcat server, add the JazzAdmins role to the existing admin user.

• For LDAP authentication: Configure the Tomcat server for LDAP authentication, and then configure four LDAP groups with the same names as the four previously mentioned roles. Alternatively, you can associate existing LDAP groups to the Jazz server roles as described in the Tech Tip TN0030: User Management in Tomcat. Follow steps 2–3 in the topic Configuring Rational Team Concert on Tomcat to use LDAP section.

• tomcat_for_rtc_install_directory\bin\startup.bat
• tomcat_for_rtc_install_directory/bin/startup.sh

1. If you see an error about "fetching server status information," shut down and restart both your database server and your application server and log in again.
2. In the Rational Team Concert Administrative web interface, click User Management. Ignore any errors about an external registry not being configured.
3. Click Create User.
4. Enter the following details:
   1. User Name: The user ID of the application server administrator
   2. User ID: The user ID of the application server administrator
   3. Email Address: A valid email address for the application server administrator
5. In the Client Access License section, select Rational Team Concert - Developer to assign the developer license to that user.
6. Click Save.
7. Log out, and then log back in to the Administrative web interface as the administrator of the application server.

1. In the Rational Team Concert Administrative web interface, click Process Template Management. If you cannot see the Process Template Management link, log out and then log back in to the Administrative web interface.
2. Click Import Template and browse to the com.ibm.ram.lifecycle.zip file in the archive_extract_location/DatabaseScripts/ folder. Then click OK. The RAM Lifecycle template is displayed.

1. In the Rational Team Concert Administrative web interface, click Project Area Management. If you cannot see the Project Area Management link, log out and then log back in to the Administrative web interface.
2. Click Create Project Area.
3. Enter the following details about the project area:
   • Project name: RAM Lifecycle
   • Summary: Rational Asset Manager Lifecycle control project area
   • Description: This area is used to manage the lifecycles for Rational Asset Manager
4. Click Save.

1. On the Project Area Management page, click the RAM Lifecycle project area.
2. In the Administrators section, click Add. Search for and select the administrator user that you created. If you are working with an existing Rational Team Concert application, you can also select a different user to be administrator for this project area.
3. In the Members section, click Add; then search for and select the same user that you selected as the administrator for the project area.
4. After you add the administrator, click the Process Roles icon next to the administrator's name.
5. In the Edit Process Roles window, from the Available Roles list, select Administration and click Add.
6. Click Finish.
7. Click Save.

1. From the installation media, extract the RTC-Server.zip file to a new location on your hard disk drive, which in these instructions is referred to as new_rtc_install_dir.
2. From the older rtc_install_dir/jazz/server/conf/jazz/ folder, copy the file teamserver.properties to the new new_rtc_install_dir/jazz/server/conf/jazz/ folder.

   You can find the existing rtc_install_dir location in the Tomcat startup file. In the startup file, search for the line that contains JAZZ_INSTALL_DIR=; the value of the JAZZ_INSTALL_DIR variable is the location of the current Rational Team Concert files.

3. Find the Tomcat startup file and open it in a text editor. On Windows, this file is tomcat_for_rtc_install_directory\bin\startup.bat. On Linux, AIX, or Linux for zSeries, the file is tomcat_for_rtc_install_directory/bin/startup.sh.
4. In the Tomcat startup file, search for the line that contains JAZZ_INSTALL_DIR=. Edit the value per the following, where new_rtc_install_dir is the extracted directory from step 32.a:
   • (replace space characters in new_rtc_install_dir with %20):

     set JAZZ_INSTALL_DIR=new_rtc_install_dir

   • :

     JAZZ_INSTALL_DIR=new_rtc_install_dir

5. Start the Tomcat server.
6. In a web browser, enter the following URL: https://host:secure_port/jazz/admin?internal, where host is your IP address or server name, and secure_port is the secure port for your Tomcat server.
7. Log on as an application server administrator.
8. In the sidebar, under Internal Tools, click Server reset.
9. Click Request server reset.
10. Stop, and then restart the Tomcat server. The included Rational Team Concert application is updated.

1. Navigate to the tomcat_install_directory/webapps/ directory.
2. Note the folders and file names for any Rational Asset Manager web applications. In previous versions of Rational Asset Manager, the following names were suggested for those folders (in other words, the context paths of the applications):
   • /com.ibm.ram.repository.web.tomcat_runtime
   • /com.ibm.ram.repository.web.ws.tomcat_runtime
   • /help/
   • /abdprocess/
3. Delete the following application files:
   • com.ibm.ram.repository.web.tomcat_runtime.war
   • com.ibm.ram.repository.web.ws.tomcat_runtime.war
   • ramhelp.war
   • rmcabdgovernprocess.war
   The file names might be different from the names in the list, depending on how you installed the applications on your server.
4. Delete the associated folders for those applications.

• com.ibm.ram.repository.web.tomcat_runtime.war
• com.ibm.ram.repository.web.ws.tomcat_runtime.war
• ramhelp.war
• rmcabdgovernprocess.war

1. In a web browser, open the Rational Asset Manager web client. The first time that you open the web client after the upgrade, a message is displayed that indicates that you must migrate the repository.
2. If necessary, log in with a user ID that has repository administrator authority.
   Note: For SQL Server, if an existing Rational Asset Manager database does not have the collation set to a sequence that ends with _BIN2 (for example, Latin1_General_BIN2) then the Manual Configuration Required page appears with a message. You can either recreate the database and set the collation option to be case-sensitive to work correctly with Rational Asset Manager or you can accept that there might be unexpected case-sensitivity conflicts.
3. Click Migrate. On large repositories, the migration might take several minutes; until the migration is complete, some information about the repository might not be available.
4. After the migration process completes, click Home.

1. In the Rational Asset Manager web client, click Administration.
2. Click Configuration.
3. In the Internal Rational Team Concert path section, type the following information:
   1. Path: The secure URL to the Rational Team Concert server that you have configured. For example, https://localhost:9443/ramccm. Note the https connection, and the secure port number.
   2. User: The user name for the user in Rational Team Concert that is the administrator for the "RAM Lifecycles" project area.
   3. Password: The password for the user that is the administrator for the "RAM Lifecycles" project area.
   4. Timeout: The amount of time, in seconds, to allow Rational Asset Manager to connect to Rational Team Concert. The default is 120.