Upgrading to DSG 4.0.0

The DSG v4.0.0 can be upgraded on an on-premise or cloud platforms. It can be upgraded to 4.0.0 from the following versions:

• 3.3.0.1
• 3.3.0.0
• 3.2.0.1
• 3.2.0.0
• 3.1.0.x (3.1.0.0 through 3.1.0.7)

Upgrading DSG and ESA

The DSG patch in ESA is added to extend the DSG functionality on ESA. It allows ESA to deploy configurations to other DSG nodes.

The following figure illustrates DSG component upgrade on ESA.

The following figure illustrates the DSG upgrade.

Upgrade process

Upgrading the DSG version involves a series of steps that must be performed on ESA and DSG. The following order illustrates the upgrade process.

Before you begin

• Ensure that DSG and ESA are backed up. For more information about backing up, refer to Backing up from the Web UI.

• Ensure that communication is established between the ESA and DSG.

• Ensure that DSGs and ESA are in a cluster. All the DSGs in the cluster are healthy.

• Ensure that the buffer folders in /opt/protegrity/fluent-bit/data/buffer/tcp.<n> and /opt/protegrity/td-agent/es_bufferare empty. If these folders are not empty, check for errors in /var/log/td-agent/td-agent.log or /opt/protegrity/fluent-bit/data/logforwarder.log.

• Record any configurations added to the /opt/protegrity/alliance/config/features.json file. These configurations will not be retained after the upgrade.

• Ensure that the configurations in the alliance_audit.conf are noted. These configurations must be added after the upgrade is completed.

• Configure Ruleset definitions on the ESA to push the same configuration to all cluster nodes. Perform any import/export of DSG and Ruleset configurations from the ESA Web UI only.

• In DSG, the custom files related to LogForwarder are placed in the /opt/protegrity/fluent-bit/data/config.d directory. These files can be configured as required. When the the upgrade is in process, DSG backs up the custom LogForwarder files. The files are moved to the /opt/protegrity/fluent_backup directory. However, after the upgrade is completed, the files are not automatically restored to the /opt/protegrity/fluent-bit/data/config.d directory. All the custom configuration files and the modifications to existing default configuration files done before upgrade must to be manually applied after upgrade.

Export/import of DSG configurations and Ruleset configurations to DSG v4.0.0 is supported only from DSG v3.1.0.x and higher. Do not import DSG Ruleset backups (.zip) from older DSG versions into DSG v4.0.0. Navigate to Settings > Backup & Restore to export/import the DSG configurations.

• If Codebook reshuffling is used, back up the following files on each DSG node:

  • random.dat (BLOB)
  • userpin.bin (User PIN)

  For backing up the files, create a .tgz file using the following command.

   tar --same-owner -zcpvf /products/uploads/<filename>.tgz \
   /opt/protegrity/defiance_dps/data/random.dat \
   /opt/protegrity/defiance_dps/data/userpin.bin \
  

  Run the following command to set the required permissions for downloading the .tgz package from the DSG Web UI.

  chmod 644 /products/uploads/<filename>.tgz
  

  Perform the following steps to download the .tgz package from the DSG Web UI.

  1. Login to the DSG Web UI.
  2. On the DSG Web UI, navigate to Settings > System > File Upload.
  3. Select the .tgz file from the Uploaded Files drop-down and click Download.

Uploading and Installing the Patch

The patch can be uploaded from the CLI Manager or the Web UI.

Uploading patch from Web UI.

1. Log in to the Web UI with administrator credentials.
2. Navigate to Settings > System > File Upload.
3. In the File Selection section, click Choose File.
4. Select the patch file and click Open. Only the files with .pty and .tgz extensions can be uploaded.
5. Click Upload.

Uploading patch from CLI Manager

1. Log in to the 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 /opt/products_uploads directory using the FTP or SCP command.

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

1. Log in to the 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 required patch and select Install.

Upgrading to DSG v4.0.0 from DSG v3.3.0.x

Steps to upgrade to DSG v4.0.0 from the following version of DSG:

• 3.3.0.1
• 3.3.0.0

Prerequisites

• Ensure that ESA 10.1.0 is available with the DSG v3.3.0.x patch applied on it.

• Ensure that DSG v3.3.0.x is available.

Upgrade Procedure

• ESA 10.1.0
• DSG

Ensure that all the required nodes are upgraded to v4.0.0. After installing the patches perform the post upgrade steps.

Upgrading to DSG v4.0.0 from DSG v3.3.0.0

Steps to upgrade to DSG v4.0.0 from DSG v3.3.0.0.

Prerequisites

• Ensure that ESA v10.0.1 is available with the DSG v3.3.0.0 patch applied on it.

• Ensure that DSG v3.3.0.0 is available.

Upgrade Procedure

• ESA 10.0.1
• DSG

Ensure that all the required nodes are upgraded to v3.3.0.1. After installing the patches perform the post upgrade steps.

Upgrading to DSG v4.0.0 from DSG v3.2.0.x

Steps to upgrade to DSG v4.0.0 from the following versions of DSG.

• 3.2.0.0
• 3.2.0.1

Prerequisites

• Ensure that ESA v9.2.0.x with the corresponding DSG v3.2.0.x patch applied on it.

• Ensure that DSG v3.2.0.x is available.

Upgrade Procedure

• ESA
• DSG

Ensure that all the required nodes are upgraded to v4.0.0. After installing the patches perform the post upgrade steps.

Upgrading to DSG v4.0.0 from DSG v3.1.0.x

Steps to upgrade to DSG v4.0.0 from any of the following DSG versions:

• 3.1.0.7
• 3.1.0.6
• 3.1.0.5
• 3.1.0.4
• 3.1.0.3
• 3.1.0.2
• 3.1.0.1
• 3.1.0.0

Prerequisites

• Ensure that ESA v9.1.0.x is available with the corresponding DSG v3.1.0.x patch applied on it.

• Ensure that corresponding DSG v3.1.0.x is available.

Upgrade Procedure

• ESA
• DSG

Ensure that all the required nodes are upgraded to v4.0.0. After installing the patches perform the post upgrade steps.

Post Upgrade Steps

The post upgrade steps must be performed only after each DSG node is upgraded to v4.0.0. Run the following steps after upgrade is completed.

• Log forwarder custom files backed up during upgrade must be restored.

• If codebook reshuffling was set up and working before the upgrade, all configurations will migrate automatically. To verify, check if the blob management service is running post‑upgrade.If codebook shuffling is still not working, manually restore the following files.

  • random.dat (BLOB)
  • userpin.bin (User PIN)

  For more information about restoring the files, refer to Restore Backed up Files for Codebook Reshuffling.

• Scheduled tasks related to DSG on the Audit Store are enabled. The DSG metrics logs that are generated over time can be scheduled for cleanup regularly. Click Audit Store > Analytics > Scheduler, select the Delete DSG Error Indices, Delete DSG Usage Indices, or Delete DSG Transaction Indices, and then click Edit to modify the scheduled task that initiates the Indices file cleanup at regular intervals. The scheduled task can be set to n days based on your preference.

• If DSG is upgraded from versions prior to 3.3.0.1, the following steps must be performed.

  Ensure that the restore operation is only performed on the registered DSG node.

  1. Restore DSG TACs from the primary DSGs that were earlier a part of TAC from a primary DSG.

     1. Choose an upgraded DSG as a primary DSG.

     2. On the CLI Manager, navigate to Tools > Restore DSG-DSG TAC.

     3. Enter the appropriate user credentials and select OK.

        All the The DSGs that were a part of a TAC and upgraded are now restored.

  2. Perform the ESA communication from the all DSG.

  3. Register DSG node on ESA.

• The blocked_modules and blocked_methods added in the gateway.json file before upgrade are retained after the DSG is upgraded. However, it is recommended to use the allowed modules and methods for enhanced security. For more information about blocked and allowed modules, refer to

• If any changes are made on a DSG node in the cluster, then create a scheduler task to replicate policies, configuration, DSG rulesets, and so on, from the DSG having changes to the other DSGs in the cluster.

• Restore the configurations in the alliance_audit.conf file.

• If the DSG configurations were deployed to specific node groups before upgrade, ensure that the configurations are deployed again to the respective node groups again after the upgrade is completed. If no specific node groups are available, deploy the configurations to all the nodes.

Canary Upgrade

In a canary upgrade, the DSG nodes are re-imaged to v4.0.0. The DSG image is installed afresh on an existing or a new system.

Before proceeding with the upgrade, back up the PEP server configuration from the DSG nodes. Run the following steps.

1. Login to the DSG Web UI.
2. Navigate to Settings > System.
3. Under the Files tab, download the pepserver.cfg file.
4. Repeat step 1 to step 3 on each DSG node in the cluster.

Consider the following figure.

1. Run the following steps on ESA A.

   1. Remove the ESA A from the cluster.
   2. Upgrade the ESA A to v10.2.0.
   3. If the ESA is not accessible through host name, add the following host details:
      • Host details of ESA B.
      • Host details of node A, node B, node C, and node D.
   4. Create a cluster.

2. Run the following steps on node A.

   1. Remove node A from the cluster.
   2. Re-image the node A to v4.0.0.
   3. If the ESA is not accessible through host name, add the following host details:
      • Host details of ESA A and B.
      • Host details of node B, node C, and node D.
   4. Run the set communication for node A to communicate with the upgraded ESA A.
   5. Restore the pepserver.cfg file that was backed up for node A.
   6. Create a cluster on the node.

3. Run the following steps on node B.

   1. Remove node B from the cluster.
   2. Re-image node B to v 4.0.0.
   3. If the ESA is not accessible through host name, add the following host details:
      • Host details of ESA A and B.
      • Host details of node A, node C, and node D.
   4. Restore the pepserver.cfg file backed up for node B.
   5. Join node B to the cluster created on node A.

4. Run the following steps on node C.

   1. Remove node C from the cluster.
   2. Re-image node C to v 4.0.0.
   3. If the ESA is not accessible through host name, add the following host details.
      • Host details of ESA A and B.
      • Host details of node A, node B, and node D.
   4. Restore the pepserver.cfg file backed up for node C.
   5. Join node C to the cluster created on node A.

5. Run the following steps on node D.

   1. Remove node D from the cluster.
   2. Re-image node D to v 4.0.0.
   3. If the ESA is not accessible through host name, add the following host details.
      • Host details of ESA A and B
      • Host details of node A, node B, and node C.
   4. Restore the pepserver.cfg file that was backed up for node D.
   5. Join node D to the cluster created on node A.

6. Run the following steps on ESA B.

   1. Remove node D from the cluster.
   2. Upgrade ESA B to v10.2.0.
   3. If the ESA is not accessible through host name, add the following host details:
      • Host details of ESA A.
      • Host details of node A, node B, node C, and node D.
   4. Join ESA B to the cluster created on ESA A.

The following figure illustrates the upgraded setup.

After upgrading the DSG nodes, if codebook reshuffling was enabled on your older system, you must restore the codebook reshuffling parameters. For detailed steps, refer to the section Restore Backed up Files for Codebook Reshuffling.