Upgrading

Most Keyfactor Command upgrades are brief with a minimum of changes to existing user accounts, groups, CAClosed A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. templates, firewall settings, etc. Most prerequisites have not materially changed from previous versions and the current version can generally be installed using the same hardware and existing instances of the supporting software. The upgrade process is often completed within three to four hours.

The overall task flow consists of the following steps:

The Keyfactor Command server software will be installed and configured for you. Once this is complete, you may upgrade any orchestrators and gateways in your environment.

In many cases the Keyfactor Universal OrchestratorClosed The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with servers and devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can provide certificate management capabilities on a variety of platforms and devices (e.g. Amazon Web Services (AWS) resources, Citrix\NetScaler devices, F5 devices, IIS stores, JKS keystores, PEM stores, and PKCS#12 stores) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux servers or Linux containers. can be installed over the existing installation without uninstalling the previous version. For specific upgrade guidance, see Upgrading the Universal Orchestrator.

Support for the Keyfactor Windows OrchestratorClosed The Windows Orchestrator, one of Keyfactor's suite of orchestrators, is used to manage synchronization of certificate authorities in remote forests, run SSL discovery and management tasks, and interact with Windows servers as well as F5 devices, NetScaler devices, Amazon Web Services (AWS) resources, and FTP capable devices, for certificate management. In addition, the AnyAgent capability of the Windows Orchestrator allows it to be extended to create custom certificate store types and management capabilities regardless of source platform or location. was deprecated in Keyfactor Command release 11.0. All uses of the Keyfactor Windows Orchestrator should be updated to the Keyfactor Universal Orchestrator. The Keyfactor Universal Orchestrator replaces the Keyfactor Windows Orchestrator and runs on both Windows or Linux servers. The following functions that were part of the Keyfactor Windows Orchestrator are supported in the Keyfactor Universal Orchestrator with custom extensions:

  • Interact with F5 devices for certificate management
  • Interact with NetScaler devices for certificate management
  • Interact with Amazon Web Services (AWS) resources for certificate management
  • Interact with Windows certificate stores and IIS

For more information about using custom extensions with the Keyfactor Universal Orchestrator, see Installing Custom-Built Extensions.

Important:  The Keyfactor Universal Orchestrator is only compatible with Keyfactor Command version 9.0 or later. The current version of the Keyfactor Universal Orchestrator is 12.5.0.1 and requires .NET 6.

If you're upgrading from a version of Keyfactor Command prior to 8.0, you will need to update any Windows Orchestrators (a.k.a. Windows Agents) that are used for SSLClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. scanning to support the current scanning architecture. Install and configure the Keyfactor Universal Orchestrator software (see Upgrading the Universal Orchestrator).

Note:  The orchestrator endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. location changed for Keyfactor Command release 6 and may need to be modified in your orchestrator endpoint configuration—from CMSAgents to KeyfactorAgents.
Important:  The most recent versions of the Keyfactor CA Policy Module software need to be upgraded using the below method and PowerShell script and can't be installed over an existing implementation of the Keyfactor CA Policy Module as an upgrade method.

To upgrade a Keyfactor CA Policy Module:

  1. Make a note of all your existing policy module configuration, including which policy handlers are enabled and what configurations are set within each handler. During the upgrade process, you will uninstall the policy module, which will remove your configuration. The upgrade script should successfully restore the configuration as part of the upgrade process, but you will want to have a complete record of the configuration as a backup.
  2. On the Keyfactor CA Policy Module server, open a PowerShell window using the “Run as administrator” option.

  3. In the PowerShell window, change to the directory in which you placed the upgrade script included with the latest version of the Keyfactor CA Policy Module and execute it in archive mode. For example:

    .\Keyfactor-CA-Modules-Upgrade-Script.ps1 -Mode archive -InformationAction Continue -ErrorAction Stop
    Note:  This step is creating a backup of your policy module configuration before you uninstall the old policy module. It will create an output file, Keyfactor-CA-Policy.dat, in the current directory.
    Tip:  Additional options are available in the upgrade script and can be viewed using the -full switch with Get-Help. For example:
    Get-Help .\Keyfactor-CA-Modules-Upgrade-Script.ps1 -full
  4. Unload the existing policy module in the CA MMC, and close the MMC.
  5. Uninstall the existing policy module.

  6. Install the latest version of the Keyfactor CA Policy Module but do not configure it (see Installing the Keyfactor CA Policy Module Handlers in the Keyfactor Command Server Installation Guide). Be sure to install all the same policy handlers that were installed previously.

    Execute the upgrade script included with the latest version of the Keyfactor CA Policy Module again, but this time in restore mode. For example:

    .\Keyfactor-CA-Modules-Upgrade-Script.ps1 -Mode restore -InformationAction Continue -ErrorAction Stop
    Note:  This step takes the backup of your policy module configuration from the first run of the upgrade script and restores the information to the correct locations so that you will not need to re-configure the policy module. Be sure that the output file from the first run of the upgrade script, Keyfactor-CA-Policy.dat, is in the current directory.
  7. Open the CA MMC and load the Keyfactor CA Policy Module (see Installing the Keyfactor CA Policy Module Handlers in the Keyfactor Command Server Installation Guide).
  8. Open the Properties for the policy module and, if you've received a new license, install the new license on the License tab. On the Custom Handlers tab, review all the configuration to confirm that it has been correctly restored by the upgrade script.
Tip:  New versions of the policy module are not necessarily released at the same time as new versions of Keyfactor Command and so the policy module may not need upgrading at the same time as Keyfactor Command.

The latest version of the Keyfactor Cloud Gateway—used to support management of certificates in the hosted Keyfactor Command environment—is 23.3 released in mid 2023. If you are already using this version, no configuration changes need to be made. Restart the gateway service to refresh the connection to the upgraded Keyfactor Command instance.

If you're using a recent version of the gateway (20.6 or newer), you don't need to upgrade the gateway unless the gateway contains a change that's needed in your environment. See the gateway release notes in the Keyfactor Cloud Gateway Installation & Configuration Guide to review some of the recent changes.

In most cases, the Keyfactor gateway software can be installed over the existing software installation without uninstalling the previous version. Review the configuration for your gateway, and then install and configure the software as per the Keyfactor Cloud Gateway Installation & Configuration Guide, retaining the same installation location.

If you're using an EJBCA gateway and wish to make use of the new feature in Keyfactor Command for native support of EJBCA CAs, you will need to follow the EJBCA gateway upgrade process to unlink the EJBCA certificates in your Keyfactor Command database from your EJBCA gateway CA to enable them to be relinked to a native CA configured in Keyfactor Command. For more information, contact Keyfactor support.

In most cases, the Keyfactor gateway software can be installed over the existing software installation without uninstalling the previous version. Review the configuration for your gateway, and then install and configure the software as per the Keyfactor gateway guide for the particular gateway, retaining the same installation location. The gateway configuration wizard has significantly changed in recent releases for many of the gateways, which may require modification to your configuration.

Tip:  New versions of CA gateways are not necessarily released at the same time as new versions of Keyfactor Command and so gateways may not need upgrading at the same time as Keyfactor Command.
Important:  The Classic APIClosed A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command., also known as the CMS API or CMSAPI, was removed in Keyfactor Command version 11.0. Customers should migrate all uses of the Classic API to the Keyfactor API prior to upgrading to Keyfactor Command versions 11.0 or later.

Please see the latest release notes (see Release Notes & Upgrading) if you are using any custom scripts that leverage the Keyfactor API.

See Post-Upgrade Steps

The bulk of the time upgrading will be spent verifying that all functions and configurations have correctly carried over and the upgraded instance is performing correctly.