Upgrading to DSG 3.3.0.1

The DSG v3.3.0.1 can be upgraded on an on-premise or cloud platforms. It can be upgraded to 3.3.0.1 from the following versions:

• 3.3.0.0
• 3.2.0.1
• 3.2.0.0
• 3.1.0.x (3.1.0.0 through 3.1.0.6)
• 3.0.0.0

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 ESAs and DSGs are accessible through their hostnames. If not, refer to Update Host Details for the detailed steps.

• 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 configurations in the pepserver.cfg are saved for each DSG node in the cluster. These configurations must be manually set after upgrade. For more information about the PEP server, refer to Managing PEP server

• 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 v3.3.0.1 is supported only from DSG v3.0.0.0 and higher. Do not import DSG Ruleset backups (.zip) from older DSG versions into DSG v3.3.0.1. 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)
  • dps.env
  • userpin.bin (User PIN)

  After 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 \
   /opt/protegrity/defiance_dps/bin/dps.env
  

  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.

• Save the details of the TAC before starting the upgrade. For more information about the TAC, refer to Trusted Appliances Cluster.

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 v3.3.0.1 from DSG v3.3.0.0

Steps to upgrade to DSG v3.3.0.1 from DSG v3.3.0.0.

Prerequisites

• Ensure that ESA v10.0.1 or ESA 10.1.0 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.1.0
• 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 v3.3.0.1 from DSG v3.2.0.1

Steps to upgrade to DSG v3.3.0.1 from DSG v3.2.0.1.

Prerequisites

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

• Ensure that DSG v3.2.0.1 is available.

Upgrade Procedure

• ESA
• 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 v3.3.0.1 from DSG v3.2.0.0

Steps to upgrade to DSG v3.3.0.1 from DSG v3.2.0.0.

Prerequisites

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

• Ensure that DSG v3.2.0.0 is available.

Upgrade Procedure

• ESA
• 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 v3.3.0.1 from DSG v3.1.0.x

Steps to upgrade to DSG v3.3.0.1 from any of the following DSG versions:

• 3.1.0.0
• 3.1.0.2
• 3.1.0.3
• 3.1.0.4
• 3.1.0.5
• 3.1.0.6

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.2.0.x is available.

Upgrade Procedure

• ESA
• 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 v3.3.0.1 from DSG v3.0.0.0

Steps to upgrade to v3.3.0.1 from DSG v3.0.0.0.

Prerequisites

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

• Ensure that DSG v3.0.0.0 is available.

Upgrade Procedure

• ESA
• DSG

Ensure that all the required nodes are upgraded to v3.3.0.1. 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 v3.3.0.1. Run the following steps after upgrade is completed.

• Log forwarder custom files backed up during upgrade are restored.

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

  • random.dat (BLOB)
  • dps.env
  • 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.

• 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

• PEP server configurations for the respective DSG nodes are added in the pepserver.cfg file. For more information about the PEP server, refer to Managing PEP server.

• Run the command to create a trusted appliances cluster. For more information about the creating TAC, refer to Trusted Appliances Cluster.

• 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.

• Run the set ESA communication on the DSG nodes. For more information, refer to Setting up ESA communication.

• Ensure that the primary DSG node is registered with all ESA nodes. For more information about registering DSG, refer to Registering the DSG.

Canary Upgrade

In a canary upgrade, the DSG nodes are re-imaged to v.3.3.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.1.x.
   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 v3.3.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 3.3.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 3.3.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 3.3.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.1.x.
   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.