Table of Contents

Preparing to upgrade a DataMiner Agent

This section of the documentation contains detailed information on how to prepare to upgrade a DataMiner Agent. To ensure a successful upgrade of your DMA, we strongly recommend that you read through the content of this page.

Best practices

Check for known issues and breaking changes

From time to time, issues are detected that might impact a DataMiner System if a particular DataMiner version is installed. Before you upgrade, we therefore recommend that you first check the Known issues page to identify if your system might be affected by such an issue.

Make sure you also check the Breaking changes page to see if any breaking changes will affect your system when you upgrade.

Upload upgrade packages before an upgrade

We highly recommend that you upload the upgrade package before the actual maintenance window, as this is low risk and does not require a restart of your system, but it will indicate whether all conditions and requirements to upgrade your DataMiner Agent are met, vastly reducing the chance of problems occurring during the eventual upgrade.

To upload an upgrade package:

  1. Open DataMiner Cube.

  2. Follow the upgrade procedure described in Upgrading a DataMiner Agent in System Center.

  3. During the final step of the upgrade procedure, instead of clicking Upgrade, select Upload only.

    Upload only

  4. If the upload was successful, you should receive the following upload report:

    Upload report
Upload has been completed successfully.
Note

When you upload a package, several prerequisite checks will be executed, so that you will immediately get informed if certain conditions or requirements for the update are not met yet.

Tip

We recommend that you upload the package a few days before you execute the upgrade. This will allow you extra time to perform corrective actions in case any of the prerequisite checks fail.

Have a backup at the ready

We recommend making a backup of your DataMiner System before executing an upgrade, in case unexpected issues should occur.

Making a backup can be done with a VM snapshot or DataMiner.

VM snapshot

Take a virtual machine (VM) snapshot of the upgraded machines shortly before the update. This will allow a speedy rollback of the DataMiner System.

Tip

For more information on how to downgrade your DMS using a VM snapshot restore, see Downgrade with VM snapshot restore.

Note

The timing for a VM snapshot restore depends on your specific setup.

DataMiner backup

Make a backup of your DataMiner Agent using DataMiner Taskbar Utility or DataMiner Cube, as explained in Backing up a DataMiner Agent. This will allow a speedy rollback of the DataMiner System by installing the upgrade package of the previous DataMiner version.

Best practices when upgrading across major versions

If you are upgrading to another major version that does not immediately follow your current version, always follow this general guideline:

Upgrade to the next major DataMiner version(s) before upgrading to your preferred version.

Upgrading across major versions

This does not apply for upgrades within the same major version. For example, to upgrade from 10.4.0 CU6 to 10.4.0 CU8, it is not necessary to install CU7 first.

Important
  • There is one exception to this rule: if you are upgrading from a version prior to DataMiner 10.1.x to 10.2.x or higher, skip DataMiner 10.1 and proceed directly to the subsequent major version instead (i.e. DataMiner 10.2).
  • If you are upgrading from DataMiner 9.6.0/9.6.x or a DataMiner 10.0.0 main release version prior to DataMiner 10.0.0 [CU19], upgrade to DataMiner 10.0.0 [CU19] as the next major version.
  • If you are on the Feature Release track and want to switch to a DataMiner version on the Main Release track, skip the main release version that matches your current feature release version. For example, if you have DataMiner 10.2.12 installed, you can upgrade directly to DataMiner 10.3.0, or you can upgrade from DataMiner 10.2.12 to any 10.3.x version and then to 10.4.0. See DataMiner Main Release vs. Feature Release.
Tip

See Example upgrade path.

Upgrade prerequisites

If you are about to upgrade across major versions, before proceeding with the upgrade, ensure the following requirements are met:

Example upgrade path

To upgrade from DataMiner 9.6.0 to DataMiner 10.3.0:

  1. Install Microsoft .NET 4.8, ASP.NET Core 5.0.11, and ASP.NET Core 6.0.13.

  2. Open IP network ports 9090, 4222, 6222, and 8222 (NATS monitoring only).

  3. Install DataMiner 10.0.0 [CU19].

  4. Download VerifyClusterPorts.dmupgrade and run it.

  5. Install DataMiner 10.2.0.

  6. Install DataMiner 10.3.0.

Prerequisite checks

When you upload a DataMiner upgrade, several prerequisite checks are automatically executed. These will verify whether all the necessary conditions for upgrading DataMiner to the selected version and all requirements for the DataMiner Agent to run are met. If the prerequisite checks detect that this is not the case, the upgrade will be canceled.

Important

We recommend running the prerequisite checks well in advance of the actual upgrade activity, so that you have time to carry out any actions that are required as reported by the checks.

The following prerequisite checks are currently available:

  • Verify .NET Version: Verifies whether the Microsoft ASP.NET 8.0 Hosting Bundle is installed. From DataMiner 10.3.0 [CU12]/10.4.0/10.4.3 onwards, this prerequisite is available by default and runs automatically when you upgrade.

  • Verify Cloud DxM Version: Verifies whether the minimum required version is installed for all DxMs in the system. From DataMiner 10.2.0 [CU6]/10.2.8 onwards, this prerequisite is available by default and runs automatically when you upgrade.

  • Verify Cluster Ports: Verifies whether the ports used by DataMiner can be reached in between DataMiner Agents. If this check fails, you will need to install the VerifyClusterPorts.dmupgrade package. From DataMiner 10.2.0 [CU2]/10.2.5 onwards, this prerequisite is available by default and runs automatically when you upgrade.

  • Verify Elastic Storage Type: Verifies whether the system has successfully switched to an indexing database. From DataMiner 10.4.0/10.4.1 onwards, this prerequisite is available by default and runs automatically when you upgrade.

  • Verify NATS is Running: Verifies whether the crucial NATS service used by DataMiner is running on all required DataMiner Agents. From DataMiner 10.2.0 [CU14]/10.2.7 onwards, this prerequisite is available by default and runs automatically when you upgrade.

  • Verify No Legacy Reports Dashboards: Scans the DataMiner System for any legacy reports and legacy dashboards. From DataMiner 10.4.0/10.4.1 onwards, this prerequisite is available by default and runs automatically when you upgrade.

  • Verify No Obsolete API Deployed: Verifies whether the APIDeployment soft-launch option is enabled and obsolete APIs are deployed. From DataMiner 10.4.0 onwards, this prerequisite is available by default and runs automatically when you upgrade.

  • Service Automatic Properties: Verifies whether the installed SRM framework version is up to date. From DataMiner 10.2.3/10.3.0 onwards, this prerequisite is available by default and runs automatically when you upgrade.

  • Validate Connectors: Scans the DataMiner System for any connectors that are known to be incompatible with the DataMiner version to which the DataMiner Agent is being upgraded. From DataMiner 10.3.4/10.4.0 onwards, this prerequisite is available by default and runs automatically when you upgrade.

  • Firewall Configuration: Checks the firewall configuration. From DataMiner 10.3.7/10.4.0 onwards, this prerequisite runs automatically when you upgrade, to ensure TCP port 5100 is correctly configured to allow inbound communication. This port is required for communication to the cloud via the endpoint hosted in DataMiner CloudGateway.

Note

Though this is not recommended, you can bypass these checks by manually removing the Prerequisites folder from Update.zip in the upgrade package. However, you should only do so if there is a clear reason to assume that the prerequisites do not work because of a bug in the software and they are consequently failing without a proper reason. If you bypass these checks in any other circumstances, and this results in a DataMiner issue, this is not covered by support.

Propose changes