Updating Existing XTAM Deployment to OpenJDK 13 Framework and Tomcat 9.0 WEB Container

Starting December 2019 XTAM Server ships with OpenJDK 13 Framework and Apache Tomcat 9.0 WEB container. While all new installations use these new components as a default option, existing deployments should be updated manually.

 

If you want to migrate from current XTAM Server deployment to OpenJDK 13 (or to the other Java build) and Apache Tomcat 9.0, 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. Appropriate 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

  1. Download OpenJDK 13 framework packaged for XTAM Server for Windows or Linux hosts to your XTAM host server and extract archive outside the $XTAM directory.

    2.  

    Alternatively, download the latest version of OpenJDK specific for Windows or Linux platforms and extract it outside the $XTAM directory. Rename top folder to jre to match the name in XTAM distributions.

     

    Note: The advantage of using complete OpenJDK framework is availability of Java diagnostics tools to analyze XTAM operational characteristics if needed. The advantage of using packaged for XTAM frameworks is to minimize deployment footprint.

  2. Download Apache Tomcat 9.0 WEB container packaged for XTAM Server to your XTAM host server and extract archive outside the $XTAM directory.

  3. Download the OpenJDK 11+ compatible XTAM Federated Sign-in Module from the below location. Please note that if you are not using the Federated Sign-in Module, then you can skip this step.

  4. 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-jdk13-pack.

 

Step 2. Stop the XTAM Services

Once the services are stopped, XTAM will become inaccessible until the entire migration is completed.

 

  1. For Windows deployments, stop the PamManagement and PamDirectory services:
    2. Copy 
    net stop PamManagement
    Copy 
    net stop PamDirectory

  1. For Linux deployments, stop the pammanager and pamdirectory services:

    Copy 
    service pammanager stop
    Copy 
    service pamdirectory stop

     

Step 3. Updating OpenJDK and WEB Container Version

  1. Replace the existing XTAM jre directory.

    • Rename $XTAM_HOME/jre to $XTAM_HOME/jre.old folder

    • Move jre directory downloaded in the Step 1a to $XTAM_HOME/jre

  2. Copy existing XTAM Certificates and Configurations

    • Copy the file $XTAM_HOME/jre.old/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.

  3. Update WEB Container

    • Copy existing $XTAM_HOME/web directory to the $XTAM_HOME/web.old to create a backup.

    • Copy all files from the directory web/bin downloaded in the Step 1b to $XTAM_HOME/web/bin

    • Copy all files from the directory web/lib downloaded in the Step 1b to $XTAM_HOME/web/lib.

  4. Update XTAM container files. This step should be performed for existing deployments that were done before March, 2019. All deployments performed after March, 2019 already include modifications in these files.

    • Copy all files from $XTAM_HOME/pam-jdk13-pack/bin to $XTAM_HOME/bin overwriting the current files.

    Note: This step resolves two issues with the compatibility between Java versions: deprecated endorsed folder and endpoint identity verification for LDAPS integrations.

  5. (Windows only) Redeploy Service. This step should be performed for existing deployments that were done before March, 2019. All deployments performed after March, 2019 already include these modifications.

    • From an administrative command prompt, navigate to $XTAM_HOME and run the command:

      Copy 
      bin\ServiceManagement.cmd remove

    • When the above command completes successfully, run the command:

      Copy 
      bin\ServiceManagement.cmd install

  6. Redeploy the Federated Sign-In Module. If you are not using the Federated Sign-in Module, you can skip this step. This step should be performed for existing deployments that were done before March, 2019. All deployments performed after March, 2019 already include modifications in these files.

    • Copy the downloaded cas.war from step (1c) 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.

     

Step 4. Start the XTAM Services

  1. For Windows deployments, start the PamManagement and PamDirectory services:
    2. Copy 
    net start PamDirectory
    Copy 
    net start PamManagement

  2. For Linux deployments, start the pammanager and pamdirectory services:

    Copy 
    service pamdirectory start
    Copy 
    service pammanager 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, check Framework and WEB Container versions on the bottom of Administration / Settings / Database screen. The displayed versions should match version that was downloaded.

 

Rollback

If the migration or testing fails and you need to rollback to the previous Java framework and a WEB Container, 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.new
  • Rename the previous $XTAM_HOME/jre.old back to $XTAM_HOME/jre
  • Rename the new $XTAM_HOME/web to $XTAM_HOME/web.new
  • Rename the previous $XTAM_HOME/web.old back to $XTAM_HOME/web
  • 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.old
  • $XTAM_HOME/web.old
  • $XTAM_HOME/pam-jdk13-pack
  • Files downloaded in Step 1 and extracted archives