Upgrading iTDS 3.X to 4.0.2

Modified on: Mon, 22 Nov, 2021 at 10:15 AM

Introduction

Maltego is releasing a significant new update to its on-premise deployable infrastructure.

This update brings with it several patches and other docker container security enhancements. It also serves as an important step towards full Kubernetes support. 

 

The most significant change introduced is the provision of a single service per docker container. As a result, the deployment now has one more additional docker container.

 

Two iTDS deployment models are officially supported:

  1. Docker deployment
  2. Virtual Machine (OVA) deployment


The steps for each deployment model are provided in this document.


Upgrading a Docker deployment

For the purpose of these instructions, it is assumed that the docker-compose deployment instructions were followed (Deploying the iTDS with Docker : Maltego Support).

 

If all goes well, upgrading from 3.X to 4.0.2 should be a quick and painless exercise. If customizations were made to the deployment model, such as using custom SSL certificates, please review the new instructions and apply them to the custom docker-compose yaml file.


In this document, we will only cover the most frequently applied customization: Using your own custom SSL certificate.


NOTE: If a more advanced deployment model was followed, such as a cloud-based container service, e.g., AWS ECS, Azure App services, Kubernetes, etc., and you require additional information, please contact support@maltego.com.


NOTE: Should you wish to make use of some of the new features, such as providing your own database password, you will be required to complete an in-place upgrade and, backup your iTDS using the new CSV based export (Backing up using CSV Import / Export : Maltego Support).

Remember to backup paired configuration files, shutdown your deployment, delete the shared volumes, change the password in the docker-compose yaml file, deploy the iTDS and restore your backups.

Or, simply create a new deployment, with the updated database password, and restore the backups from your in-place upgraded instance.


NOTE: There is currently a new, practical method to convert a 3.X backup to a 4.0.2 backup rather than performing an in-place upgrade.


High Level Steps:

  1. Backup the existing installation.
  2. Shutdown the existing iTDS installation and remove the existing iTDS docker containers.
  3. Retag existing docker container images.
  4. Download the new docker-compose yaml file.
  5. Pull the new docker container images from the Paterva Docker registry.
  6. (Optional) Update customizations.
  7. Deploy and start the new iTDS docker containers.


Backup the existing installation

3.X provides a MySQL database dump as backup mechanism. 4.0.2 now has a new CSV based backup and restore mechanism. These two mechanisms are mutually exclusive. An in-place upgrade is required. A backup of 3.X is required, should the in-place upgrade fail and you are required to revert back to 3.X.

 

Follow the 3.X backup instructions to make a backup of your existing installation (Backup (iTDS version 3.1.2) : Maltego Support).


Shutdown the existing iTDS installation

Shut down the existing iTDS and remove the existing containers:


sudo docker-compose –f itds.yml down

Retag existing docker container images

NOTE: Retagging the existing docker images serves as a backup mechanism to revert back to a previous version.

List the existing docker container images:

 

Sudo docker images

 

Sample output:

 

 

Retag the existing docker container images using the Images ID:

 

Sudo docker image tag c5f975d3fd77 registry.paterva.com/itdsphp:bck
Sudo docker image tag e78b9dd14e93 registry.paterva.com/itdsdb:bck


NOTE: Should you wish to revert:
- use docker image rm to delete the new docker container images
- use docker image tag to revert to bck tag back to latest
- use docker volme ls to list the corrupted database volume
- Restore the MySQL backu as per the instructions in the documentation (Backup (iTDS version 3.1.2) : Maltego Support).

Download the new docker-compose yaml file

Download the docker-compose yaml file by following the instructions in the documentation (Deploying the iTDS with Docker : Maltego Support). The link to the file is also provided in the delivery document which was emailed to you when you purchased the product.


The URL is: https://dolores.paterva.com/customers/docker/download_compose/12/ 


NOTE: As instructed in the official documentation, the docker-compose yaml file must be available on the VM or server on which the iTDS is deployed.


NOTE: To avoid confusion, rename the docker-compose yaml file of the existing installation, e.g., itds_3.yml. The new file can be named itds.yml to match the instructions provided in the documentation.


The new docker-compose yaml file should be in the same location as the old file. This is to ensure that the new deployment has access to the existing shared docker volumes.


Pull the new docker container images from the Paterva Docker registry.

Do a docker-compose pull to download the new docker container images as specified in the new docker-compose yaml file.


sudo docker-compose –f itds.yml pull


Remember to log into the Paterva Docker Registry, if you receive any authentication errors, your login credentials are saved in your delivery document.

sudo docker login registry.paterva.com


Update Customizations (optional)

Assuming you used your own SSL certificates, make the following change to you custom Dockerfile and docker-compose yaml file:

 

Old Dockerfile which references the PHP Docker container image:

 

New Dockerfile, which references the Apache Docker container image:

 

Old custom docker-compose yaml file:

Text

Description automatically generated

 

New custom docker-compose yaml file:

Text

Description automatically generated

 

Summary:

Change the Docker container images name from itdsphp to itdsapache


Deploy and start the new iTDS docker containers. 

Deploy and start the new iTDS docker containers following the instructions provided in the documentation (Deploying the iTDS with Docker : Maltego Support).


Sudo docker-compose -f itds.yml up -d

Allow your iTDS to run for a while to complete database update functions. Depending on the size of the database, give at least 5 minutes.

 

Restart the iTDS


Sudo docker-compose -f itds.yml stop
Sudo docker-compose -f itds.yml up -d  

Access your iTDS as you would normally. If the in-place migration went according to plan, you will be able to use your iTDS as previously.


NOTE: Any Maltego Desktop clients that were connected to the iTDS at the time of the upgrade, might need to refresh the Refresh the internal hub item.


NOTE: For detailed instructions on how to build and deploy your customizations, please refer to the documentation (Using your own SSL Certificate : Maltego Support).



Upgrading a Virtual Machine (OVA) deployment

The instructions to upgrade a Virtual Machine (OVA) based iTDS deployment requires an in-place upgrade as described in the instructions for the Docker deployment. The only difference is that you would need to log into the VM and the follow the Docker upgrade instructions.

 

High Level Steps:

  1. Log into the Virtual Machine.
  2. Follow steps as provided in this document to upgrade the iTDS.
  3. Use the CSV backup instructions (Backing up using CSV Import / Export : Maltego Support) to get backups.
  4. Use the Virtual Machine (OVA) deployment instructions (Deploying the iTDS with Docker : Maltego Support) to deploy a new Virtual Machine.
  5. Use the Use the CSV backup instructions (Backing up using CSV Import / Export : Maltego Support) to restore backups.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.