New Xton Documentation Center
Xton help has moved. Please visit the current version of this page for the most recent updates. Our new documentation center can be found at help.xtontech.com.
Migrating the XTAM Framework from Java 8 to OpenJDK 11
If you want to migrate from XTAM’s default Java 8 deployment to OpenJDK 11 or to the latest Java 8 version, please read the following FAQ article.
Prerequisites
- An operational XTAM deployment with the latest version. Please update to the latest available version before proceeding.
Considerations
- Each XTAM node that is updated will be offline and inaccessible for the entirety of the migration.
- The user performing the migration will be required to update files and configurations on the XTAM host server. Administrative privileges are required.
- We highly recommend deploying a test instance of XTAM that mirrors your production instance as closely as possible to test the migration (DB type, Federated Sign-In, certificates, MFA/SSO, AD Integration, etc). Once the migration is successful with the test instance you can reproduce the procedure on your production instance.
Please read the entire procedure outlined in the article before beginning. If you have any questions, please contact us.
Step 1. Download Migration Components
Download the latest version of the OpenJDK 11 archive using the AdoptOpenJDK link below to your XTAM host server (Windows or Linux) and extract the archive to your $XTAM_HOME directory. The extracted archive will create a new directory with a name resembling $XTAM_HOME/jdk-11.x.x.
Download the OpenJDK 11 compatible XTAM Federated Sign-in Module from the below location. Once downloaded, extract this zip to a temporary location on the XTAM host server. Do not extract this archive to $XTAM_HOME. Please note that if you are not using the Federated Sign-in Module, then you can skip this step.
Download the XTAM JDK Update Pack to your XTAM host server (Windows and Linux) and extract the archive to your $XTAM_HOME directory. The extracted archive will create a new directory with the name $XTAM_HOME/pam-jdk11-pack.
Step 2. Stop the XTAM Services
Once the services are stopped, XTAM will become inaccessible until the entire migration is completed.
For Windows deployments, stop the PamManagement and PamDirectory services:
-
net stop PamManagement
-
net stop PamDirectory
For Linux deployments, stop the pammanager and pamdirectory services:
-
service pammanager stop
-
service pamdirectory stop
Step 3. JRE to OpenJDK Migration
Replace the existing XTAM jre directory.
- Rename $XTAM_HOME/jre to $XTAM_HOME/jre.8
- Rename $XTAM_HOME/jdk-11.x.x to $XTAM_HOME/jre
Copy JRE 8 Certificates and Configurations
- Copy the file $XTAM_HOME/jre.8/lib/security/cacerts to $XTAM_HOME/jre/lib/security overwriting the current file.
Note: This step will migrate the existing certificates loaded into the previous XTAM deployment including ADS, AD connection certificates as well as SSL certificate for CAS integration.
Update XTAM container files.
- Copy all files from $XTAM_HOME/pam-jdk11-pack/bin to $XTAM_HOME/bin overwriting the current files.
- (Linux only) Copy all files from $XTAM_HOME/pam-jdk11-pack/web/bin to $XTAM_HOME/web/bin
Note: This step resolves two issues with the compatibility between Java versions: deprecated endorsed folder and endpoint identity verification for LDAPS integrations.
(Windows only) Redeploy Service
- From an administrative command prompt, navigate to $XTAM_HOME and run the command:
bin\ServiceManagement.cmd remove
- When the above command completes successfully, run the command:
bin\ServiceManagement.cmd install
Redeploy the Federated Sign-In Module. If you are not using the Federated Sign-in Module, you can skip this step.
- Move $XTAM_HOME/web/webapps/cas to $XTAM_HOME
- Move $XTAM_HOME/web/webapps/cas.war to $XTAM_HOME
- Copy the extracted cas.war file from step (1b) to $XTAM_HOME/web/webapps
Note: If you made any customizations to the Federated Sign-in Module, they may be lost and need to be redone after the migration is complete.
Update External Database Dependencies. If you are using the Internal XTAM database, then this step can be skipped.
- Navigate to $XTAM_HOME/web/webapps/xtam/WEB-INF/lib
- Select and copy all the files that start with jaxb- and are of extension .jar (i.e. jaxb-*.jar) to $XTAM_HOME/web/lib
Step 4. Start the XTAM Services
For Windows deployments, start the PamManagement and PamDirectory services:
-
net start PamManagement
-
net start PamDirectory
For Linux deployments, start the pammanager and pamdirectory services:
-
service pammanager start
-
service pamdirectory start
Step 5. Test and Verify
Once the services come back online, you should now login and thoroughly test the system. This should include, but not be limited to:
- Login with all applicable types of user accounts; Local, AD/LDAP, MFA and SSO
- Accessing existing records (and creating new records) in both the Record List and Personal Vault, including the unlock action
- Creating remote sessions
- Executing jobs and tasks (on demand and scheduled)
- Viewing and exporting reports
To confirm the migration, open the file $XTAM_HOME/web/logs/catalina.currentDate.log and search for JVM Version:. The displayed version should be 11.0.9.1+1 or the latest version that was downloaded.
Rollback
If the migration or testing fails and you need to rollback to the previous Java 8 framework, then follow this procedure. If you do not need to rollback, proceed to the next section.
Stop the XTAM services as described earlier
Rename the new $XTAM_HOME/jre to $XTAM_HOME/jre.11
Rename the previous $XTAM_HOME/jre.8 back to $XTAM_HOME/jre
Delete the new $XTAM_HOME/web/webapps/cas
Delete the new $XTAM_HOME/web/webapps/cas.war
Move the previous $XTAM_HOME/cas back to $XTAM_HOME/web/webapps/cas
Move the previous $XTAM_HOME/web/webapps/cas.war back to $XTAM_HOME/web/webapps/cas.war
Start the XTAM services as described earlier
When the services come back online, XTAM should be using the previous framework. You should now perform the testing and validation again.
Step 6. Cleanup
After all the testing is complete and the system is fully operational, you may remove the following directories:
- $XTAM_HOME/jre.8
- $XTAM_HOME/pam-jdk11-pack
- $XTAM_HOME/cas
- $XTAM_HOME/cas.war
- Extracted pam-cas.zip directory