Prerequisites

Verifying the License Status

Before upgrading the ESA, ensure that the license is not expired or invalid.

An expired or invalid license blocks policy services on the ESA and Devops API’s. A new or existing protector will not receive any policies until a valid license is applied.

For more information about the license, refer Protegrity Data Security Platform Licensing.

Verifying the GPG Public Key

The GPG Public Key used to sign Debian packages embedded in Protegrity appliances expired on April 9, 2024. The appliances installed before this date will continue to function, however issues will occur when upgrading or applying any maintenance patches to these appliances.

To avoid any potential issues, it is recommended to apply the PAP_PAP-ALL-64_x86-64_Generic.V-6.pty patch to extend the expiry date of the GPG Public Key used to sign Debian packages embedded in Protegrity appliances. This patch must be applied before applying maintenance releases or upgrading the ESA.

The following table lists the appliances and the affected versions.

For more information, refer the following GPG Public Key Expiration announcement on My.Protegrity.com portal.

https://my.protegrity.com/notifications/GPG-notification#_New_Installations

Configuring Keys and HSM

• If the security keys, such as, master key or repository key have expired or are due to expire within 30 days, then the upgrade fails. Thus, you must rotate the keys before performing the upgrade. Additionally, ensure that the keys are active and in running state.

  For more information about rotating keys, refer to Working with Keys.

• If you are using an HSM, ensure that the HSM is accessible and running.

  For more information about HSM, refer to the corresponding HSM vendor document.

If the prerequisites are not met, the ESA upgrade process fails. In such a case, it is required to restore the ESA to its previous stable version.

Accounts

The administrative account used for upgrading the ESA must be active.

Backup and Restore

The OS backup procedure is performed to backup files, OS settings, policy information, and user information. Ensure that the latest backup is available before upgrading to the latest version.

If the patch installation fails, then you can revert the changes to a previous version. Ensure to backup the complete OS or export the required files before initiating the patch installation process.

For more information about backup and restore, refer here.

• Ensure to perform backup on each ESA separately. The IP settings will cause an issue if the same backup is used to restore different nodes.
• Backup specific components of your appliance using the File Export option. Ensure to create a backup of the Policy Management data, Directory Server settings, Appliance OS Configuration, Export Gateway Configuration Files, and so on.
• While upgrading an ESA with the DSG installed, select the Export Gateway Configuration Files option and perform the export operation.

Full OS backup

The entire OS must be backed up to prevent data loss. This allows the OS to be reverted to a previous stable configuration in case of a patch installation failure. This option is available only for the on-premise deployments.

The Full OS Backup/Restore features of the Protegrity appliances is available only for the on-premise deployments. It is not available for virtual machines created using an OVA template and cloud-based virtual machines.

Perform the following steps to backup the full OS configuration:

1. Log in to the ESA Web UI.
2. Navigate to System > Backup & Restore > OS Full, to backup the full OS.
3. Click Backup.

The backup process is initiated. After the OS Backup process is completed, a notification message appears on the ESA Web UI Dashboard.

Creating a snapshot for cloud-based services

A snapshot represents a state of an instance or disk at a point in time. You can use a snapshot of an instance or a disk to backup and restore information in case of failures. Ensure that you have the latest snapshot before upgrading the ESA.

You can create a snapshot of an instance or a disk on the following platforms:

• Amazon Web Services (AWS)

• Microsoft Azure

• Google Cloud Platform (GCP)

Validating Custom Configuration Files

Complete the following steps if you modified any configuration files.

• Review the contents of any configuration files. Verify that the code in the configuration file is formatted properly. Ensure that there are no additional spaces, tabs, line breaks, or control characters in the configuration file.
• Validate that the backup files are created with the details appended to the extension, for example, .conf_backup or .conf_bkup123.
• Back up any custom configuration files or modified configuration files. If required, use the backup files to restore settings after the upgrade is complete.

While using protectors below version 10.x, if any changes are made to the ulimit, then the changes are retained after the ESA upgrade is completed successfully.

Trusted Appliance Cluster (TAC)

While upgrading an ESA appliance that is in a TAC setup, delete the cluster scheduled tasks and then, remove the ESA appliance from the TAC.

For more information about TAC, refer here.

Deleting a Scheduled Task

Perform the following steps to delete a scheduled task:

1. From the ESA Web UI, navigate to System > Task Scheduler.
   The Task Scheduler page displays the list of available tasks.
2. Select the required task.
3. Select Remove.
   A confirmation message to remove the scheduled task appears.
4. Click OK.
5. Select Apply to save the changes.
6. Enter the root password and select Ok.
   The task is deleted successfully.

Removing a Node from the Cluster

While upgrading an ESA appliance that is in a Trusted Appliance Cluster (TAC) setup, remove the the ESA appliance from the TAC and then apply the upgrade patch.

If a node is associated with a cluster task, then the Leave Cluster operation does not remove the node from the cluster. Ensure to delete all such tasks before removing any node from the cluster.

Perform the following steps to remove a node from a cluster:

1. From the ESA Web UI of the node that you want to remove from the cluster, navigate to System > Trusted Appliances Cluster.
   The screen displaying the cluster nodes appears.
2. Navigate to Management > Leave Cluster.
   A confirmation message appears.
3. Select Ok.
   The node is removed from the cluster.

For more information about TAC, refer here.

Disabling the Audit Store Cluster Task

Perform the following steps to disable the task:

1. Log in to the ESA Web UI.
2. Navigate to System > Task Scheduler.
3. Select the Audit Store Management - Cluster Config - Sync task.
4. Click Edit.
5. Clear the Enable check box.
6. Click Save.
7. Click Apply.
8. Enter the root password and click OK.
9. Repeat the steps on all the nodes in the Audit Store cluster.

Disabling Rollover Index Task

Perform the following steps to disable the Rollover Index task:

1. Log in to the ESA Web UI on any of the nodes in the Audit Store cluster.

2. Navigate to Audit Store > Analytics > Scheduler.

3. Click Enable for the Rollover Index task.

   The slider moves to the off position that it turns grey in color.

4. Enter the root password and click Submit to apply the updates.

5. Repeat steps 1-4 on all nodes in the Audit Store cluster, if required.

Deleting patches from /products/uploads directory

The /products/uploads directory contains all the previously uploaded patches. Before upgrading the ESA, it is recommended to remove these already installed patches from this directory. Ensure that only the required patches are present.

When multiple patches exist, the Patch Manager may take longer to display them. After the available patches are listed, select the required patch to install.

Perform the following steps to delete patches from the directory:

1. Log in to the ESA CLI Manager with administrator credentials.

2. Navigate to Administration > OS Console.

3. Enter the root password and click OK.

4. Delete a patch from the /products/uploads directory using the following command:

   cd /products/uploads && rm -rf <Patch name>
   

   The above command deletes one patch at a time. Repeat this step to delete any other patches that are already installed.

The patches are deleted successfully from the /products/uploads directory.