Introduction
The iTDS server is available as a Docker image. Your Electronic Delivery document contains a link to the Docker Compose YAML file (itds.yml) that should be downloaded and will be used to pull the required Docker images from our Docker registry and Docker Hub, provision volumes, and start the containers in the default network.
These instructions were tested on an Ubuntu 20.04 LTS host using IPv4. Instructions may differ slightly depending on your preferred host operating system and network configuration.
Note: The instructions below should be executed from the host server through console or a SSH session. Commands have to be executed with elevated user privileges (e.g. “sudo” or with the “root” user) if the logged in user is not in `docker` group.
Software Requirements
The host machine running the Docker containers will need to have the following installed:
- Docker Engine (CE or EE) - Read more: https://docs.docker.com/get-started/overview/
- Docker Compose - Read more: https://docs.docker.com/compose
Starting the Server
After you have installed Docker and Docker Compose on your Host machine follow the steps below:
Step 1: Login to the Docker Registry
To download the latest Docker images, you first need to log into our Docker Registry using the following command:
docker login registry.paterva.com
Enter the iTDS Docker Registry username and password as specified in the Delivery document.
Note: If the delivery document contains multiple server licenses, the password is different per server license.
Step 2: Copy your Docker Compose YAML File
Your delivery document includes a link to a Docker Compose YAML file (itds.yml) that can be used to deploy iTDS. You will need to either copy the Docker Compose YAML file or directly download it onto the machine that will be running the Docker containers.
Note: It is recommended that you always run the docker-compose commands from the same directory as the docker-compose YAML file. Please copy the docker-compose YAML file to it’s own directory (e.g. /var/maltego/ or /home/maltego/), and run all future commands from this directory.
You can use either of the following commands to download the YAML file directly on to the host machine (you may need "write permissions" if downloading to a system directory).
wget https://dolores.paterva.com/customers/docker/download_compose/12/ -O itds.yml
Or
curl https://dolores.paterva.com/customers/docker/download_compose/12/ -o itds.yml
Step 3: (Optional) Environment Variables
The environmental variables mentioned below can be set in your itds.yml file.
The ENCRYPTION_KEY is what is used to encrypt a user session. It can be set to any random string of at least 20 characters and should not be changed once initially set.
To change the default MySQL password, you need to change DB_PASS under the itdsphp service and MYSQL_ROOT_PASSWORD under the itdsdb service.
NOTE: The default MySQL password must be changed the first time the server is powered on and should not be changed. If you wish to change the password after the server has already been powered on for the first time, you will also need to refer to MySQL official documentation on how to change the password or reach out to support@maltego.com for more assistance.
With the release of iTDS 4.1.1, a TRANSFORM_TIMEOUT environmental variable was added which can be used to set the Transform timeout. Users can adjust the Transform timeout by setting the TRANSFORM_TIMEOUT variable in the docker compose file. The default timeout is set to 2 minutes.
Step 4: Start the Server
From the directory containing the Docker Compose YAML file (e.g. /home/maltego/), build and start the server using ‘docker-compose’:
Docker Compose Version: 20.10.15 and above. Reference: https://docs.docker.com/compose/
docker compose -f <filename> up -d
Docker Compose Version: 20.10.14 and below. Reference: https://docs.docker.com/engine/release-notes/#201015
docker-compose -f itds.yml up -d
The iTDS Docker images will be pulled from the Docker Registry. Once the images have been pulled, the containers will start running automatically in Detached mode (-d).
You can now access the iTDS web interface and access the server. For more information, refer to the iTDS Activation article.
Deploying Previous Versions of the Server
Should you wish to deploy an older version of the iTDS server, please refer to our GitHub repository for Docker compose file history and downloads.