Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

CipherTrust Manager Administration

System Upgrade/Downgrade

search

Please Note:

System Upgrade/Downgrade

Note

CipherTrust Manager 2.16 included a major version upgrade of the internal database. As a consequence, the time needed to upgrade from older versions to 2.16 or higher is longer than before and requires more free disk space. Typically, 25 - 35 GB of free disk space is needed for this upgrade. If a Virtual CipherTrust Manager node does not have enough free disk space, it can be increased by following the instructions from the cloud provider.

You can upgrade/downgrade your CipherTrust Manager firmware to and from 2.16 by securely downloading and applying a new/older system archive file.

Note

Consult the Release Model and Upgrade Paths pages for high-level overviews of upgrade support across more versions of CipherTrust Manager.

Specific upgrade steps vary depending on whether the CipherTrust Manager is clustered or unclustered.

Downgrade is only supported on unclustered appliances.

Upgrading a k160 Thales TCT Device

The k160 Thales TCT device has a different supported upgrade path than all other CipherTrust Manager models. For this device, the supported upgrade path is 2.11.2-tct->2.15.0->2.16.

The supported upgrade methods are unclustered/standalone and cluster remove/rebuild.

System Upgrade for an Unclustered Appliance

Caution

Please read this section carefully before performing a system upgrade.

Refer to Cluster Upgrade for details on upgrading a CipherTrust Manager which is part of a cluster of devices.

For 2.16, we tested upgrade from 2.13, 2.14, 2.15, and 2.16.0.

Note

If you are upgrading from 2.11.3 or higher 2.11 patch to 2.14 to pass through to 2.16, you must use the force flag, -o to upgrade to 2.14.x, so the upgrade command is sudo /opt/keysecure/ks_upgrade.sh -f <archive_file_path> -o. This is because these upgrade paths from 2.11.3 or higher 2.11 patch are not permitted for 2.14 as a final deployment target, as that patch contain bug fixes which 2.14 does not. As the final upgrade to 2.16 reapplies the bug fixes, you can pass through 2.14 as a temporary, intermediate version during the upgrade process only.

Note

Upgrades from other versions have not been tested and may not work correctly.

You require ksadmin level access with an SSH key.

  1. Obtain the signed archive file for the upgrade from the Support Portal. The file has the format ks_upgrade_<major.minor.patch+build_number>.tar.gz.gpg.

  2. On CipherTrust Manager create and download a backup with corresponding backup key, in case there are any problems.

    Note

    Upgrades keep all the data and may migrate the data and configuration. Therefore, as a precaution, it is recommended to take a backup before upgrading.
    Consult the backups page for details on forward compatibility for backups. Restoring a newer backup to an older version is never supported.

  3. Transfer the archive file to the CipherTrust Manager. You require the private SSH key associated with the ksadmin account. The command and supported private key format depends on the operating system you are transferring the archive file from.

    Source Operating SystemExample Command SyntaxRequired Private Key Format
    Linuxscp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.OpenSSH format
    Windowspscp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.PuTTY PPK format

  4. ssh into the CipherTrust Manager as ksadmin and ensure there is sufficient disk space available. The required disk space is 5 times the size of the upgrade file. For example, if the upgrade file is 5 GB, 25 GB of free space is required. Use df -h / to view available space.

  5. Run the following command:

    sudo /opt/keysecure/ks_upgrade.sh -f <archive_file_path>

    Here, <archive_file_path> specifies the CipherTrust Manager path to the signed archive file.

    The signature of the archive file is verified and the upgrade is applied.

  6. Reboot the appliance when prompted. The following output indicates the upgrade has completed:

    Upgrade succeeded
Reboot the instance to finish the upgrade

    Note

    If you have lost the SSH session, you can access upgrade logs in /home/ksadmin/. Upgrade log files have the prefix ks_upgrade. Search for "Upgrade succeeded" to confirm the upgrade completed, and that you must reboot. Take care to verify the upgrade has completed before rebooting. You must always reboot to fully apply the upgrade.

  7. Ensure the CipherTrust Manager services have started. From the ksadmin session, run systemctl status keysecure. Alternatively, you can visit the CipherTrust Manager web console or attempt to connect with the ksctl CLI.

  8. If you need to verify the new version, look for the version displayed in CipherTrust Manager banner in the SSH session on reboot, as shown in the screenshot. Alternatively, log in the web console UI and click the information icon at the top right to display version information.

    SSH session banner

  9. Re-download and re-install ksctl to access commands and settings introduced in the new CipherTrust Manager software version.

    Note

    Previous versions of ksctl still work with new CipherTrust Manager software for existing features and settings.

System Downgrade

An unclustered CipherTrust Manager can be downgraded to the previous minor version. For release-specific upgrade/downgrade information, refer to the release notes for your release.

Downgrades perform a CipherTrust Manager reset, which wipes all CipherTrust Manager data except the backup files that already exist.

As well, the PCI HSM drivers on k570 models, and base operating system packages are not changed during downgrade.

Warning

As we cannot guarantee stability, we strongly recommend using downgraded systems for test environments only. Do not use a downgraded CipherTrust Manager in a production environment.
To return to a production environment to a previous version,
1. Take a backup.
2. Perform a system factory reset.
3. Upgrade the CipherTrust Manager to the desired version.
4. Restore the backup.

To downgrade your CipherTrust Manager

  1. SSH into the CipherTrust Manager as "ksadmin".

  2. Downgrade the CipherTrust Manager:

    $ sudo /opt/keysecure/ks_downgrade.sh -f <~/filename>

Usage: ks_downgrade.sh -f <FILE> [-o]

*  `-f`: Path to the signed CipherTrust Manager installer file.

*  `-o`: Clustered node cannot be downgraded. Use this flag to override this behavior.

Cluster Upgrade

A cluster can be upgraded in two ways:

The following table indicates the differences between the two ways:

CharacteristicOnline in-placeCluster Remove/Rebuild
Cluster configuration preservedyesno
Available for client requests during entire upgradeyesno
Skip intermediate versionsnoyes, skip up to three versions

Note

In-place offline cluster upgrade is only supported if the target release is a Long Term Support release such as 2.11-LTS.

Prerequisites

  • You require ksadmin level access with an SSH key.

  • Obtain the signed archive file for the upgrade from the Support Portal. The file has the format ks_upgrade_<major.minor.patch+build_number>.tar.gz.gpg.

Online In-place Cluster Upgrade

Caution

CipherTrust Manager 2.14 included a major version upgrade of the internal database. As a consequence, the time needed to upgrade from older versions to 2.14 or higher is longer than before and requires more free disk space. Typically, 25 - 35 GB of free disk space is needed for this upgrade. If a Virtual CipherTrust Manager node does not have enough free disk space, it can be increased by following the instructions from the cloud provider.

Be aware of the following considerations when performing an in-place cluster upgrade:

  • The node being upgraded will be inaccessible during the upgrade. This may be as long at 10 or more minutes. Clients must be able to handle this outage.

  • There will be a brief period of time (under 30 seconds) where the database will be locked while upgrading the first node. This affects all nodes at the same time, and some nodes may give error responses during this time.

  • All nodes in the cluster should be upgraded as soon as possible - nodes running different version of the firmware will behave differently, potentially causing problems with applications.

For 2.11.1, 2.11.2, 2.11.3, and 2.11.4 patches, you must use the force flag, -o to upgrade to 2.12.x, so the upgrade command is sudo /opt/keysecure/ks_upgrade.sh -f <archive_file_path> -o. This is because these upgrade paths are not permitted for 2.12 as a final deployment target, as these patches contain bug fixes which 2.12 does not. As the final upgrade to 2.16 reapplies the bug fixes, you can pass through 2.12 as a temporary, intermediate version during the upgrade process only.

To perform an online in-place cluster upgrade

  1. Before doing any upgrade operation, ensure that you have a backup, and that you have downloaded the backup and associated backup key.

  2. Ensure all nodes in the cluster are up and operating normally. Resolve any issues (like removing any obsolete nodes) before performing the upgrade.

  3. Perform a system upgrade on each node, one at a time.

    1. Transfer the archive file to the CipherTrust Manager. You require the private SSH key associated with the ksadmin account. The command and supported private key format depends on the operating system you are transferring the archive file from.

      Source Operating SystemExample Command SyntaxRequired Private Key Format
      Linuxscp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.OpenSSH format
      Windowspscp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.PuTTY PPK format

    2. SSH into the CipherTrust Manager as ksadmin and ensure there sufficient disk space available. The required disk space is 5 times the size of the upgrade file. For example, if the upgrade file is 5 GB, 25 GB of free space is required. Use df -h / to view available space.

    3. Run the following command to upgrade the device.

      $ sudo /opt/keysecure/ks_upgrade.sh -f <archive_file_path>

      Here, <archive_file_path> specifies the CipherTrust Manager path to the signed archive file.

      The signature of the archive file is verified and the upgrade is applied.

    4. Reboot the appliance as prompted. The following output indicates the upgrade has completed:

      Upgrade succeeded
Reboot the instance to finish the upgrade

      Note

      If you have lost the SSH session, you can access upgrade logs in /home/ksadmin/. Upgrade log files have the prefix ks_upgrade. Search for "Upgrade succeeded" to confirm the upgrade completed, and that you must reboot. Take care to verify the upgrade has completed before rebooting. You must always reboot to fully apply the upgrade.

    5. Ensure the upgrade of each node is complete and that the node is operating normally, before proceeding to the next node.

      From the ksadmin session, run systemctl status keysecure to ensure that the CipherTrust Manager services have started. Alternatively, you can visit the CipherTrust Manager web console or attempt to connect with the ksctl CLI.

      Note

      When updating the first node in a cluster, the cluster nodes may briefly experience slower than usual response times. This occurs because the shared database schema for the cluster is updated with the first node.

    6. If you need to verify the new version, look for the version displayed in CipherTrust Manager banner in the SSH session on reboot, as shown in the screenshot. Alternatively, log in the web console UI and click the information icon at the top right to display version information.

      SSH session banner

  4. Repeat step 3 for each minor version.

    Note

    For 2.11.1, 2.11.2, 2.11.3, and 2.11.4 patches, you must use the force flag, -o to upgrade to 2.12.x, so the upgrade command is sudo /opt/keysecure/ks_upgrade.sh -f <archive_file_path> -o. This is because these upgrade paths are not permitted for 2.12 as a final deployment target, as these patches contain bug fixes which 2.12 does not. As the final upgrade to 2.16 reapplies the bug fixes, you can pass through 2.12 as a temporary, intermediate version during the upgrade process only.

  5. Re-download and re-install ksctl to access commands and settings introduced in the new CipherTrust Manager software version.

    Note

    Previous versions of ksctl still work with new CipherTrust Manager software for existing features and settings.

Upgrade Using the Cluster Remove/Rebuild Method

Supported upgrade paths are the same as for system upgrade of an unclustered appliance.

Note

If you are upgrading from 2.11.3 or 2.11.4 to 2.14 to pass through to 2.16, you must use the force flag, -oto upgrade to 2.14.x, so the upgrade command issudo /opt/keysecure/ks_upgrade.sh -f -o. This is because these upgrade paths from 2.11.3 or 2.11.4 are not permitted for 2.14 as a final deployment target, as that patch contain bug fixes which 2.14 does not. As the final upgrade to 2.16 reapplies the bug fixes, you can pass through 2.14 as a temporary, intermediate version during the upgrade process only.

Prerequisite for Cluster Remove/Rebuild Method

Plan for downtime when clients cannot make requests to the cluster and manually block client access to the CipherTrust Manager IP addresses/hostnames in your network before starting.

Caution

If any client request comes into a CipherTrust Manager while the cluster is broken or during the cluster rebuild, the resulting data changes can be lost.

To Perform an Upgrade Using Cluster Remove/Rebuild Method

  1. On one of the cluster nodes, create and download a backup with corresponding backup key, in case there are any problems.

  2. Remove all nodes from the cluster except one.

  3. Delete the cluster configuration on the remaining node.

    $ ksctl cluster delete

  4. Perform the upgrade on that remaining node.

    1. Transfer the archive file to the CipherTrust Manager. You require the private SSH key associated with the ksadmin account. The command and supported private key format depends on the operating system you are transferring the archive file from.

      Source Operating SystemExample Command SyntaxRequired Private Key Format
      Linuxscp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.OpenSSH format
      Windowspscp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.PuTTY PPK format

    2. SSH into the CipherTrust Manager as ksadmin and ensure there sufficient disk space available. The required disk space is 5 times the size of the upgrade file. For example, if the upgrade file is 5 GB, 25 GB of free space is required. Use df -h / to view available space.

    3. Run the following command to upgrade the device.

      $ sudo /opt/keysecure/ks_upgrade.sh -f <archive_file_path>

      Here, <archive_file_path> specifies the CipherTrust Manager path to the signed archive file.

      The signature of the archive file is verified and the upgrade is applied.

    4. Reboot the appliance as prompted. The following output indicates the upgrade has completed:

      Upgrade succeeded
Reboot the instance to finish the upgrade

      Note

      If you have lost the SSH session, you can access upgrade logs in /home/ksadmin/. Upgrade log files have the prefix ks_upgrade. Search for "Upgrade succeeded" to confirm the upgrade completed, and that you must reboot. Take care to verify the upgrade has completed before rebooting. You must always reboot to fully apply the upgrade.

    5. From the ksadmin session, run systemctl status keysecure to ensure that the CipherTrust Manager services have started. Alternatively, you can visit the CipherTrust Manager web console or attempt to connect with the ksctl CLI.

    6. If you need to verify the new version, look for the version displayed in CipherTrust Manager banner in the SSH session on reboot, as shown in the screenshot. Alternatively, log in the web console UI and click the information icon at the top right to display version information.

      SSH session banner

  5. After the appliance reboots, re-build the cluster by creating a new cluster on this node.

  6. Perform the upgrade on all other removed nodes, as outlined in step 4.

    Note

    If a previously used node is to be re-used, the cluster must first be deleted from that system.

  7. Join new instances to the cluster.

  8. Re-establish client access to the cluster.

  9. Re-download and re-install ksctl to access commands and settings introduced in the new CipherTrust Manager software version.

    Note

    Previous versions of ksctl still work with new CipherTrust Manager software for existing features and settings.

Upgrade Troubleshooting

The following section lists some commonly encountered errors during upgrade and their solutions.

Occasional Error for Devices Upgraded from NextGen KeySecure 1.6 or 1.7

CipherTrust Manager appliances that at one time ran NextGen KeySecure software versions 1.6 or 1.7 occasionally fail to upgrade on future versions. The error reported is E: Unable to locate package docker-compose-plugin.

Solution: Contact customer support to resolve this state.

On this page