Additional documentation for server rename

Authors: VaughnRokosz
Build basis: 6.x

This page expands on the server rename documentation found in the Knowledge Center. It will cover:

• How to do a server rename if the Jazz Authorization Server is in use
• What do to when creating a staging environment that is a subset of a production environment
• How to deal with the Report Builder component of the Jazz Reporting Server

Server rename and the Jazz Authorization Server

Jazz Security Architecture single sign-on (SSO) is an alternate single sign-mechanism that can be used instead of Kerberos SSO, IBM WAS SSO, or Apache Tomcat server SSO. If you have adopted the Jazz Security Architecture, then you need take some additional steps during the server rename process:

• You must disable the Jazz SSO feature before you import the mappings file
• You must manually update URLs in the Jazz Authorization Server database
• After the server rename verification process completes, you must re-enable the Jazz SSO feature and update references to the Jazz Authorization Server

Scenario: Setting up a test staging environment with Jazz SSO

One of the supported server rename scenarios is to create a staging environment using production data. If your production environment has adopted Jazz SSO, then you must do the following if you plan to import your production data into a staging environment:

• Set up a new Jazz Authorization Server for use in your staging environment
• Be sure you have configured your production Jazz Authorization Server to use a database server for persistent data, and not the local Derby database

You will not be able to share a single Jazz Authorization Server between your staging and production environments.

The detailed step-by-step instructions for creating a staging environment using production data are in the on-line help. The changes to those instructions to account for the Jazz Authorization server are listed below.

Additional steps to take in your production environment

When backing up your production databases (step 2), you will need to back up the OAUTH database used by the Jazz Authorization Server. Copy the OAUTH database to your staging database server along with the other databases as described in Moving the CLM database.

You will also need to export the JAS client configuration, using the following procedure (on Linux):

Log in to the production JAS server
cd /opt/IBM/JazzAuthServer/cli 
./lsclient -u adminUser:adminPassword >& prodjas.backup

Copy prodjas.backup to the /opt/IBM/JazzAuthServer/cli directory on your staging Jazz Authorization Server.

Additional steps to take in your staging environment

When restoring the database backups in production (step 3b), you will need to restore the configuration database for JAS. After restoring, you will need to delete the entries in the "OAUTH20CACHE" table. On DB2, you would do this as follows (if the JAS database was called "OAUTH2DB"):

db2 connect to OAUTH2DB
db2 delete from OAUTHDBSCHEMA.OAUTH20CACHE

This table contains cached user information which is encrypted using keys on the production JAS. These steps are just clearing the cache and allowing the staging JAS to do its own encryption.

Prior to importing the mapping file in step 3e, you must temporarily disable Jazz SSO on your staging systems.

For jts, ccm, dcc, gc, qm, relm and rm, edit (or add) the following line in teamserver.properties:

com.ibm.team.repository.servlet.sso_authenticationActivated=false

For rs, edit (or add) the following line in app.properties:

authenticationEnabled=false

In step 4, if you are using the IBM HTTP Server, remember to include the staging Jazz Authorization Server in your other updates.

After you complete the server rename verification process (step 8), you must re-enable the Jazz Authorization server and manually change any host references to the production JAS so that they point to the staging JAS.

To re-enable the Jazz SSO, first shut down all of your staging systems. For jts, ccm, dcc, gc, qm, relm and rm, edit (or add) the following line in teamserver.properties:

com.ibm.team.repository.servlet.sso_authenticationActivated=true

For rs, edit (or add) the following line in app.properties:

authenticationEnabled=true

Next, log into your staging JAS, and edit the client backup file generated on the production JAS via lsclient. This file is in JSON format, and will contain an entry for each production application. You must change the host names in this file to reflect the new host names which you have assigned to staging. This is a manual step - the server rename process in 6.0.x does not automatically rename the JAS URLs. Be sure to update all of the URLs; there will be multiple entries in each client section.

Here is an example client entry - this one is for the JTS. The entries highlighted below are from a test production server, and would need to be edited to point at the staging JTS. Repeat this for all client entries.

After you have edited the client file to point to your staging URLs, load it into the Jazz Authorization server as follows:

Log in to your staging JAS.
Make sure JAS is running.
cd /opt/IBM/JazzAuthServer/cli
./ldclient -u adminUser:adminPassword prodjas.backup

Finally, you must manually update application properties files to point to your staging JAS. For jts, ccm, dcc, gc, qm, relm and rm, edit (or add) the following line in teamserver.properties:

com.ibm.team.repository.servlet.sso_as=https\://StagingJAS\:9643/oidc/endpoint/jazzop

For rs, edit (or add) the following line in app.properties:

jsa.auth.server.url=https\://StagingJAS.com\:9643/oidc/endpoint/jazzop

(In the above examples, replace "StagingJAS.com" with the host name of your staging JAS, and change to port to match your staging JAS configuration).

Now you can start your staging CLM applications.

Scenario: Moving a pilot or full production deployment with Jazz SSO

One of the supported server rename scenarios is to move a pilot or production deployment. The detailed steps are provided in the on-line help. The changes to those instructions to account for the Jazz Authorization server are listed below.

Additional steps to take in your source environment

When backing up your source databases (step 2), you will need to back up the configuration database used by the Jazz Authorization Server. Copy that database to your target database server along with the other databases as described in Moving the CLM database.

You will also need to export the JAS client configuration, using the following procedure (on Linux):

Log in to the JAS server
cd /opt/IBM/JazzAuthServer/cli 
./lsclient -u adminUser:adminPassword >& prodjas.backup

If you are moving to a new Jazz Authorization server, copy prodjas.backup to the /opt/IBM/JazzAuthServer/cli directory on your new Jazz Authorization Server.

Additional steps to take in your target environment

When restoring the database backups as part of moving your databases, you will need to restore the configuration database for JAS. After restoring, you will need to delete the entries in the "OAUTH20CACHE" table. On DB2, you would do this as follows (if the JAS database was called "OAUTH2DB"):

db2 connect to OAUTH2DB
db2 delete from OAUTHDBSCHEMA.OAUTH20CACHE

This table contains cached user information which is encrypted using keys on the source JAS. These steps are just clearing the cache and allowing the target JAS to do its own encryption. This step is not necessary if you are not moving to a new Jazz Authorization Server, but it won't do any harm.

Prior to importing the mapping file in step 3a, you must temporarily disable Jazz SSO on your staging systems.

For jts, ccm, dcc, gc, qm, relm and rm, edit (or add) the following line in teamserver.properties:

com.ibm.team.repository.servlet.sso_authenticationActivated=false

For rs, edit (or add) the following line in app.properties:

authenticationEnabled=false

After you complete the server rename verification process (step 8), you must re-enable the Jazz Authorization server and manually change any host references to the source JAS so that they point to the target JAS. You can skip this step if you did not move to a new JAS.

To re-enable the Jazz SSO, first shut down all of your target systems. For jts, ccm, dcc, gc, qm, relm and rm, edit (or add) the following line in teamserver.properties:

com.ibm.team.repository.servlet.sso_authenticationActivated=true

For rs, edit (or add) the following line in app.properties:

authenticationEnabled=true

Next, log into your JAS, and edit the client backup file generated on the source JAS via lsclient. This file is in JSON format, and will contain an entry for each Jazz application. You must change the host names in this file to reflect the new host names which you have assigned to your target systems. This is a manual step - the server rename process in 6.0.x does not automatically rename the JAS URLs. Be sure to update all of the URLs; there will be multiple entries in each client section.

Here is an example client entry - this one is for the JTS. The entries highlighted below are from a source JTS, and would need to be edited to point at the new JTS. Repeat this for all client entries.

After you have edited the client file to point to your staging URLs, load it into the Jazz Authorization server as follows:

Log in to your JAS.
Make sure JAS is running.
cd /opt/IBM/JazzAuthServer/cli
./ldclient -u adminUser:adminPassword prodjas.backup

Finally, if you changed the name of the Jazz Authorization Server as part of the move, you must manually update application properties files to point to your new JAS. For jts, ccm, dcc, gc, qm, relm and rm, edit (or add) the following line in teamserver.properties:

com.ibm.team.repository.servlet.sso_as=https\://NewJAS\:9643/oidc/endpoint/jazzop

For rs, edit (or add) the following line in app.properties:

jsa.auth.server.url=https\://NewAS.com\:9643/oidc/endpoint/jazzop

(In the above examples, replace "NewJAS.com" with the host name of your new JAS, and change to port to match your JAS configuration).

Now you can start your moved CLM applications.

Additional steps when creating a staging environment that is a subset of a production environment

Clarifications when Report Builder is part of a server rename

Related topics: Deployment web home, Deployment web home

External links:

• IBM

Additional contributors: TWikiUser, TWikiUser