Upgrading EJBCA

This section provides information on upgrading from your current version to a later version of EJBCA.

Also see the EJBCA Upgrade Notes for the version you plan to upgrade to (and any version in between).

Upgrade Strategy

When EJBCA is deployed with external Registration Authorities (RAs) and external Validation Authorities (VAs) using peering, the strategy for upgrading is to start with the external EJBCA nodes first. After the external EJBCA nodes are upgraded, upgrade the EJBCA CA nodes. Upgrading the external EJBCA nodes first ensures the CA node uses the Peering protocol version of the CA instance. Therefore if the CA is upgraded first it would use a newer version of the Peering protocol that could be incompatible with the external RA/VA EJBCA nodes. Remember the phrase outside-in when upgrading EJBCA with external RA/VA nodes.

Upgrade Instructions

When upgrading or changing a configuration setting in a properties file, it is not required to fully re-install EJBCA or re-configure the application server. Instead, deploy a new EJBCA application (ejbca.ear) to the application server using the ant deployear command.

Always make a backup of the database before upgrading. The database contains all CA data, and in case you need to roll back an upgrade you can restore the database backup. For information on how to back up and restore an EJBCA installation, see Backup and Restore.

Follow the steps below to upgrade from one version of EJBCA to a new version.

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 changes (if there are any) from *.properties.sample into your *.properties.
   
   

3. Copy the content of the p12 directory from the earlier installation and run the following command with the new version:

   BASH

   $ ant deployear

   Note that the command deployear deploys a new ejbca.ear to the application server, not performing the same configuration work as the deploy command.

   

   Wildfly 24 and later versions support the PKCS12 type of 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" (using the EJBCA RA UI, for example), renew the keystore, and configure the following in the EJBCA configuration file web.properties: httpsserver.tokentype=P12.

4. If you have switched application server (a new version, or just unpacked a fresh installation of it), you need to run the following additional command to copy the TLS keystores over to the new server:

   BASH

   $ ant deploy-keystore
   

5. You also need to configure TLS for your application server. See the application server specific instructions for the installation, for example for WildFly on Application Servers.
   
   

6. All database upgrades require CREATE and ALTER TABLE privileges in addition to the usual privileges SELECT, UPDATE, INSERT, and DELETE. The SQL executed by database upgrades code is available in src/upgrade/<oldversion>_<newversion>/<oldversion>_<newversion>-upgrade-<database>.sql. For example, src/upgrade/832_900/832_900-upgrade-oracle.sql. For MariaDB, use the *.mysql.sql upgrade scripts.

ejbca-custom

To ease upgrades and allow keeping your personal configurations from a version to another, you can store your personal EJBCA modifications in the ejbca-custom folder. Your modifications will automatically overwrite any existing files found in the EJBCA_HOME directory before executing an ant command. For more information, see Modifying EJBCA.

Upgrade Paths

Use the table below to determine the most efficient upgrade path from your current version to the later versions of EJBCA and see the Notes below for details.

Also see the EJBCA Upgrade Notes for the version you plan to upgrade to (and any in between).

Notes

Technology Jumps

Upgrading past these technology jumps requires not only upgrading EJBCA, but also the underlying software such as the JDK and the application server.  

• EJBCA 9.0: JEE8 → JEE10: EJBCA 9 supports running on Java 17. EJBCA 9.0 is based on JEE10/Jakarta10, which limits WildFly support to WF32+. For more information about technology upgrades, see EJBCA 9.0 Release Notes.
• EJBCA 8.0: JEE7 → JEE8: EJBCA 8 supports running on Java 17 in addition to Java 11. EJBCA 8.0 is based on JEE8/Jakarta8, which limits WildFly support to WF24 and WF26. For more information about technology upgrades, 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 moving to JDK8
• EJBCA 6.4.0: JEE5 → JEE6: With the move to runtime version JDK7, it can no longer be deployed to application servers based on JDK6 such as JBoss versions 4 and 5. The latest version that can still run under JDK6 is the EJBCA 6.3.2.6 intermediate release. Thus, EJBCA 6.3.2.6 and earlier can be run on JBoss 5.1.0.GA server (JEE5), while later versions require an upgrade of the JDK and application server, JDK8 and JBoss EAP 7 or WildFly 10 are recommended.
• EJBCA 6.4.0: JDK6 → JDK7: End of support for legacy runtime version JDK6 and moving to JDK7.

Upgrade Process Changes

• As of EJBCA 6.8.0, you can perform post-upgrades from the Admin Web. When a post-upgrade is required, the System Configuration menu option System Upgrade is available.