Remediation instructions for License Management Defect

These instructions pertain to the Critical Advisory: Mandatory update required to address License Management Defect note, which clarifies that:

Matillion ETL has a critical License Management defect in Matillion ETL (v1.51 and above), requiring all instances to be patched or upgraded by March 31st, 2024. Failure to apply the patch or to upgrade your instances will result in the software failing to run after that date.

Follow the instructions on this page to patch your Matillion ETL instance or perform an in-place update or migration to a newer version.

Check your current Matillion ETL version

Log in to your Matillion ETL instance.
Open a project.
Click Admin in the upper-right.
Click Matillion ETL Updates.
The Matillion ETL Updates dialog will open, displaying the current version of your instance. In the image below, the current version is 1.73.0, and the Available Version drop-down menu offers an update to version 1.73.1.

Matillion ETL Updates

Is your Matillion ETL version affected?

Affected versions

These versions require immediate remediation:

Major version	Minor version
1.51	All versions
1.52	All versions
1.53	All versions
1.54 to 1.63	All versions
1.64	.18 or below
1.65 to 1.67	All versions
1.68	.18 or below
1.69 to 1.71	All versions
1.72	.3 or below
1.73	.0

Fixed versions

These versions are recently released and include the fix. If you're on one of these versions, no action is required:

Major version	Minor version
1.64	.19 or above
1.68	.19 or above
1.72	.4 or above
1.73	.1 or above
1.74	.0 or above

Unaffected versions

These older versions are unaffected by the bug. If you're on one of these versions, no action is required:

Major version	Minor version
1.47	All versions
1.48	All versions
1.49	All versions
1.50	All versions

Other versions

Any other version not listed on this page should be considered affected and requires you to either patch the instance or upgrade.

Back up your Matillion ETL instance

Before you update a Matillion ETL instance, always take a backup of the instance and ensure you can easily restore from the backup in the event of any problems. If you don't back up, you may lose configuration and/or job definitions that won't be retrievable.

Backup documentation for each cloud platform is available here:

Remediation options

There are two methods to resolve this issue:

Manually applying a patch via SSH.
Performing an in-place update.

Manually patching via SSH

This option lets you deploy the single fix for this licencing issue, without changing your Matillion ETL version.

Pros
No need to change Matillion ETL versions.
No need to test pipelines/jobs after applying the fix.
Simple.

Cons
Requires SSH/command line access to the instance.
Requires knowledge of the Linux command line.
Does not include other recent security patches and bug fixes.

Matillion's advice:

We recommend patching via SSH if you have SSH access and would otherwise need to upgrade your Matillion ETL instance's major version.

In-place update

This option upgrades your Matillion ETL instance to a later version, bringing bug fixes, security updates, and new features.

Pros
Upgrading to a long-term support (LTS) release comes with the latest security and product fixes.
New features.

Cons
Depending on your current version, this option may require a full migration, increasing the complexity of the task and the time required to complete.
Testing should be performed on pipelines/jobs after a major version upgrade.

Matillion's advice:

If your major version has a fixed minor version available, then an in-place update is simple and unlikely to cause any pipeline/job regressions. However, upgrading your major version will require a migration, and in such scenarios, we would recommend using the "patch via SSH" option instead.

Perform the remediation steps

Patch via SSH

With internet connection

This option lets you deploy the single fix for this licensing issue, without changing your Matillion ETL version.

If your Matillion ETL instance can connect to the internet—specifically to our Yum upgrade host, artifacts.matillion.com—we have provided an update script for the instance.

Warning

This method will perform an instance restart. Make sure no jobs are running before executing the script.

SSH in to your Matillion ETL instance. Click here if you need help doing this.
Execute the following commands:

$ sudo su
# wget https://artifacts.matillion.com/jar/hazelcast/hazelcast_update.sh
# bash hazelcast_update.sh

What steps does the script perform?

Downloads a .jar file containing the fix.
Stops the Matillion ETL service.
Replaces the required file in the Matillion ETL library folder.
Restarts the Matillion ETL service.

Note

The .jar file is verified before the server restart takes place. This operation typically requires only a few minutes of downtime.

Without internet connection

This option lets you deploy the single fix for this licensing issue, without changing your Matillion ETL version

If your instance is isolated from the internet, you can still patch via SSH:

Download the updated jar file https://artifacts.matillion.com/jar/hazelcast/emerald-<your version>.jar separately, where <your version> would be the Matillion ETL version. For example, 1.65.9.
Replace the existing emerald-[your version].jar in the libraries folder, /usr/share/emerald/WEB-INF/lib/.
Restart Matillion ETL, either by:
1. Using systemctl restart tomcat8 in the command line in pre-1.69 versions.
2. Using systemctl restart tomcat in post-1.69 versions.
3. Choosing Restart Server from the Admin menu within Matillion ETL.

In-place update

Read Updating and migrating to learn how to perform an in-place update or a migration. As noted above, certain versions may require a total instance migration rather than an in-place update. In such scenarios, using the "patch via SSH" option may be the preferred approach.

Confirm the license update was successful

In-place updates

Log in to your Matillion ETL instance.
Open a project.
Click Admin in the upper-right.
Click Matillion ETL Updates.
Confirm your instance is now running a fixed version.

Patch via SSH

Note

If you performed an in-place update, you can confirm that your license key is updated by running the steps below too.

Validate via license expiry date

SSH in to your Matillion ETL instance.
Switch to a super user:
```
sudo bash
```
Execute this command:

Matillion ETL versions before v1.69:
```
grep -i "hazelcast.*expiryDate" /var/log/tomcat8/catalina.out
```
If the above doesn't work, your instance is on a version after v1.69. Try the filepath without 8 in tomcat:
```
grep -i "hazelcast.*expiryDate" /var/log/tomcat/catalina.out
```
Check that the last entry is expiryDate=Mar/31/2026 instead of expiryDate=Mar/31/2024:

Note

Some logs may display expiryDate=03/31/2026 23:59:59 and some may display expiryDate=Mar/31/2026 (03 versus Mar).

Invalid: ❌

26-Jan-2024 11:57:37.435 INFO [localhost-startStop-1] com.hazelcast.instance.NodeExtension.null [172.31.31.147]:5701 [Matillion] [3.12.13-SNAPSHOT] License{allowedNumberOfNodes=6, expiryDate=Mar/31/2024 23:59:59, featureList=[ Management Center, Clustered JMX, Clustered Rest, Security ], type=null, companyName=null, ownerEmail=null, keyHash=di4GH0ObvwFLK8cug4OIPHBScL3B8an5VNg7Fx1gyto=, No Version Restriction}

Valid ✅

26-Jan-2024 11:57:37.435 INFO [localhost-startStop-1] com.hazelcast.instance.NodeExtension.null [172.31.31.147]:5701 [Matillion] [3.12.13-SNAPSHOT] License{allowedNumberOfNodes=6, expiryDate=Mar/31/2026 23:59:59, featureList=[ Management Center, Clustered JMX, Clustered Rest, Security ], type=null, companyName=null, ownerEmail=null, keyHash=di4GH0ObvwFLK8cug4OIPHBScL3B8an5VNg7Fx1gyto=, No Version Restriction}

Validate via number of nodes

SSH in to your Matillion ETL instance.
Switch to a super user:
```
sudo bash
```

Execute this command:

Matillion ETL versions before v1.69:

grep -i "hazelcast.*allowedNumberOfNodes" /var/log/tomcat8/catalina.out

Matillion ETL versions after v1.69:

grep -i "hazelcast.*allowedNumberOfNodes" /var/log/tomcat/catalina.out

If the response is allowedNumberOfNodes=9999 then you have successfully patched your instance. ✅
If the response is allowedNumberOfNodes=6, your instance still requires the patch in the steps above. ❌

Need help?

Contact our customer support team at support.matillion.com for further assistance.