Upgrading EJBCA

This section provides information on upgrading from your current version to a later version of EJBCA and the Upgrade Paths table below helps you determine the most efficient upgrade path.

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

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.

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:

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

  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:

    $ 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/700_710/700_710-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 section 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

4.0.15 or earlier on JDK6 or earlier

Upgrade to 4.0.16 and then upgrade to 6.3.2.6.

  1. Upgrade to EJBCA 4.0.16

  2. From the console, run ant upgrade.

  3. From the console, run ant post-upgrade.

  4. Continue by following the steps below to upgrade to 6.3.2.6.


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.

  1. Upgrade to EJBCA 6.3.2.6.

  2. From the console, run ant upgrade.

  3. From the console, run ant post-upgrade.

  4. Upgrade to JDK8.

  5. Upgrade the application server to a JEE7 supporting server.

  6. Deploy the latest version of EJBCA.

  7. From the console, run ant upgrade.

  8. Perform a post-upgrade by selecting System Upgrade in the Admin GUI.


5.0.12 to 6.3.x

Upgrade to the latest version of EJBCA.

  1. If on JDK6, upgrade to JDK8 and if required,
    upgrade the application server to a JEE7 supporting server.

  2. Upgrade to latest version of EJBCA.

  3. From the console, run ant upgrade.

  4. Perform a post-upgrade by selecting System Upgrade in the Admin GUI.


6.4.0 or later

Upgrade to the latest version of EJBCA.

  1. Upgrade to latest version of EJBCA.

  2. Perform a post-upgrade by selecting System Upgrade in the Admin GUI.


Notes

Intermediate Release EJBCA 6.3.2.6

The intermediate release EJBCA 6.3.2.6, released 1 December 2017, handles intermediate upgrade steps when upgrading a version prior to 5.0.12 to a later EJBCA version.

Up until and including version 6.3.2.6, EJBCA can be run on JBoss 5.1, while higher versions of EJBCA require Java 8 and WildFly.

Approval Request after EJBCA 6 Upgrade

If you are using approvals and upgrading to EJBCA 6, please be aware of an issue preventing approval requests created in EJBCA 5.x or earlier from being displayed after the upgrade. For details, refer to ECA-8831 .

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 6.4.0: JDK6 → JDK7: End of support for legacy runtime version JDK6 and moving to JDK7.

  • 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 7.0.0: JDK7 → JDK8: End of support for legacy runtime version JDK7 and moving to JDK8

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

Upgrade Process Changes

  • As of EJBCA 4.0, full up-time is supported during upgrades for clustered installations, using the upgrade process steps upgrade and post-upgrade:

    • upgrade: Performs steps required for upgrading the first node to be able to function once it comes online again.

    • post-upgrade: Performs remaining upgrade steps (such as clean-up) that can only be performed once all nodes are running the latest code.

  • As of EJBCA 6.4.0, the database version is tracked internally, making the upgrade automatically run from the first run running the upgraded code, making the upgrade command redundant.

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