Preparing Jazz Authorization Server for server rename

If you are using a Jazz Authorization Server in your environment, you must complete additional steps for a server rename.

Setting up a test staging environment with Jazz SSO

If Jazz SSO is implemented in your production environment, you can create a staging environment that uses the production data. For details, see, Setting up a test staging environment with production data. To import the production data into a staging environment, you must complete the following steps:
  • Set up a new Jazz Authorization Server for use in your staging environment.
  • Ensure that the Jazz Authorization Server is configured in the production environment to use a database server for data, and not the local Derby database.
Note: You cannot use the same Jazz Authorization Server in your staging and production environments.

For instructions on creating a staging environment that uses the production data, see Setting up a test staging environment with production data. Additionally, you must complete the following actions:

Additional steps to be completed in the production environment

When you back up the production databases, you must back up the OAUTH database that is used by the Jazz Authorization Server. Copy the OAUTH database to the staging database server along with the other databases. See, Configuring your deployment after a database server move.

You must export the Jazz Authorization Server client configuration on Linux and complete the following steps:
  1. Log in to the production Jazz Authorization Server.
  2. Run the following command:
    cd /opt/IBM/JazzAuthServer/cli 
    ./lsclient -u adminUser:adminPassword>& prodjas.backup

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

Additional steps to be performed in your staging environment
When you restore the backed up databases in the production environment, you must also restore the configuration database for Jazz Authorization Server. After restoring the databases, delete the entries from the OAUTH20CACHE table. This table contains cached user information, which is encrypted using keys on the production Jazz Authorization Server. These steps clear the cache and allow the staging Jazz Authorization Server to do its own encryption. For Db2, run the following commands if the Jazz Authorization Server database was called OAUTH2DB:
db2 connect to OAUTH2DB
db2 delete from OAUTHDBSCHEMA.OAUTH20CACHE
Before importing the mapping file, you must temporarily disable Jazz SSO on your staging environment. 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

Moving a pilot or full production deployment with Jazz SSO

You can rename a small pilot or full production deployment. For instructions on creating a staging environment that uses the production data, see Moving a pilot or full production deployment by using server rename. Additionally, you must complete the following actions:

Additional steps to be performed in the source environment

When you back up the source databases, you must back up the configuration database that is used by the Jazz Authorization Server. Copy that database to the target database server along with the other databases. See, Configuring your deployment after a database server move.

You must also export the Jazz Authorization Server client configuration on Linux by performing the following steps:
  1. Log in to the production Jazz Authorization Server.
  2. Run the following command:
    cd /opt/IBM/JazzAuthServer/cli 
    ./lsclient -u adminUser:adminPassword>& prodjas.backup

If you want to move to a new Jazz Authorization server, copy the prodjas.backup file to the /opt/IBM/JazzAuthServer/cli directory on the new Jazz Authorization Server. If you want to use the same Jazz Authorization Server, save the prodjas.backup file.

Additional steps to be performed in your target environment
When you restore the backed up databases in the target environment, you must also restore the configuration database for Jazz Authorization Server. After restoring the databases, delete the entries from the OAUTH20CACHE table. For Db2, run the following commands if the Jazz Authorization Server 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 Jazz Authorization Server. These steps clear the cache and allow the staging Jazz Authorization Server to do its own encryption.

Before importing the mapping file, you must temporarily disable Jazz SSO on your staging environment. 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

Creating a staging environment that is a subset of a production environment

You can create a staging environment that only has a subset of the applications available in the production environment. In this process you mask the URLs in the staging environment so that they map to nonexistent hostnames.

If there are any CLM applications in the production environment that are sharing a JTS, you must unregister the applications that are present in the production environment but are not available in the staging environment. See, Repository tools command to unregister an application. You must unregister the applications before you import the mapping file on the staging JTS. If you don't unregister the applications, the server rename verification process gets stuck trying to communicate with the missing applications and does not get completed.

If you want to create a staging environment that does not include the production /rm application (rm1.production.example), unregister the rm application on your staging JTS before importing the mapping file that uses the following command:
./repotools-jts.sh -unregisterApp appName=/rm teamserver.properties=conf\jts\teamserver.properties

If you have configured one or more Data collection components (DCC) to populate a data warehouse from your applications, remove the missing applications from the list of DCC data sources in the staging environment. The server rename process maps the URLs in the Resource Group Configuration UI to dummy URLs, but the staging system encounters errors when you run the data collection jobs. These errors are harmless but you can remove the dummy data sources to eliminate them.

Resource group configuration screen
Note:

When you map the production URLs to dummy staging URLs, do not use underscores in the dummy hostnames. It results in failure when you import the mappings file.

Attempts to use the masked applications generate errors. You might see unexpected behavior in several cases:
  • You can see links to artifacts in the masked applications but encounter an error when you click the links.
  • The Report Builder lists masked applications and reports from the data warehouse that might return artifacts from the masked application.
    Note: The URLs for those artifacts are not renamed. If you click them, you are directed to the production system, unless you have updated your client hosts file to prevent access to the production systems.

Clarifications when Report Builder is part of a server rename

The Report Builder stores its information on the Report Builder server within the conf/rs/db directory. It does not use a relational database and there is no database table on your database server. You must copy the contents of the conf/rs/db directory from your source server to your target server.

The Report Builder stores information about the data sources that it reports against in this local directory. If you have moved your data warehouse from one database to another, as part of your server rename, you must manually update the names of the database servers after completing the server rename verification process and ensuring that your servers are running.

Go to your Report Builder -> Admin page and select Data Sources. Open each data source and update the hostname for the new database by editing the Data source location field. Test the connection and if it is successful, save your changes.

The data source screen of report builder