Upgrade EJBCA Software Stack

This describes how to upgrade an existing EJBCA Software Stack installation to a later version.

For general EJBCA upgrade information about foundational concepts and upgrade strategy applicable to all deployment types, refer to Upgrading EJBCA.

Review the EJBCA Upgrade Notes for the target release as well as all intermediate releases.

Prerequisites

Before you begin:

• Ensure you have a complete database backup. The database contains all CA data and is required for rollback. For details, see Backup and Restore.

• If the upgrade includes database schema changes:

  • Verify that the database user has the privileges CREATE and ALTER TABLE in addition to SELECT, UPDATE, INSERT, and DELETE.

  • Locate the SQL upgrade scripts under:
    src/upgrade/<oldversion>_<newversion>/<oldversion>_<newversion>-upgrade-<database>.sql
    (For MariaDB, use the *.mysql.sql scripts).

Upgrade Procedure for a Single Node

To review more generic EJBCA upgrade strategies, refer to the general EJBCA upgrade information.

Upgrading or changing configuration settings does not require a full reinstallation of EJBCA or a reconfiguration of the application server. Deploy a new EJBCA application (ejbca.ear) to the application server using the ant deployear command.

Make sure you have completed the database backup as described in the Prerequisites before proceeding with the upgrade steps.

Follow the steps below.

1. Copy conf/*.properties from the earlier installation.
   This step is not required if you are using an ejbca-custom directory (see ejbca-custom below).

2. Merge any changes from *.properties.sample into your *.properties files.

3. Copy the entire p12 directory from the earlier installation.

4. Deploy the new version:

   BASH

   $ ant deployear

   The deployear command deploys a new ejbca.ear to the application server. It does not perform the configuration steps executed by the deploy command.

5. Configure TLS keystore - WildFly supports PKCS12 keystore (.p12) files:

   • To continue to use the JKS format, configure the JKS keystore type and file name in the TLS configuration.

   • To switch to the PKCS12 format:

     • Change the keystore type for the end entity "tomcat" (for example, using the EJBCA RA UI).

     • Renew the keystore, see Renew Keystore.

     • Set httpsserver.tokentype=P12 in the EJBCA configuration file web.properties.

6. If you have changed or replaced the application server (a new version or a fresh unpacked instance), run the following to copy the TLS keystores to the new server:

   BASH

   $ ant deploy-keystore

   Then configure TLS for the application server. Refer to the application-server-specific installation instructions (for example, WildFly) in Application Servers.

7. If this upgrade includes database schema changes, ensure the database user has the required privileges and that the SQL upgrade scripts are accessible as described in Prerequisites.

8. If required for the version, perform a post-upgrade in EJBCA under System Configuration>System Upgrade.

ejbca-custom

The ejbca-custom directory allows you to preserve local modifications across upgrades. Files in ejbca-custom automatically overwrite corresponding files in EJBCA_HOME before any ant command is executed. For details, see Modifying EJBCA.

Upgrade Paths

Use the table below to determine a suitable upgrade path. Review the EJBCA Upgrade Notes for the target version and all intermediate versions.

Technology Jumps

Upgrading across the following transitions requires upgrading both EJBCA and underlying components such as the JDK and application server.

• EJBCA 9.0: JEE8 → JEE10: Runs on Java 17. Based on JEE10/Jakarta10, which limits WildFly support to WF32+. See EJBCA 9.0 Release Notes.

• EJBCA 8.0: JEE7 → JEE8: Runs on Java 11 and Java 17, which limits WildFly support to WF24 and WF26. See EJBCA 8.0 Release Notes.

• EJBCA 7.0.0: JEE6 → JEE7: With the end of JDK7 support, support of JEE6 reliant application servers ceases as well. Minimum supported version of JBoss is EAP7/WildFly 10. 

• EJBCA 7.0.0: JDK7 → JDK8: End of support for legacy runtime version JDK7 and move to JDK8

• EJBCA 6.4.0: JEE5 → JEE6: Requires JDK7 and application servers based on JDK7. JBoss 4 and 5 (JEE5, JDK6) are no longer supported. EJBCA 6.3.2.6 is the last version that runs on JDK6 and JBoss 5.1.0.GA. For later versions, JDK8 and JBoss EAP7 or WildFly 10 are recommended.

• EJBCA 6.4.0: JDK6 → JDK7: End of support for legacy runtime version JDK6 and moving to JDK7.