CipherTrust Manager (CTM) is the core key and policy management platform in the Thales CipherTrust data security platform. It enables businesses to set up security policies, assign granular access controls, and centrally manage encryption keys. The key lifecycle tasks CTM manages include creation, rotation, destruction, import, and export. CTM also provides role-based access control, thorough auditing and reporting, and REST APIs for management and development automation. Physical and virtual CTM form factors are FIPS 140-2 compliant up to Level 3. Hardware Security Modules (HSMs) such as Thales Luna and Luna Cloud HSM can be used to anchor CipherTrust Manager. Keeping CTM on a supported version is critical for security: running an outdated version exposes the organization to vulnerabilities that have been patched in subsequent releases and may violate compliance requirements that mandate current software versions. Thales tests upgrades only from the three previous minor versions, making the mandatory upgrade path a critical constraint: to upgrade from version 2.0 to 2.9, the required path is 2.0 to 2.3, then 2.3 to 2.6, then 2.6 to 2.9. This document covers the prerequisites, the file transfer step, the three-step upgrade procedure, post-upgrade validation checks, the known MAC address swap issue, and troubleshooting guidance. For full official documentation, see the Thales System Upgrade Guide. For CTM consulting and migration, see CipherTrust Manager.
Quick Answer: What Is the Upgrade Path from CTM 2.0 to 2.9?
The mandatory upgrade path from CipherTrust Manager 2.0 to 2.9 is: 2.0 to 2.3, then 2.3 to 2.6, then 2.6 to 2.9. You cannot skip intermediate versions. Each hop must be completed, verified, and confirmed operational before beginning the next. The upgrade process requires: Ksadmin SSH access; a system-level backup with both backup file and backup key downloaded; at least 12 GB of free disk space; the upgrade archive file for the target version transferred to the appliance via SCP; and a reboot at the end of each upgrade hop.
Pre-Requisites
Pre-requisites must be completed before beginning any upgrade. Skipping these steps risks upgrade failure or data loss. The following checks must be completed before proceeding:
- Know your current software version of the CipherTrust Manager (CM) and the desired target version. Example: Current version is 2.0, desired version is 2.9.
- Define the complete upgrade path: For the above example: 2.0 to 2.3, then 2.3 to 2.6, then 2.6 to 2.9. [NOTE: Thales tests upgrades from the three previous minor versions only. Upgrades from versions outside this range have not been tested and may not work correctly.]
- Ensure you have access as Ksadmin with an SSH key.
- Take a system-level backup and ensure you have downloaded both the CM backup file and the backup key. This can be done via the CM Web UI. The backup is your recovery mechanism if the upgrade fails; do not proceed without a verified backup.
- Run the following command to confirm at least 12 GB of free disk space is available (excluding the upgrade file): df -h
- Transfer the upgrade file to the CipherTrust Manager using SCP (Secure Copy Protocol) with the following command, or via the WinSCP application (select SCP as the file protocol in WinSCP, not SFTP):
scp -i <path_to_private_SSH_key> <upgrade_file_name> ksadmin@<ip>:.
[NOTE: Upgrade files can be downloaded from the Thales Support portal for the desired version. If you cannot locate the upgrade file, open a support ticket with Thales to obtain it.]
Upgrade Workaround: Step-by-Step Procedure
Once all prerequisites are satisfied, execute the following three steps for each version hop in the upgrade path. Repeat this process for each intermediate version before proceeding to the next.
- Login as Ksadmin via SSH. Open an SSH connection to the CipherTrust Manager appliance using the Ksadmin account and your SSH private key.
- Run the upgrade script. Execute the following command to begin the upgrade process:
sudo /opt/keysecure/ks_upgrade.sh -f <archive_file_path>The upgrade script extracts and applies the archive file, migrates the database, and updates all service configurations. Wait for the script to complete. Do not interrupt the process. [NOTE: The upgrade can also be performed via serial console connection as Ksadmin if SSH connectivity is unavailable.] - Reboot the appliance once all services are running.
sudo rebootAllow the system to complete the reboot before proceeding to post-upgrade checks or to the next upgrade hop.
Post-Upgrade Validation Checks
After each upgrade hop completes and the appliance has rebooted, run the following validation checks before proceeding to the next hop or concluding the upgrade is complete:
- Verify all services are running: sudo docker ps | wc -l The line count should reflect the expected number of running containers for the CTM version.
- Verify the CipherTrust Manager service status: systemctl status keysecure The service should show as active and running. If the service is not running, review the service logs before proceeding.
- Access the CipherTrust Manager web console in your browser to confirm the UI loads correctly and displays the updated version number.
- Alternatively, connect using the ksctl CLI and verify the version with the appropriate CLI command.
Upgrade Decision Table
| Current CTM Version | Target CTM Version | Required Upgrade Path | Number of Hops |
|---|---|---|---|
| 2.0 | 2.3 | 2.0 to 2.3 (direct) | 1 |
| 2.0 | 2.6 | 2.0 to 2.3, then 2.3 to 2.6 | 2 |
| 2.0 | 2.9 | 2.0 to 2.3, then 2.3 to 2.6, then 2.6 to 2.9 | 3 |
| 2.3 | 2.6 | 2.3 to 2.6 (direct) | 1 |
| 2.3 | 2.9 | 2.3 to 2.6, then 2.6 to 2.9 | 2 |
| 2.6 | 2.9 | 2.6 to 2.9 (direct) | 1 |
Known Issue: MAC Address Swap After Upgrade from 2.6 and Earlier
There is a known issue in CipherTrust Manager instances upgraded from version 2.6 and earlier where network device names sometimes swap MAC addresses after reboot. This has been observed for network interfaces beginning with eth and bonded connections created from network interfaces beginning with eth. After the reboot that follows the upgrade, network connectivity to the CTM appliance may be lost if the interface names have been swapped and the network configuration is no longer bound to the correct physical interface.
To avoid this issue, configure a dedicated named connection for each network interface before performing the upgrade. This ensures that network configuration is bound to the interface by its specific connection definition rather than relying on interface name ordering, which may change after the reboot.
Troubleshooting
- Upgrade script fails immediately: Verify that the archive file was transferred correctly and is not corrupted. Re-download from the Thales Support portal and retry the SCP transfer.
- Services do not start after reboot: Check service logs for error messages before assuming the upgrade failed. Some services may take several minutes to initialize after a reboot following a version upgrade. If services remain down after 10 minutes, contact Thales support.
- Web console inaccessible after reboot: Verify network connectivity using the MAC address swap mitigation steps above. If connectivity is confirmed but the UI is unresponsive, check the keysecure service status and review logs.
- Cannot log in after upgrade: Verify that the user account and credentials are correct for the new version. Some version upgrades may modify authentication configuration; refer to the Thales upgrade release notes for the specific target version.
- Insufficient disk space error: Free disk space before retrying. The upgrade archive and extracted files require space beyond the 12 GB threshold; ensure the system has additional headroom beyond the minimum.
Conclusion
This document covers the essential steps for upgrading CipherTrust Manager from version 2.0 to higher versions following the mandatory Thales upgrade path. It does not replace the standard Thales documentation set for CipherTrust Manager. It is an addendum designed to be used alongside that documentation to highlight the key constraints and operational steps that practitioners need to complete a successful upgrade. Always upgrade to the latest supported version: running current security software is a best practice that reduces exposure to vulnerabilities and ensures continued vendor support. For CTM consulting, migration planning, or Vormetric DSM to CTM migration, see CipherTrust Manager and DSM Migration Services.
Sources: thalesdocs.com
Frequently Asked Questions
What is the mandatory upgrade path for CipherTrust Manager from 2.0 to 2.9?
The mandatory path is: 2.0 to 2.3, then 2.3 to 2.6, then 2.6 to 2.9. You cannot skip intermediate versions. Thales tests upgrades only from the three previous minor versions; skipping versions risks upgrade failure or data integrity issues.
What are the prerequisites for upgrading CipherTrust Manager?
Prerequisites are: know current and target versions and define the complete path; have Ksadmin SSH access; take a system-level backup with backup file and backup key downloaded; verify at least 12 GB of free disk space with df -h; and transfer the upgrade archive file to the appliance via SCP before beginning the upgrade.
How do you transfer the upgrade file to CipherTrust Manager?
Use SCP: scp -i path_to_private_SSH_key upgrade_file_name ksadmin@ip:. On Windows, WinSCP can be used; select SCP as the file protocol, not SFTP. Upgrade files are available from the Thales Support portal for the target version.
What post-upgrade checks confirm the upgrade was successful?
Run: (1) sudo docker ps | wc -l to verify all containers are running; (2) systemctl status keysecure to verify the CTM service is active; (3) access the web console to confirm the UI loads and displays the new version number; (4) optionally connect via ksctl CLI to verify the version.
What is the known MAC address swap issue in upgrades from 2.6 and earlier?
Upgrading from CTM 2.6 and earlier can cause network interface names to swap MAC addresses after reboot, particularly for eth interfaces and bonded connections. This may cause network connectivity loss after the post-upgrade reboot. The mitigation is to configure a dedicated named connection for each network interface before performing the upgrade.
