Prerequisites

Prerequisites before upgrading the ESA from v9.2.0.1 to v10.0.x.

Verifying the protector compatibility

The ESA v10.0.x only supports protectors having the PEP server version 1.2.2+42 and later.

During the upgrade, the process checks if any unsupported protector is registered in the system.
If the protector is not compatible with the ESA, then the ESA upgrade process terminates.
Unsupported protectors must be updated to a supported version before upgrading the ESA. After upgrading the protector, continue to upgrade the ESA to v10.0.x.

Perform the following steps to identify the PEP server version of the protector:

  1. Log in to the ESA.
  2. Navigate to Policy Management > Nodes.
  3. View the Version field for all the protectors.

If the protector version is unsupported, perform one of the following actions:

  • Uninstall the unsupported protector and delete the node from the list of registered nodes.
  • Upgrade the unsupported protector to a supported version. For most of the protectors, this process involves uninstalling and installing the protectors. However, some protectors, such as Data Security Gateway (DSG) and Big Data Protector (BDP), might support the upgrade process. The new installed protector updates the registered node entry.

Verifying the Presence of DTP/DTP2 Data Elements

If the DTP/DTP2 is present in the algorithm property of a data element while upgrading from the ESA v9.2.0.1 to v10.0.x, then the upgrade script fails. The following error message appears:

ERROR: Found unsupported DTP data elements

Perform the following actions:

  1. Reprotect data with a new data element that does not have DTP/DTP2 formatting.
  2. Remove the data elements that contain DTP/DTP2 algorithm.

This prevents the data loss that occurs during the upgrade. The DTP/DTP2 data elements are now unsupported.

For more information about the data elements to be used, contact Protegrity Support.

Verifying the Presence of FPE Data Elements with Left and/or Right in Clear Settings

If the format-preserving encryption (FPE) data elements with Left and Right settings are present when you upgrade the ESA from v9.2.0.1 to v10.0.x, then the upgrade script fails. The following error message appears:

ERROR: FPE Data Element(s) with characters in clear ('From Left' / 'From Right') are no longer supported on the target version.  
   Please consult the documentation or Protegrity staff for guidance. 
   Data Element(s) affected: <List of affected data elements>

Perform the following actions:

  1. Reprotect data with a new data element that does not have Left and Right settings.
  2. Remove the data elements that contain Left and Right settings.

This prevents the data loss that occurs during the upgrade. The FPE data elements with Left and Right settings are now unsupported.

For more information about the data elements to be used, contact Protegrity Support.

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.

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.

  • Backing up specific components of your appliance using the File Export option. Ensure to create a back up 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.

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.

Exporting data/configuration to remote appliance

The backup configurations to a remote appliance can be exported.

The following scenario illustrates the steps performed for a successful export of the backup configuration.

  1. Log in to the CLI Manager.
  2. Navigate to Administration > Backup/Restore Center.
  3. Enter the root password and select OK.
    The Backup Center dialog box appears.
  4. From the menu, select the Export data/configurations to a remote appliance(s) option and select OK.
  5. From the Select file/configuration to export dialog box, select Current (Active) Appliance Configuration package to export and select OK.
  6. Select the packages to export and select OK.
  7. Select the Import method.
    For more information on each import method, select Help.
  8. Type the IP address or hostname for the destination appliance.
  9. Type the administrative credentials of the remote appliance and select Add.
  10. In the information dialog box, press OK.
    The Backup Center screen appears.

Avoid importing all network settings to another machine. This action will create two machines with the same IP in the network. It is recommended to restart the appliance after receiving an appliance core configuration backup.

This item shows up only when exporting to a file.

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:

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.

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.

Rotating the Keys

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.

For more information about rotating keys, refer Working with Keys in the Protegrity Key Management.

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.

Last modified : February 06, 2025