UrbanCode

IBM UrbanCode Deploy: IBM Java 8 EOS and how to migrate

By Osman Burucu posted Wed October 20, 2021 11:16 AM

  
In the IBM UrbanCode Deploy 7.2 Announcement the information was given, that IBM Java 8 will be end of support in September 2022. This also means that no IBM Java (JRE/JDK) will be bundled with IBM UrbanCode Deploy anymore.

If you were using the bundled JRE you need to migrate other (supported) runtimes (please have a look at the documentation or software compatibility report first). There are several available:

Great, nothing as easy than installing a new JRE. Well, not so fast.

IBM UrbanCode Deploy uses the java keystore for encryption of secured properties. So when you just replace the existing IBM JRE with a another one this keystore will not be decryptable.
In the IBM UrbanCode Deploy documentation there is a specific section for upgrading the JRE of servers. There is one interesting statement: "The new JRE must be from the same vendor as the current JRE. If you want to change the JRE vendor, contact support to obtain the KeystoreConverter tool."

In this case just open a new support case using the IBM support page (see Help document here) and after a short period of time you will get back the information how to access this tool.

In the mean time please do your backup (and it is always a good practice to verify that a restore works) or your IBM UrbanCode Deploy server and Agents.

As soon as you have the converter you can start using it. I have here in a short form added the steps needed:
Note:
I have installed UrbanCode Deploy Server under /opt/ucd/server and the Agent under /opt/ucd/agent.
So the placeholders serverinstallationdirectory will be /opt/ucd/server and agentinstallationdirectory will be /opt/ucd/agent
The environment variables OLDJAVA_HOME points to /usr/lib/jvm/jre and the new Java JRE uses NEWJAVA_HOME under /usr/lib/newjvm/jre

Ensure that the new JRE and the old JRE are on the machine!

Steps needed for the server
  1. Stop the UrbanCode Deploy Server
  2. Copy KeystoreConverter.jar to <serverinstallationdirectory>/appdata/conf/
  3. Switch to this directory and backup the existing encryption.keystore (f.e. copy to other location)
  4. Run $OLDJAVA_HOME/bin/java -jar KeystoreConverter.jar export encryption.keystore keystorepass enckeystore.zip
  5. delete <serverinstallationdirectory>/appdata/conf/encryption.keystore as we will create a new one
  6. Run $NEWJAVA_HOME/bin/java -jar KeystoreConverter.jar import encryption.keystore keystorepass enckeystore.zip
  7. Update the following files to point to the new Java
    1. <serverinstallationdirectory>/bin/set_env
    2. <serverinstallationdirectory>/bin/classpath.conf
    3. <serverinstallationdirectory>/conf/server/installed.properties
  8. Restart the UrbanCode Deploy Server

The procedure for the agent is similar to the server, again take care of the variables.
Steps for UCD Agent
  1. Stop the UrbanCode Deploy Agent
  2. Copy KeystoreConverter.jar to <agentinstallationdirectory>/appdata/conf/
  3. Switch to this directory and backup the existing encryption.keystore (f.e. copy to other location)
  4. Run $OLDJAVA_HOME/bin/java -jar KeystoreConverter.jar export encryption.keystore keystorepass enckeystore.zip
  5. delete <agentinstallationdirectory>/appdata/conf/encryption.keystore as we will create a new one
  6. Run $NEWJAVA_HOME/bin/java -jar KeystoreConverter.jar import encryption.keystore keystorepass enckeystore.zip
  7. Update the following files to point to the new Java
    1. <agentinstallationdirectory>/bin/configure-agent
    2. <agentinstallationdirectory>/bin/agent
    3. <agentinstallationdirectory>/conf/agent/installed.properties
  8. Restart the UrbanCode Deploy Agent

Rollback
If something goes wrong you need to do a rollback. The rollback procedure is the following:
  1. Stop the Server and the Agent
  2. Restore the encryption.keystore from backup into <agent or server installationdirectory>/appdata/conf/ overwriting the newly created one
  3. Update the files to point back to old java. See Steps 7. from above.
  4. Restart the Server and the Agent

Windows Service
For the Windows Service you need to delete the service and recreate it for getting the Java change.
 
Certificates
Also, the certificates need to be copied into the keystore of the new java installation. To do that you need to export the certificates from $OLDJAVA_HOME/jre/lib/security/cacerts and import it to $NEWJAVA_HOME/jre/lib/security/cacerts

Here is an example from the KeystoreConverter documentation:
# exporting
cd $OLDJAVA_HOME/jre/lib/security
$OLDJAVA_HOME/bin/keytool -export -alias <alias name> -keystore cacerts -file <alias name>.cert

# importing
cd $NEWJAVA_HOME/jre/lib/security
$NEWJAVA_HOME/bin/keytool -import -alias <alias name> -keystore cacerts -file <alias name>.cert

You will find also a document in the KeystoreConverter Zip file from which i took the parts about how to use this tool.
#Featured-area-2
#Featured-area-2-home
0 comments
503 views

Permalink