Upgrading DSS Hub on Linux - DSS 6 | Data Source Solutions Documentation

Documentation: Upgrading DSS Hub on Linux - DSS 6 | Data Source Solutions Documentation

Upgrading DSS Hub on Linux

This section describes the requirements and step-by-step instructions on how to upgrade the DSS Hub System to a new version on Linux.

For upgrading the DSS Agent, see Upgrading DSS Agent.

In the case of a distributed setup, along with the DSS Hub System installation, there may be one or more DSS Agent installations on the source and target machines. Since DSS versions 6.1.0 and higher are fully compatible with each other, upgrading all installations may not be required.

Each DSS release contains new features and/or fixes for certain bugs. Each feature or fix is only effective if the correct machine is upgraded. Typically, the release notes (also available in DSS_HOME/dss.rel directory and on the downloads page) contain information about which features and fixes have been added and which machines must be upgraded for each feature and fix to be effective. New features should not be used until all machines that are specified for that feature are upgraded; otherwise, errors may occur.

For example, if a new release fixes an Integrate bug, then that release must be installed on the DSS Agent machine(s) that performs Integrate. There will be no benefit if only the DSS Hub System is upgraded using that release.

Requirements

Following are the prerequisites for upgrading the DSS Hub System on Linux:

DSS installation file
Obtain the latest version of the DSS Hub System installation file for Linux (e.g., datasourcesolutions-6.2.0-hub_and_agent-linux_glibc2.12-x64-64bit_ga.tar.gz). You can downloaded the installation file from the Downloads tab in the Data Source Solutions dashboard. For more information, see Downloading DSS.
Backup the DSS directories and repository database:
- Create a backup of the directories DSS_HOME (installation files) and DSS_CONFIG (DSS state).
- Create a backup of the repository database, which contains metadata definitions and settings. Use the native backup option provided by the DBMS.
- Optionally, save a hub snapshot using the UI option Save Hub Snapshot or the command dsssnapshotsave.

Creating a backup is essential because it provides a reliable method to roll back or downgrade to the previous stable version if issues arise during an upgrade. This ensures that all data and settings can be restored to their original state if needed.
Downgrading using a hub snapshot is more complex than using a hub repository database backup. The hub snapshot contains only the hub configuration.

Upgrade Steps

Perform the following steps to upgrade the DSS Hub System:

Perform steps 1 - 3 for all active channels.

Suspend the capture job running in a channel. {% tabs %}

{% tab label="CLI" %}

Run the command dsssuspend.
```
dsssuspend <em>hub channel</em>-cap
```
{% /tab %}

{% tab label="UI" %}
1. Go to the Channel Details page.
2. In the Jobs pane, select the capture job and click Suspend Jobs at the top right of the Jobs pane.
{% /tab %}

{% /tabs %}
Ensure that the integrate job finishes integrating all the changes. This can be verified as follows: {% tabs %}

{% tab label="CLI" %}
1. No transaction (.tx) files are left in the router directory ($DSS_CONFIG/hubs/hub/channels/channel/locs/src_loc/router/loc_tgt_loc/).
2. The integrate job has status Waiting... in the channel-integ-location.out log file located at $DSS_CONFIG/hubs/hub/logs/.
{% /tab %}

{% tab label="UI" %}
1. No transaction (.tx) files are left in the router directory ($DSS_CONFIG/hubs/hub/channels/channel/locs/src_loc/router/loc_tgt_loc/).
2. In the Jobs pane, click the View Log button next to the integrate job. The integrate job has status Waiting....
Alternatively, you can check for the same status in the channel-integ-location.out log file located at $DSS_CONFIG/hubs/hub/logs/.

{% /tab %}

{% /tabs %}
Suspend the integrate job. {% tabs %}

{% tab label="CLI" %}

Run the command dsssuspend.
```
dsssuspend <em>hub channel</em>-integ
```
{% /tab %}

{% tab label="UI" %}
1. Go to the Channel Details page.
2. Under the Jobs pane, select the integrate job and click Suspend Jobs at the top right of the Jobs pane.
{% /tab %}

{% /tabs %}
Stop the DSS Hub Server.
- If the Hub Server is configured with systemd, use the command systemctl to terminate the process.
```
systemctl stop dsshubserver
```
- If the Hub Server is NOT configured with systemd, use the command dsshubserver to terminate the process.
```
dsshubserver -k
```

Ensure that all DSS processes have stopped. To verify whether any DSS processes are still running, use a command like the following: shell ps -ef | grep dss If any DSS processes are running, use the kill command to terminate the process.

Install the new version of the DSS Hub System; uncompress the installation file (e.g., datasourcesolutions-6.1.0_21-hub_and_agent-linux_glibc2.12-x64-64bit_ga_patch.tar.gz) into the DSS_HOME directory.
```
cd $DSS_HOME
```
```
tar xzf /tmp/datasourcesolutions-6.1.0_21-hub_and_agent-linux_glibc2.12-x64-64bit_ga_patch.tar.gz
```
Start the DSS Hub Server by using the command dsshubserver.
```
dsshubserver -d
```
Activate replication in the channel to capture changes from the beginning of the oldest current (not closed) transaction, regenerate jobs and enroll information for tables.

Perform this step for all the channels.

In some cases, other replication components should also be reactivated depending on the type of changes contained in the version being installed.

{% tabs %}

{% tab label="CLI" %}

Run the dssactivate command with options -J and -oje. This will update the job scripts, scheduler jobs, job groups and extend the enrollment details for tables.

dssactivate -J cap -J integ -oje <em>hub channel</em>

Alternatively, run the dssactivate command with options -J and -ojE. This will update the job scripts, scheduler jobs, job groups and recreate the enroll file for all tables in the channel.

```shell

dssactivate -J cap -J integ -ojE hub channel


{% /tab %}

{% tab label="UI" %}

   1. Go to the [**Channel Details**](/docs/dss6-user-interface-channels-channel-details) page and click [**Activate Replication**](/docs/dss6-user-interface-channels-activating-replication).
   2. In the **Activate Replication** dialog, under [**Replication Components**](/docs/dss6-user-interface-channels-activating-replication#replicationcomponents), select options **Jobs**, **Table Enrollment**, and **Force Start Replication Jobs**. This will update the job scripts, scheduler jobs, job groups and extend the enrollment details for tables.

      Alternatively, in the **Activate Replication** dialog, under [**Replication Components**](/docs/dss6-user-interface-channels-activating-replication#replicationcomponents), select options **Jobs**, **Table Enrollment**, **Replace All Old Enrollment**, and **Force Start Replication Jobs**. This will update the job scripts, scheduler jobs, job groups and recreate the enroll file for all tables in the channel.
 
      ![SC-Dss-Install-UpgradingDSS_ActivateReplication.webp](../_assets/SC-Dss-Install-UpgradingDSS_ActivateReplication.webp)
   

{% /tab %}

{% /tabs %}

## Downgrade Steps

Downgrade may be possible - depending on source(s), destination(s) and DSS settings - for a limited time without being forced to refresh tables or introduce data inconistencies. Always contact support for help and advice before downgrading an DSS installation.

Following are the steps for downgrading the DSS Hub System on Linux to before the upgrade:

- Stop DSS hub server
- Create backup <br />
Keep a backup of **DSS_CONFIG** representing the state of data movement at the moement you start the downgrade.
- Restore pre-upgrade backup <br />
- the **DSS_HOME** (installation files) and **DSS_CONFIG** (DSS state) directories from before the upgrade.
- the repository database by using the DBMS's native backup utilities.
If you must recover with only a hub snapshot then you must import the snapshot into a new empty repository database.
- Adjust channel settings as needed <br />
The backup restored replication state to before the upgrade. If changes were replicated following the upgrade then targets are ahead of the restored state. With access to log backups and/or archivelog files you may want to replay the changes with Resilient mode enabled on the Integrate action, followed by [**dssactivate**](/docs/dss6-command-line-interface-command-reference-dssactivate). Alternatively, you may be able to reuse state from the upgraded system, or use [**dssactivate**](/docs/dss6-command-line-interface-command-reference-dssactivate) to reset the capture time  based on state tables in the destination.
- Start hub server <br />

Resuming replication based on the recovered state from before the upgrade may no longer possible, or a suitable starting point for capture cannot be determined. In such cases [**dssrefresh**](/docs/dss6-command-line-interface-command-reference-dssrefresh) must be used to resync data.