System Upgrade/Downgrade
Note
CipherTrust Manager 2.14 includes a major version upgrade of the internal database. As a consequence, the time needed to upgrade to 2.14 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.
During upgrade, the message
NOTICE: skipped replication for captured CCL command "LOCK TABLE in replication sets (kylo)
is displayed multiple times. This is an expected part of backend database configuration and does not indicate a problem.[CTE UserSpace] After upgrade to CipherTrust Manager 2.14, CTE UserSpace 10.1.0 clients don't show the Healthy status on GUI. This is a CTE UserSpace Agent issue, which is resolved in the CTE-U 10.2.0 release. To workaround this issue, upgrade the CTE UserSpace clients to 10.2.0 or manually restart the CTE-U services (
secfs-fuse restart
) to restore the client communication to the Healthy state for older CTE-U client versions.
You can upgrade/downgrade your CipherTrust Manager firmware to and from 2.14.x 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.
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.14.x, we tested upgrade from 2.13.x, 2.12.x, 2.11.1, and 2.11.2. We have also tested upgrade from lower 2.14.x versions to higher 2.14.x patches.
Note
Upgrade from 2.11.3-2.11.6 to 2.14 is not supported, as these patches will be released after 2.14 and contain bug fixes not present in 2.14. Upgrading from these patches to 2.14 can re-introduce bugs. Consult the Release Model page for more details on upgrade compatibility for 2.11 patches.
Note
Upgrades from other versions have not been tested and may not work correctly.
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
.On CipherTrust Manager create and download a backup with corresponding backup key, in case there are any problems.
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 System Example Command Syntax Required Private Key Format Linux scp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.
OpenSSH format Windows pscp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.
PuTTY PPK format ssh
into the CipherTrust Manager asksadmin
and ensure there is sufficient disk space available. 35 GB of free space is required. Usedf -h /
to view available space.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.
Reboot the appliance when prompted.
Ensure the CipherTrust Manager services have started. From the
ksadmin
session, runsystemctl status keysecure
. Alternatively, you can visit the CipherTrust Manager web console or attempt to connect with the ksctl CLI.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.
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
SSH into the CipherTrust Manager as "ksadmin".
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:
Characteristic | Online in-place | Cluster Remove/Rebuild |
---|---|---|
Cluster configuration preserved | yes | no |
Available for client requests during entire upgrade | yes | no |
Skip intermediate versions | no | yes, 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 includes a major version upgrade of the internal database. As a consequence, the time needed to upgrade to 2.14 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.
To perform an online in-place cluster upgrade
Before doing any upgrade operation, ensure that you have a backup, and that you have downloaded the backup and associated backup key.
Ensure all nodes in the cluster are up and operating normally. Resolve any issues (like removing any obsolete nodes) before performing the upgrade.
Perform a system upgrade on each node, one at a time.
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 System Example Command Syntax Required Private Key Format Linux scp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.
OpenSSH format Windows pscp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.
PuTTY PPK format SSH into the CipherTrust Manager as ksadmin and ensure there sufficient disk space available. 35 GB of free space is required. Use
df -h /
to view available space.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.
Reboot the appliance as prompted.
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, runsystemctl 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.
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.
Repeat step 3 for each minor version.
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.
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
On one of the cluster nodes, create and download a backup with corresponding backup key, in case there are any problems.
Remove all nodes from the cluster except one.
Delete the cluster configuration on the remaining node.
$ ksctl cluster delete
Perform the upgrade on that remaining node.
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 System Example Command Syntax Required Private Key Format Linux scp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.
OpenSSH format Windows pscp -i <path_to_private_SSH_key> <archive_file_name> ksadmin@<ip>:.
PuTTY PPK format SSH into the CipherTrust Manager as ksadmin and ensure there sufficient disk space available. 35 GB of free disk space is required. Use
df -h /
to view available space.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.
Reboot the appliance as prompted.
From the
ksadmin
session, runsystemctl 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.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.
After the appliance reboots, re-build the cluster by creating a new cluster on this node.
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.
Join new instances to the cluster.
Re-establish client access to the cluster.
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.