Upgrading iTDS 3.x to 4.x

Modified on: Thu, 30 Mar, 2023 at 1:59 AM


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.X 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, you can simply create a new deployment, with the updated database password, and restore the backups from your in-place upgraded instance.

NOTE: There is currently no practical method to convert a 3.X backup to a 4.X backup other 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 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.X 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

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 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 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:


Description automatically generated


New custom docker-compose yaml file:


Description automatically generated



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  

During the migration from v3 to v4, we changed the linux user that owns the folder containing the paired configurations uploaded to the iTDS.

In order for the server to function correctly, the owner of that folder will need to be updated. This only needs to be done once. Please run the following command on your host machine:

sudo docker exec -u 0 itds-itdsphp-1 chown -R php:php /usr/local/paired_config

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

NOTE: Any Maltego Desktop Client connected to the iTDS at the time of the upgrade, may require a refresh for its internal hub items.

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

NOTE: The default port for the admin UI has changed to 8000 and can be configured in the docker-compose file.

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 then 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 restore backups.
  4. Use the Virtual Machine (OVA) deployment instructions (Deploying the iTDS with a Virtual Machine Image : 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.