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.