OVA Upgrade Guide

Entrust provides a single upgrade kit in ISO format. You use this to upgrade KeySafe 5.

KeySafe 5 Supported Upgrade Paths

You can only upgrade between successive versions.

Supported upgrade paths are:

Current Version Upgrade Path



Upgrading the KeySafe 5 cluster

You can upgrade the entire KeySafe 5 cluster from any node in the cluster using the KeySafe 5 Appliance Management UI. KeySafe 5 automatically applies the upgrade to all nodes in the cluster sequentially.

Before You Begin

  • Make sure that the KeySafe 5 nodes can communicate with one another on port TCP/8443 and TCP/5432.

  • We recommend you back up your KeySafe 5 cluster before you upgrade it. For details, see Backing Up KeySafe 5 Through the KeySafe 5 Appliance Management UI.

  • Please download your Admin Key and store it in a safe place before you upgrade. If KeySafe 5 prompts for an admin key to recover your KeySafe 5 system, you must provide this admin key to proceed. If you do not have your admin key, you may lose your data. For details, see Downloading Your Admin Key Part.

  • We recommend that you enable the support login on all cluster nodes before you start the upgrade. For details, see Enabling or Disabling the Support Login.

  • Make sure your network connection to the KeySafe 5 node is as fast and as stable as possible. To begin the upgrade, you need to upload the upgrade ISO image to the KeySafe 5 node in one continuous session. If the upload times out or if connectivity to the KeySafe 5 node is lost during the upload, you will see error messages in KeySafe 5 and you must re-upload the file from scratch. KeySafe 5 cannot resume the upload from where it left off during a previous session.

  • Make note of the KeySafe 5 agents listed by the product, this will be useful when re-enrolling the KeySafe 5 agents during the upgrade procedure.


  1. Log into the KeySafe 5 Appliance Management UI using an account with Security Admin privileges

  2. In the top menu bar, click Cluster and make sure the Status of the cluster is Healthy. If it is not, you must resolve those issues before you can upgrade the cluster.

  3. In the top menu bar, click Settings.

  4. In the System Settings section, click System Upgrade.

  5. Click Browse, navigate to the Entrust ISO upgrade file, and click Open.

  6. Click Upload File. If the Upload File button is not active, make sure that you have selected an ISO file and that the cluster is healthy.

    After KeySafe 5 uploads and validates the ISO file, KeySafe 5 begins the automatic upgrade process by copying the ISO file from the current node to all of the other KeySafe 5 nodes in the cluster. After the ISO file has been copied, KeySafe 5 displays a Success message. Click Close to continue with the upgrade.

    KeySafe 5 displays a status message stating that the upgrade is in process along with a Cancel Upgrade button in case you want to stop the process.

  7. Click Finish Upgrade.

    Ensure you are still on the same node where you clicked Upgrade File.

    KeySafe 5 displays a message stating that the cluster will be put into maintenance mode during this procedure and that all nodes will be rebooted. While in maintenance mode no KeySafe 5 configuration changes can be made and no new VMs can be added.

  8. Click Proceed.

    KeySafe 5 displays a status message stating that the cluster nodes are being rebooted. It may take a while for this process to run on all nodes except for the current node. When all of the other nodes have been upgraded and are back online, KeySafe 5 reboots the current node to finish the upgrade process on that node. At this point, you will be automatically logged out of the KeySafe 5 Appliance Management UI on that node. You can monitor the progress on the KeySafe 5 Appliance Management UI of the other nodes. This again may take a while to complete.

    When any node is being upgraded, if you have access to the KeySafe 5 System Console, you can view the the CentOS upgrade messages.

    When KeySafe 5 reboots the current node, you may see a message that the application cannot connect to the server. The browser page may then display a "connection refused" message. Wait a few moments for the node to finish rebooting, then refresh your browser page. You should then see the KeySafe 5 Login page.

    If Refresh does not work, try to access the KeySafe 5 Appliance Management UI on a different node in the cluster. If the KeySafe 5 Appliance Management UI fails for all nodes, the hardware signature for one or more nodes may have changed during the upgrade. To restore access to KeySafe 5, contact Entrust nShield Technical Support at nshield.support@entrust.com.

  9. To verify the upgrade, return to Settings > System Upgrade and verify the settings for Current Version and Previous Version.

  10. The KeySafe 5 agents can now be updated and re-enrolled into the system, for more information please see KeySafe 5 Agent Installation.

Agent Upgrade

To update the KeySafe 5 agent installed on a machine:

  • Take a backup of the agent config directory located at %NFAST_DATA_HOME%/keysafe5/conf.

  • Uninstall the existing KeySafe 5 agent as detailed in the KeySafe 5 Installation Guide for the currently installed version of the product.

  • Install the new KeySafe 5 agent as detailed in chapter KeySafe 5 Agent Installation.

  • Restore existing agent configuration and restart the agent.

Upgrading supporting software

KeySafe 5 1.1 recommended MongoDB 5.0.10. This section details how to upgrade the software from these versions to the latest recommended compatible versions.

MongoDB 5.0.10 to 5.0.19

To update a non-Kubernetes existing Mongo install to a Mongo 5.0.19 install, see the official documentation at Upgrade to the Latest Revision of MongoDB.

To update a Mongo 5.0.10 install deployed via Bitnami Helm Charts:

# Obtain details of currently deployed helm charts
# Substitute chart and namespace values in the commands below as required
helm list -A

# Fetch current MongoDB helm chart deployed values
helm -n mongons get values --all --output yaml mongo-chart > mongo-chart-values.yaml

# Obtain the names of the existing mongo secrets
# Substitute secret names in the commands below as required
kubectl get secrets -n mongons

# Make copies of the existing secrets, this is required as the existing ones will be removed during the upgrade process
kubectl get secret mongodb-server-certificates -n=mongons -o yaml \
  | sed 's/mongodb-server-certificates/mongodb-server-certificates-upgrade/' \
  | kubectl apply -f -
kubectl get secret mongo-chart-mongodb -n=mongons -o yaml \
  | sed 's/mongo-chart-mongodb/mongo-chart-mongodb-upgrade/' \
  | kubectl apply -f -

# Upgrade helm chart based on existing deployed values
helm upgrade --install mongo-chart \
    --namespace=mongons \
    --values mongo-chart-values.yaml \
    --set image.tag=5.0.19-debian-11-r3 \
    --set auth.existingSecret=mongo-chart-mongodb-upgrade \
    --set tls.autoGenerated=false \
    --set tls.existingSecret=mongodb-server-certificates-upgrade\
    --wait --timeout 5m \
    bitnami/mongodb --version 12.1.31

# Obtain details of newly deployed helm charts
helm list -A

The helm listing for mongo-chart may fail to update app version from 5.0.10 to 5.0.19. This bug is only visual and the image will have updated successfully. This can be confirmed by using kubectl.

MongoDB User Configuration

To configure the MongoDB database correctly, access the MongoDB shell to create a user with the minimal permissions required for using the codesafe-mgmt-db, hsm-mgmt-db and sw-mgmt-db databases. See Database: User Roles.

Note that the username needs to match the subject of the client certificate, as found by the following command.

$ kubectl get secret --namespace nshieldkeysafe5 mongodb-client-certificates \
  -o jsonpath="{.data.tls\.crt}" | base64 --decode | \
  openssl x509 -out mongo-client-cert.pem
$ openssl x509 -in mongo-client-cert.pem -subject | head -n 1

In this example we will use ks5-mongo-user

We then run the mongo client container.

$ export MONGO1=mongo-chart-mongodb-0.mongo-chart-mongodb-headless.mongons.svc.cluster.local:27017
$ export MONGO2=mongo-chart-mongodb-1.mongo-chart-mongodb-headless.mongons.svc.cluster.local:27017
$ export MONGODB=${MONGO1},${MONGO2}
$ export MONGO_RUN="kubectl -n mongons exec mongo-chart-mongodb-0 0 -- "
$ export TLS_PRIVKEY="$(${MONGO_RUN} bash -c 'cat /certs/mongodb.pem')"
$ export TLS_CERT="$(${MONGO_RUN} bash -c 'cat /certs/mongodb-ca-cert')"
$ export MONGODB_ROOT_PASSWORD=$(kubectl get secret --namespace mongons \
  mongo-chart-mongodb-upgrade -o jsonpath="{.data.mongodb-root-password}" \
  | base64 --decode)
$ kubectl run --namespace mongons mongo-chart-mongodb-client \
  --rm --tty -i --restart='Never' --env="MONGODB_ROOT_PASSWORD=$MONGODB_ROOT_PASSWORD" \
  --image bitnami/mongodb:5.0.19-debian-11-r3 --command -- bash

Once inside the mongo client container, we need to set up a connection to the server before we can start mongo admin and create the user. After we finish creating the user, we need to exit mongo admin, and then the mongo-client container.

$ echo "$TLS_CERT" > /tmp/tls.crt
$ echo "$TLS_PRIVKEY" > /tmp/tls.key
$ mongo admin --tls --tlsCAFile /tmp/tls.crt --tlsCertificateKeyFile /tmp/tls.key \
  --host $MONGODB --authenticationDatabase admin -u root -p $MONGODB_ROOT_PASSWORD

> use admin
> db.createRole(
    role: "hsm-mgmt-db-user",
    privileges: [
          "resource": {"db": "hsm-mgmt-db", "collection": ""},
          "actions": ["createIndex", "find", "insert", "remove", "update"]
    roles: []
> db.createRole(
    role: "sw-mgmt-db-user",
    privileges: [
          "resource": {"db": "sw-mgmt-db", "collection": ""},
          "actions": ["createIndex", "dropCollection", "find", "insert", "remove", "update"]
    roles: []
> db.createRole(
    role: "codesafe-mgmt-db-user",
    privileges: [
          "resource": {"db": "codesafe-mgmt-db", "collection": ""},
          "actions": ["createIndex", "find", "insert", "remove", "update"]
    roles: []
> use $external
> x509_user = {
   "roles" : [
     {"role": "codesafe-mgmt-db-user", "db": "admin" },
     {"role": "hsm-mgmt-db-user", "db": "admin" },
     {"role": "sw-mgmt-db-user", "db": "admin" },
> db.updateUser("CN=ks5-mongo-user", x509_user)
> exit
$ exit