Skip navigation
Share This:

In this post we'll take a look at how to migrate the RSSO application to a new version of tomcat web server. There are many reasons why you might want to migrate to a new tomcat version, some of which can include:

 

  • Keeping up with the latest supported version of Tomcat
  • A newer version has the features you require
  • New Tomcat support for the latest version of java
  • The need for better web server performance

 

In this blog we'll use the example of migrating the RSSO application from tomcat 7.0.62 to apache-tomcat8.5.23. We will be installing the new version of Tomcat and Java on the same machine as the 7.0.62 Tomcat install to minimise downtime.

 

File System locations used in this example:

 

Tomcat 7 : C:\Program Files\Apache Software Foundation RSSO\apache-tomcat-7.0.62

Tomcat 8 : C:\Program Files\Apache Software Foundation RSSO\apache-tomcat8.5.23 (will be installed in this path)

Java 7 : C:\Program Files\Java\jre7

Java 8 : C:\Program Files\Java\jre1.8.0_151  (will be installed in this path)

 

This procedure will be done on Windows but the process will still be valid on Linux, unless stated for Windows only.

 

Installing The New Version of Tomcat(for this post apache-tomcat8.5.23 & Java jre1.8.0_151)

 

1. Download the latest version of Tomcat from https://tomcat.apache.org/ & Java Check the BMC compatibility matrix for the version of RSSO you are running.

 

2. Install java. NOTE: If installing Java on the same server as a previous install of Tomcat, Java installer will asks to uninstall previous versions of java select "No". This is until we confirm that the new version of Tomcat is working as expected.

 

3. Extract the downloaded Tomcat files to the Apache Software directory i.e. "C:\Program files\ApacheSoftware" or "\opt\ApacheSoftware" or where ever you have a previous version of TC

 

4. Open a command prompt and set environment variable JAVA_HOME to the new version of tomcat. We will set the Java environment variable permanently at a later point once we have confirmed everything is working. Keep this command prompt open.

 

5. From command prompt run the following command and confirm the correct version of java is running "Java -version"

 

6. On windows we need to create the service for Tomcat. Open command prompt "cd" in to the the Apache/tomcat/bin directory and run "service.bat install" command. Once the service has been created successfully (fig1) check in windows services manger for the service.

 

fig1

If you have a previous version of Tomcat running on the server leave it running for the time being and do no start the new Tomcat service just yet.

 

 

Moving the RSSO Installation Files

We now have to move the RSSO application files from the previous install of Tomcat to the new one.

 

1. Copy the "/Tomcat/webapps/rsso" directory from the previous Tomcat install to the same location on the new Tomcat install. In the example we are using from

"C:\Program Files\Apache Software Foundation RSSO\apache-tomcat-7.0.62\webapps" to "C:\Program Files\Apache Software Foundation RSSO\apache-tomcat8.5.23\webapps"

 

2. Copy the following files from the old version of Tomcat from tomcat/lib to the same location on the new version. Note if you have installed a future version of RSSO relative to this blog date the versions numbers may have changed.

 

ojdbc6-11.2.0.2.0.jar

postgresql-9.4.1207.jre7.jar

sqljdbc4-4.0.jar

hsqldb-2.3.5.jar

 

3. If you have a trust store location used by RSSO SAML Authentiction, login to the RSSO Admin console --->Advanced and check where the trust/keystore store path is. You will then need to copy this file from the the old version of Tomact to the same location on the new install (fig2)

 

fig2 Shows the location of the store usually used for SAML authentication (field names may have changed from one version of RSSO to another) just copy the file to the new Tomcat location if its not a common path as show below

 

Moving Tomcat files & Edit Configuration File

Our next steps is to move any tomcat configuration files from the previous version to the next version & also make some changes to the server.xml file if using HTTPS

 

1. If the previous Tomcat version was running on HTTPS we need to move over, the keystore file and trustore files files (If being used) RSSO

Open the Tomcat\conf\server.xml file, search for " keystoreFile" This will give you the location of the keystore and truststore (if being used)

copy the keystore file from the previous version of tomcat to the same location on the new Tomacat server. If the path is common to both versions of tomacat it does not need to be copied for example if the keystore path is "C:\mykeystores\keystore.p12" then there is no need to move it.

 

2. If you have made any customisation to the /tomcat/conf/context.xml file then copy this file to the new Tomcat Install in the same location

 

3. If using HTTPS our next step is to copy the entries from the server.xml file from the old version of Tomcat to the new version. Open the tomcat/conf/server.xml file search for " keystoreFile" copy the whole segment from this connector port element and place it in the same location in the new Tomcat server.xml file and save the file. The segment will look like the example below

 

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"             

         maxThreads="150" scheme="https" secure="true"

         maxHttpHeaderSize="32768"

         clientAuth="false" sslProtocol="TLS"

ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA"                  

         keystoreFile="C:/Program Files/Apache Software Foundation RSSO/apache-tomcat-7.0.62/conf/keystore.p12"

         keystorePass="internal4bmc"

         keyAlias="tomcat"/>

 

NOTE: Remember if the keystore location is in the old Tomcat version path (highlighted in green) you will need to change it to point to the new version path as per example below

 

FROM:   keystoreFile="C:/Program Files/Apache Software Foundation RSSO/apache-tomcat-7.0.62/conf/keystore.p12"

TO:         keystoreFile="C:/Program Files/Apache Software Foundation RSSO/apache-tomcat-8.5.23/conf/keystore.p12"

 

 

Testing

At this point we have configured everything we need to start the new Tomcat service.

 

1. Stop the old tomcat service

2. Start the new tomcat service

3. Login to the RSSO admin console with the same URL as before

 

You should now be able to continue testing. Test for a few days to make sure everything is OK before moving on to finalising the install. If you are not able to login to the RSSOadmin console

stop the new tomcat service, restart the old one then check the troubleshooting section below

 

Finalising

If you have been testing for a few days and have not come across any issues with the new version of Tomcat you can proceed to finalise the install. To do this

 

Windows: Set System Variable JAVA_HOME and or JRE_HOME to the new version of Java (just be aware of any other applications using the old java version) there is no harm in not doing this as the Tomcat service will always use the new one if you ran the service.bat correctly above.

 

You can remove the Tomcat Service from windows by opening a command prompt "cd" in to the old version of Tomcat directory/bin and run "service.bat remove" (fig3)

 

fig3

 

You can then proceed to delete the old tomcat install files.

 

Linux: Set JAVA_HOME and OR JRE_HOME to the version of Java in the user profile. If you are not sure if other applications are using the old version of Java don't change it, just remember you might need to EXPORT JAVA_HOME=NewJavaPath when starting the the tomcat process. If you don't need the files from the old Tomcat version they can be deleted.

 

Troubleshooting

If after starting up the new Tomcat service and you are not able to log in yo the RSSO admin console, the first place to look is in the Tomcat/Logs/catalina.<date>.log file

check for any error messages. A common one from the procedure above would be

 

java.lang.IllegalArgumentException: Illegal character in path at index 12: C:/ProgramFiles/Apache Software Foundation RSSO/apache-tomcat-8.5.23/conf/keystore.p12

at java.net.URI.create(Unknown Source)

at java.net.URI.resolve(Unknown Source)

 

This message indicates that the path to the keystore file is not found. Confirm the path is correct

 

If there are not any errors in the catalina.log file, then the webserver itself has come up correctly. The next step is to look in the Tomcat/logs/rsso.log file for any errors, a common one

from the procedure above is

 

Details: Unable to load class: com.microsoft.sqlserver.jdbc.SQLServerDriver from ClassLoader:java.net.URLClassLoader@19469ea2;ClassLoader:ParallelWebappClassLoader

  context: rsso

  delegate: false

----------> Parent Classloader:

java.net.URLClassLoader@19469ea2

org.apache.naming.NamingContext.lookup(NamingContext.java:856)

 

This usually indicate some of the RSSO library files are missing from the Tomcat/lib directory, confirm you have copied the files from the previous version of Tomcat correctly, the files are

ojdbc6-11.2.0.2.0.jar

postgresql-9.4.1207.jre7.jar

sqljdbc4-4.0.jar

hsqldb-2.3.5.jar

Note if you have installed a future version of RSSO relative to this blog date the versions numbers may have changed.

 

If all these files are in the lib directory, look at the error message in the RSSO.log file, that will usually give you a hint about which lib file is missing, then check the previous version of Tomcat/lib directory for the file name and copy it over.

Share This:

The RSSO application needs to have its own database to function, some of the tables in this database will hold data for authentications such as SAML, LDAP and AR server as well as tables for user sessions and local internal users.

 

There are two ways to create the RSSO database

  • Let the installer create the database/tables (Preferred method)
  • Pre-Create the RSSO_USER user & database before running the installation

 

 

Letting the installer create the tables

 

Create New User Option

The preferred & quickest method of creating the database is to let the installer create the database, for this you will need a privileged account such as "sa" for MSSQL or "system" for Oracle

This account is only used during the installation and will not be required or used again. If possible during the user input portion of the installation ask the DBAs to enter in a privileged account user name & password if they can not share the account details with you (which is usually the case), so its best to have them at hand to enter in the database and password.  This is the fastest and most efficient way to run the RSSO installer. We need a privileged account to create the database, tables and the RSSO database user "RSSO_USER".

During the install you will be asked for the privileged account  when the "Create New User" option is selected (fig1)

 

Fig1. Showing Create new user (for Oracle)

 

Use Existing User Option

Another option you have is to ask the DBA to pre-create the "RSSO_USER" account in the database and use the "Use Existing User" option during the install.

 

For MSSQL: Ask the DBA to create the "RSSO_USER" user and the container database "rsso" its easier to create the container DB along with the user and make the "RSSO_USER" the owner of the "rsso" database, which in turn will give the user "dbo" access to the database (Schema) (fig2). The DBA will need to provide you with the user name, password and database name (in this case "rsso")

 

Fig2. Shows the RSSO_USER and the RSSO database configuration

 

For Oracle: Ask the DBA to create the "RSSO_USER" account in oracle with CONNECT & RESOURCE roles, "Unlimited Quota for the default user table space"  with "Password Expired" not selected (fig3). The DBA will need to provide you with the username, password, SID or Service Name, you will use this as the "SID" or "Service Name" during the install.

 

Fig3. Shows the user creation for the "RSSO_USER" in oracle along with the granted roles

 

After the RSSO_USER has been created, select the "Use Existing User" Option during the RSSO install. The installer will then create the tables for RSSO (fig4)

 

Fig4. Shows oracle used as the database and "Use Exiting User Option" selected for install

 

 

Pre-Creating User & Database Tables Before the Installer Runs

In some environments the only option available is to pre-create the database due to global policies. RSSO provides the files needed to create the database before running the installer. When the install run's it will connect to the DB for verification and only deploy the system files. The following procedure is a DBA function and these instructions should be sent to the DBA to action.

 

Summary of Steps

  • Copy the Disk1/lib/rsso-database-all.jar file from the installer into a temp directory on the local database
  • Create the RSSO database user
  • Create the database.properties file
  • Execute the rsso-database-all.jar file to create the database

 

NOTE: Its important the rsso-database-all.jar file is from the RSSO version you want to install and not from a previous version, so only use the file from the installer version you have downloaded and get the file from the installer, never use a rsso-database-all.jar that has been sent to you unless instructed to by BMC SUPPORT.

 

You will need java 7 and over to be able to complete this process successfully

 

The first thing we need to do is copy the Disk1/lib/rsso-database-all.jar and place it in a folder on the database. In the same folder create an empty file called "database.properties"

Open the "database.properties" file for edit

 

FOR MSSQL:

 

1. The first thing we need to do is create a database called "rsso" then run the following SQL to create te user and assign RSSO_USER as the DB owner. Change the password to meet your policy (highlighted in red)

 

CREATE LOGIN [RSSO_USER] WITH PASSWORD=N'RSSO#Admin#', DEFAULT_DATABASE=[rsso], DEFAULT_LANGUAGE=[us_english], CHECK_EXPIRATION=OFF, CHECK_POLICY=ON

GO

ALTER LOGIN [RSSO_USER] ENABLE

GO

USE [rsso]

GO

EXEC sp_changedbowner 'RSSO_USER'; 

 

The database, user name and passwords are all changeable, the above are the default out of the box values.

 

2. Open the database.properties file and place the following lines in, change the file to reflect your environment

 

database-type=MsSql

db-url=jdbc:sqlserver://localhost:1433;instanceName=MSSQLSEVER;databaseName=rsso;

db-user-id=RSSO_USER

db-password=RSSO#Admin#

 

3. Save the file.

4. Open a command prompt and "cd" to the directory you saved the files in

5. confirm java is in the path and is version 7 and over "java -version"

6. Run the following command to begin the process of creating the tables  "java -jar rsso-database-all.jar database.properties"

 

If everything is successful you will see messages indicating that the tables have been created (fig5). Check in Microsoft SQL server Studio for the tables (see fig xx)

 

Fig5.

 

If there are any failures, check the information is correct in the "database.properties" file and the connection to the database, If the problem is still not resolvable contact BMC Support for further advice.

 

FOR ORACLE:

 

1. The first thing we need to do is create the RSSO database (RSSO_USER) user in the database. Run the following SQL to create the user.  Change the password to meet your policy (highlighted in red)

 

CREATE USER RSSO_USER IDENTIFIED BY RSSO#Admin#;

ALTER USER "RSSO_USER" QUOTA UNLIMITED ON USERS;

GRANT CONNECT, RESOURCE TO RSSO_USER;

COMMIT;

 

The database, user name and passwords are all changeable, the above are the default out of the box values.

 

2. Open the database.properties file and place the following lines in, change the file to reflect your environment

 

database-type=Oracle

db-url=jdbc:oracle:thin:@localhost:1521:orcl

db-user-id=RSSO_USER

db-password=RSSO#Admin#

 

3. Save the file.

4. Open a command prompt and "cd" to the directory you saved the files in

5. confirm java is in the path and is version 7 and over "java -version"

6. Run the following command to begin the process of creating the tables  "java -jar rsso-database-all.jar database.properties"

 

If everything is successful you will see messages indicating that the tables have been created (fig6). Check in Oracle Developer for the tables (see fig7)

 

Fig6.

 

If there are any failures, check the information is correct in the "database.properties" file and the connection to the database, If the problem is still not resolvable contact BMC Support for further advice.

 

After the user and tables have been created, the install of RSSO can continue by using the "Use Existing User" option on the installer.

 

Fig7 Shows the creation of the tables for MSSQL & Oracle (version 9.1 SP4 RSSO)

Filter Blog

By date:
By tag: