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).

Concepts

Upgrade Steps

Barring any underlying technology changes (such as changing the JDK or Application Server due to a technology leap), upgrading EJBCA is essentially as simple as deploying the new EAR file to your application server. Modifications of data happen in three discreet steps:

Label	Description
Lazy Upgrade	When data needs to be added to an object as a result of new functionality, but that data only needs to be present when that data is utilized, it will be added as part of a lazy upgrade, meaning that the data will be added the next time that object is referenced as part of normal operations. This is the preferred method of upgrading database objects in EJBCA.
Upgrade	For data which needs to be processed and rolled out holistically, this action will be performed upon deploying the new EAR to the application server. EJBCA tracks the current version of the database, and if it detects that the data in the database is older than the deployed version the upgrade procedure will be run automatically. Between this step and the next one the data in EJBCA’s database is still compatible with both the current and previous version, for reasons that will be explained under the Zero Downtime section.
Post Upgrade	After performing the Upgrade step, EJBCA may (but not for all releases) prompt administrators to perform a post-upgrade. This step is manual (again for reasons explained under the Zero Downtime section). After performing post-upgrade, the data in the database will no longer be compatible with the previous version of EJBCA.

Until post-upgrade has taken place, the upgrade may still be rolled back to the previous version of EJBCA. Running in the transitionary state between Upgrade and Post Upgrade will not cause any cessation of operations or loss of critical data, but some data changes performed manually after Upgrade may be lost (though no certificates nor audit logs).

Keyfactor does not recommend a downgrading EJBCA in anything but an emergency.

For production environments, Keyfactor always recommends evaluating the upgrade using a staging environment with production-like data. While we test all upgrades rigorously prior to release, there is always a risk of permutations and corner cases which may be missed.

The Database and Semantic Versioning

EJBCA follows strict semantic versioning, which may give some guidance to what may be happening in the background during an upgrade:

Label	Increment	Description
Major	X.y.z	Majors in EJBCA tend to involve technological leaps, or significant changes to EJBCA’s functionality or nature. Majors may involve EJBCA performing significant database changes such as adding tables, columns or modifying data.
Minor	x.Y.z	Like Majors, Minors may also perform database changes such as adding tables or columns or data modification.
Patch	x.y.Z	Unlike Majors or Minors, Patch releases may not modify the database structure in any way, and are limited to only adding data. Patch releases are meant to be quickly deployable.
Emergency	x.y.x.A	In the rare event that a significant vulnerability or compliance issue is found in EJBCA or one of its underlying libraries, Keyfactor will publish an emergency release, based on the latest Patch version of currently supported releases, in order to have a fix available to customers as quickly as possible. The scope of this emergency release is limited to the issue at hand, and while it may involve some data modification it will never involve modifying tables or columns in the database.

EJBCA will normally automatically perform all database modification required on its own upon restarting the application server, given that the account that Wildfly uses to access the database has sufficient rights.

If this is not the case, we provide manual SQL scripts for upgrading database tables under the src/upgrade folder in the source code.

EJBCA supports upgrading directly to the most recent version of EJBCA (see the Upgrade Paths section below) from whatever current version is currently running unless prohibited due to the current version being too far out of support or requiring a technology jump.

Intermediate releases do not have to be deployed, instead EJBCA will automatically determine which upgrade steps which need to take place.

Zero Downtime Upgrades

Critical Operations

For installations of EJBCA deployed on a cluster of two or more nodes, EJBCA is guaranteed to be able to be upgraded with zero operational downtime for a critical set of operations, including:

Enrollment – Creating End Entities
Issuance – The acceptance of CSRs, issuance and transmission of issued certificate to the subscriber
Revocation – Revoking issued certificates
Validation – Continued issuance of CRLs and signing OCSP responses

Other operations (such as modifying profiles or editing CAs) may continue to function during the upgrade procedure – all upgrade code takes this into consideration – but some significant changes of data may cause interruptions in service until the entire cluster has been upgraded. Operations beyond the ones described above are discouraged until the final node has been upgraded.

Data in Transit

Some data may be in transit while the upgrade is taking place, i.e. may have been created using the previous version and will be finally processed by the upgraded version. This data will remain viable after the upgrade, even though it may have been created in the previous version. Examples include:

Publishing operations stored in the publishing queue
Unresolved Approval operations.
ACME Orders waiting for challenge resolution

Upgrade Strategy Across a Cluster/Multiple Clusters

Overview

Given an idealized deployment of EJBCA made for high volumes and availability:

In this deployment a CA-cluster is being served by an RA-cluster and a VA-cluster, the latter two connected to the former through Peering. Each node in each cluster is served by its own database, but as each database is synchronized they can from a practical point of view be considered a single database.

High Level Strategy

The strategy for upgrading this deployment is:

Step 1:	Upgrade (in either order) the RA cluster and the VA cluster following the strategy outlined in the next section
Step 2:	Upgrade the CA cluster

Upgrading the external EJBCA nodes first ensures the CA node uses the Peering protocol version of the CA instance. Therefore, if the CA were upgraded first it would use a newer version of the Peering protocol, that could be incompatible with the RA/VA EJBCA nodes.

Cluster Strategy

A clustered deployment is assumed the be placed behind a load balancer in order to ensure equal workload across the nodes in the cluster:

When upgrading this cluster, follow the following procedure:

Step	Instructions	Notes
1	Remove Node 1 from the Load Balancer (LB) to ensure that no traffic reaches it as Wildfly redeploys.
2	Upgrade Node 1	The common database has now been modified with whatever changes required for Node 1 to be able to resume critical operations (see above). None of these changes affect critical operations on the un-upgraded Nodes 2 & 3
3	Return Node 1 to the Load Balancer rotation.
4	Repeat steps 1-3 on Nodes 2 & 3
5	Perform post-upgrade on any of the nodes if required.	The database is now in a post-upgrade state, and may be incompatible with the previous version of EJBCA.

The significance of running post-upgrade manually is that EJBCA has no way of knowing the number of nodes in the cluster, nor how many of those nodes (beyond the first) which have been upgraded yet.

Following the upgrade procedure outlined in the previous two sections will allow a complete upgrade to be performed with zero detecable downtime by subscribers.

Upgrade Instructions for a Single Node

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.

Copy conf/*.properties from the earlier installation.
This step is not required if you are using an ejbca-custom directory (see ejbca-custom below).
Merge changes (if there are any) from *.properties.sample into your *.properties.
Copy the content of the p12 directory from the earlier installation and run the following command with the new version:

$ 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.
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:

$ ant deploy-keystore
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.
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).

Your Version	Recommended Upgrade Path	Upgrade Steps
6.4.x or later	Upgrade to the latest version of EJBCA.	If on JDK11, upgrade to JDK17 Upgrade to Wildfly32+ Upgrade to latest version of EJBCA by deploying the latest EJBCA EAR. Perform a post-upgrade by selecting System Upgrade in the CA UI.
5.0.12 to 6.3.x	Upgrade to the latest version of EJBCA.	If on JDK6, upgrade to JDK11 and if required, upgrade the application server to a JEE8 supporting server. Upgrade to latest version of EJBCA. From the console, run `ant upgrade`. Perform a post-upgrade by selecting System Upgrade in the CA UI.
4.0.16 to 5.0.11 on JDK6 or earlier	Upgrade to 6.3.2.6 and then upgrade to the latest version of EJBCA.	Upgrade to EJBCA 6.3.2.6. From the console, run `ant upgrade`. From the console, run `ant post-upgrade`. Upgrade to JDK11. Upgrade the application server to a JEE8 supporting server. Deploy the latest version of EJBCA. From the console, run `ant upgrade`. Perform a post-upgrade by selecting System Upgrade in the CA UI.
4.0.15 or earlier on JDK6 or earlier	Upgrade to 4.0.16 and then upgrade to 6.3.2.6.	Upgrade to EJBCA 4.0.16 From the console, run `ant upgrade`. From the console, run `ant post-upgrade`. Continue by following the steps below to upgrade to 6.3.2.6.

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.