Upgrading ESA to v10.2.0

• 1: System and License Requirements
• 2: Upgrade Paths to ESA v10.2.0
• 3: Prerequisites
• 4: Upgrading ESA to v10.2.0
• 4.1: Upgrading ESA from v9.1.0.x
• 4.2: Upgrading ESA from v9.2.0.x
• 4.3: Upgrading ESA from v10.0.x
• 4.4: Verifying the ESA Patch Installation
• 4.5: Verifying the health of Trusted Appliance Cluster
• 5: Restoring to the Previous Version of ESA
• 5.1: Restoring to the Previous Version of ESA On-premise
• 5.2: Restoring to the Previous Version of ESA Cloud platforms
• 5.3: Restoring to the Previous Version of ESA VMWare

1 - System and License Requirements

The following table lists the supported components and their compatibility settings.

The following table lists the minimum hardware configurations.

The following partition spaces must be available.

Software Requirements

Ensure that the software requirements are met before upgrading the appliance.

• The ESAs must be available on one of the following versions.
  • ESA v9.1.0.x
  • ESA v9.2.0.x
  • ESA v10.0.1 + v10.0.2 HF
  • ESA v10.1.0 + v10.1.1 HF
• At least three ESAs must be in a Trusted Appliance Cluster (TAC).
• At least three ESAs must be in the Audit Store Cluster.

Installation Requirements

The ESA_PAP-ALL-64_x86-64_10.2.0.UP.2631.pty patch file is available.

Ensure to download the latest patch for the respective version from the My.Protegrity portal.

For more information about the latest build number and the patch details, refer to the Release Notes of the respective patch.

Licensing Requirements

Ensure that a valid license is available before upgrading. If the license status is invalid, then contact Protegrity Support.

2 - Upgrade Paths to ESA v10.2.0

After succesfully upgrading the ESA to v10.2.0, apply the ESA 10.2.1 HF patch. This patch contains various vulnerability fixes, package updates, and bug fixes.

*indicates all the available hotfix and security patches on the platform version.

For example, to upgrade from the ESA v9.0.0.0 to the ESA v10.2.0, install the patches as follows:

1. ESA v9.1.0.x
2. ESA v10.2.0
3. Apply the ESA 10.2.1 HF patch.

For more information about upgrading the ESA to v10.2.0, refer Upgrading to v10.2.0.

Before installing any patch, refer to the Release Notes from the My.Protegrity portal.

The following table provides the recommended upgrade paths to the ESA v10.2.0.

To check the current version of the ESA:

1. From the ESA Web UI, navigate to System > Information.
   The current patch installed on the ESA is displayed.
2. Navigate to the About page to view the current version of the ESA.

For more information about:

• Upgrading to previous ESA versions, refer the Upgrade Guide for the respective versions on My.Protegrity portal.
  

• Applying the DSG patch on the ESA, refer Extending ESA with DSG Web UI in the Protegrity Data Security Gateway User Guide for the respective version.

3 - Prerequisites

Before you begin

It is recommended to download and run the ESA Readiness patch from the My.Protegrity portal. This patch verifies if the ESA satisfies the upgrade requirements.
After applying the ESA Readiness patch, if there are any errors, then ensure these errors must be resolved before applying the Upgrade patch.
For more information about the error Messages and resolutions, refer ESA Upgrade Readiness Patch Error Messages and Resolutions.

After all the conditions from the readiness patch are satisfied, perform the following steps.

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

Verifying the Presence of DTP/DTP2 Data Elements

If the DTP/DTP2 is present in the algorithm property of a data element while upgrading the ESA to v10.2, 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 to v10.2, 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.

Accounts

An account with administrative privileges 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 ESA to a previous version. Ensure to backup the complete OS or export the required files before initiating the patch installation process.

Backup operation must be performed on each ESA. While restoring the ESA using a backup, it must be done using the backup created for the same ESA. Do not use the same backup file to restore multiple ESAs.

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. Use a snapshot of an instance or a disk to backup and restore information in case of failures. Ensure that the latest snapshot is available before upgrading the ESA.

A snapshot of an instance or a disk can be created 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.

• Back up any custom configuration files or modified configuration files. If required, use the backup files to restore settings after the upgrade is complete.

• Validate that the backup files are created with the details appended to the extension, for example, .conf_backup, .conf_bkup123, or .conf_current_build_number.

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.

Enabling the local_admin Permissions

Ensure to configure the required permissions for the local_admin user.

To change local_admin account permissions:

1. Login to the CLI Manager.

2. Navigate to Administration > Accounts and Passwords > Manage Passwords and Local-Accounts > Change OS local_admin account permissions.

3. In the dialog box displayed, in the Password field, enter the local_admin password.

4. Select OK.

5. Specify the permissions for the local_admin. You can either select SSH Access, Web-Interface Access, or both.

6. Select OK.

External SIEM running

If an external SIEM is configured, ensure that the system is running and reachable during the upgrade.

4 - Upgrading ESA to v10.2.0

Before you begin

Ensure that the ESA is upgraded prior to upgrading the protectors.

4.1 - Upgrading ESA from v9.1.0.x

When ESA is upgraded from v9.1.0.x, then the process is completed over two phases.
During Phase 1, the Kernel, OS, and other components are upgraded. After the Phase 1 is completed, the system restarts automatically.

After the system restarts, Phase 2 begins automatically and the critical components of ESA are upgraded.

It is recommended to wait for a few minutes before logging in to the ESA using SSH, to view the upgrade progress.

If logging into the system using SSH is attempted immediately after the system restarts, then an error with Invalid Credentials appears. This may occur while LDAP upgrade is in process.

After the upgrade is successful, the system restarts automatically. After the system restarts, log in to the ESA using the CLI Manager or Web UI. When using the SSH, it is recommended to wait for a few minutes before logging in to the ESA.

While upgrading the ESA from v9.1.0.x, the entire process takes approximately 45 minutes. A temporary downtime is expected, resulting in limited access or intermittent interruptions.
Additionally, the time taken for creating the backup depends on the actual size of the data which is being backed up. The time taken for the backup is excluded from the upgrade process.

Uploading the patch using the CLI Manager

Perform the following steps to upload the patch from the CLI Manager:

1. Log in to the ESA CLI Manager with administrator credentials.
2. Navigate to Administration > OS Console to upload the patch.
3. Enter the root password and click OK.
4. Upload the patch to the /products/uploads directory using the FTP or SCP command.

The patch file is uploaded.

Installing the ESA patch from CLI Manager

Before you begin

• When upgrading nodes in an Audit Store cluster, if cluster-related checks pass on one node, you can safely ignore similar errors on the other nodes.

• While upgrading multiple nodes in the Audit Store cluster, the post-upgrade steps are completed successfully only after all cluster nodes are upgraded. A success message is then logged and shown to the user as a notification message, both, in the ESA UI and the CLI. Investigate post-upgrade errors only after all nodes are upgraded.

Perform the following steps to install the patch from the CLI Manager:

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

2. Navigate to Administration > Patch Management to install the patch.

3. Enter the root password and click OK.

4. Select Install a Patch.

5. Select the ESA_PAP-ALL-64_x86-64_10.2.0.UP.2631.pty patch file and select Install.
   

6. After Phase 1 is installed, following screen appears.

   

7. After the reboot is successful, Phase 2 begins automatically.

8. After Phase 2 is completed, a message for System going down for reboot now appears.
   After the reboot is successful, then the patch is installed successfully.

The patch is installed successfully and the ESA is upgraded to v10.2.0.

After upgrading the system successfully on v10.2.0, when using the SSH, it is recommended to wait for a few minutes before logging in to the ESA.

After succesfully upgrading the ESA to v10.2.0, apply the ESA 10.2.1 HF patch. This patch contains various vulnerability fixes, package updates, and bug fixes.

4.2 - Upgrading ESA from v9.2.0.x

When ESA is upgraded from v9.2.0.x, then the upgrade process happens in a single phase.

During the upgrade, the system displays the upgrade progress which appears on the ESA CLI Manager. After the upgrade is successful, the system restarts automatically.
After the system restarts, log in to the ESA using the CLI Manager or Web UI.

While upgrading the ESA from v9.2.0.x, the entire process takes approximately 30 minutes. A temporary downtime is expected, resulting in limited access or intermittent interruptions.
Additionally, the time taken for creating the backup depends on the actual size of the data which is being backed up. The time taken for the backup is excluded from the upgrade process.

Uploading the patch using the CLI Manager

Perform the following steps to upload the patch from the CLI Manager:

1. Log in to the ESA CLI Manager with administrator credentials.
2. Navigate to Administration > OS Console to upload the patch.
3. Enter the root password and click OK.
4. Upload the patch to the /products/uploads directory using the FTP or SCP command.

The patch file is uploaded.

Installing the ESA patch from CLI Manager

Before you begin

• When upgrading nodes in an Audit Store cluster, if cluster-related checks pass on one node, you can safely ignore similar errors on the other nodes.

• While upgrading multiple nodes in the Audit Store cluster, the post-upgrade steps are completed successfully only after all cluster nodes are upgraded. A success message is then logged and shown to the user as a notification message, both, in the ESA UI and the CLI. Investigate post-upgrade errors only after all nodes are upgraded.

Perform the following steps to install the patch from the CLI Manager:

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

2. Navigate to Administration > Patch Management to install the patch.

3. Enter the root password and click OK.

4. Select Install a Patch.

5. Select the ESA_PAP-ALL-64_x86-64_10.2.0.UP.2631.pty patch file and select Install.
   

6. After the patch is installed, select Reboot Now.

   

   This screen has a timeout of 60 seconds. If Reboot Now is not selected manually, then the system automatically reboots after 60 seconds.

7. After the reboot is initiated, the message Patch has been installed successfully !! appears. Select Exit.

The patch is installed successfully and the ESA is upgraded to v10.2.0.

After upgrading the system successfully on v10.2.0, when using the SSH, it is recommended to wait for a few minutes before logging in to the ESA.

After succesfully upgrading the ESA to v10.2.0, apply the ESA 10.2.1 HF patch. This patch contains various vulnerability fixes, package updates, and bug fixes.

4.3 - Upgrading ESA from v10.0.x

When ESA is upgraded from v10.0.1 or v10.1.0, ensure to apply the hotfix patch before applying the v10.2.0 upgrade patch.

If upgrading ESA from v10.0.1 or v10.1.0, then the upgrade process happens in a single phase.

During the upgrade, the system displays the upgrade progress which appears on the ESA CLI Manager. After the upgrade is successful, the system restarts automatically.
After the system restarts, log in to the ESA using the CLI Manager or Web UI.

While upgrading the ESA from v10.0.1 or v10.1.0, the entire process takes approximately 30 minutes. A temporary downtime is expected, resulting in limited access or intermittent interruptions.
Additionally, the time taken for creating the backup depends on the actual size of the data which is being backed up. The time taken for the backup is excluded from the upgrade process.

Uploading the ESA patch

The ESA patch can be uploaded using the Web UI or the CLI Manager but the patch should only be installed using the CLI Manager.

Uploading the patch using the Web UI

Perform the following steps to upload the patch from the Web UI:

1. Log in to the ESA Web UI with administrator credentials.

2. Navigate to Settings > System > File Upload.
   The File Upload page appears.

3. In the File Selection section, click Choose File.
   The file upload dialog box appears.

4. Select the patch file and click Open.

   • Only the files with .pty and .tgz extensions can be uploaded.
     
   • If the file uploaded exceeds the Max File Upload Size, then a password prompt appears. Enter the password and click Ok.
     

     Only a user with the administrative role can perform this action.

   • By default, the Max File Upload Size value is set to 25 MB. To increase this value, refer Increasing Maximum File Upload Size.

5. Click Upload.
   

6. After the file is uploaded successfully, then from the Uploaded Files area, choose the uploaded patch.
   The information for the selected patch appears.

   

Uploading the patch using the CLI Manager

Perform the following steps to upload the patch from the CLI Manager:

1. Log in to the ESA CLI Manager with administrator credentials.
2. Navigate to Administration > OS Console to upload the patch.
3. Enter the root password and click OK.
4. Upload the patch to the /products/uploads directory using the FTP or SCP command.

The patch file is uploaded.

Installing the ESA patch from CLI Manager

Before you begin

• When upgrading nodes in an Audit Store cluster, if cluster-related checks pass on one node, you can safely ignore similar errors on the other nodes.

• While upgrading multiple nodes in the Audit Store cluster, the post-upgrade steps are completed successfully only after all cluster nodes are upgraded. A success message is then logged and shown to the user as a notification message, both, in the ESA UI and the CLI. Investigate post-upgrade errors only after all nodes are upgraded.

Perform the following steps to install the patch from the CLI Manager:

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

2. Navigate to Administration > Patch Management to install the patch.

3. Enter the root password and click OK.

4. Select Install a Patch.

5. Select the ESA_PAP-ALL-64_x86-64_10.2.0.UP.2631.pty patch file and select Install.
   

6. After the patch is installed, select Reboot Now.

   

   This screen has a timeout of 60 seconds. If Reboot Now is not selected manually, then the system automatically reboots after 60 seconds.

7. After the reboot is initiated, the message Patch has been installed successfully !! appears. Select Exit.

The patch is installed successfully and the ESA is upgraded to v10.2.0.

After upgrading the system successfully on v10.2.0, when using the SSH, it is recommended to wait for a few minutes before logging in to the ESA.

After succesfully upgrading the ESA to v10.2.0, apply the ESA 10.2.1 HF patch. This patch contains various vulnerability fixes, package updates, and bug fixes.

4.4 - Verifying the ESA Patch Installation

Verifying the ESA version

Perform the following steps to verify the patch installation:

1. From the ESA Web UI, navigate to System > Information.
   The current patch installed on the ESA is displayed.
2. Navigate to the About page to view the current version of the ESA.

The ESA is upgraded to v10.2.0.

Verifying Upgrade Logs

During the upgrade process, logs describing upgrade process are generated. The logs describe the services that are initiated, restarted, or the errors generated.

To view the logs under the /var/log directory from the CLI Manager, navigate to CLI Manager > Administration > OS console.

4.5 - Verifying the health of Trusted Appliance Cluster

After upgrading all the ESAs in the Trusted Appliance Cluster to v10.2.0, ensure that all the nodes in the cluster are healthy.

Perform the following steps to verify health of ESAs in the TAC.

These steps must be performed individually on each ESA node in the Trusted Appliance Cluster.

1. From the ESA Web UI, navigate to System > Trusted Appliance Cluster.
2. Verify the details for each node in the TAC.
3. In the Status field, the ESA node must be Online.
4. In the Status Message field, no errors must be displayed.
5. In the Labels field, each node must be labeled as Consul Server or Consul Client.
   If the label for any ESA node is not Consul Server or Consul Client, then refer Common ESA Errors.

5 - Restoring to the Previous Version of ESA

5.1 - Restoring to the Previous Version of ESA On-premise

To roll back the system to the previous version, perform the steps to restore the system.
This helps in cases such as when an upgrade fails.

Perform the steps to restore to the previous version of the ESA on-premise.

1. From the CLI Manager, navigate to Administration > Reboot And Shutdown > Reboot to restart the system.
   A screen to enter the reason for restart appears.
2. Enter the reason and select OK.
3. Enter the root password and select OK.
   The appliance restarts and the following screen appears.
   
4. Select System-Restore and press ENTER.
   The Welcome to System Restore Mode screen appears.
5. Select Initiate OS-Restore Procedure and select OK.
   

   The Boot Into System-Restore Partition option is deprecated from this release. Ensure to only use Initiate OS-Restore Procedure option to restore to the previous stable version.

The restore procedure is initiated.

After the OS-Restore procedure is completed, the login screen appears.

5.2 - Restoring to the Previous Version of ESA Cloud platforms

This section describes restoring the ESA on Cloud platforms, such as, Amazon Web Services (AWS), Azure, or Google Cloud Platform (GCP). For installing the ESA on cloud platforms, you must mount the image containing the ESA on a cloud instance or a virtual machine. After mounting the image, you must run the finalization procedure to install the ESA components.

5.3 - Restoring to the Previous Version of ESA VMWare

This section describes creating a snapshot and restoring the ESA on VMWare to the previous version.

Creating a Snapshot on VMWare

To create a snapshot on VMWare:

1. Log in to the VMware Client console.
2. Navigate to Inventories > VMs and Templates.
3. From the left navigation pane, select the required project.
4. Select the required OVA template.
5. Right-click the VM and select Snapshot > Take Snapshot. The Take Snapshot screen appears.
6. Enter a name and description for the snapshot.
7. Click Take Snapshot.
8. Check “Snapshot the virtual machine’s memory” for a full state capture.
9. Click OK.

Restoring a Snapshot on VMWare

To restore a snapshot on VMWare:

1. Log in to the VMware Client console.
2. Navigate to Inventories > VMs and Templates.
3. From the left navigation pane, select the required project.
4. Select the required OVA template.
5. Right-click the VM and select Snapshot > Snapshot Manager.
6. Select the required snapshot.
7. Click Go To.

The snapshot is added to the VMWare.