ThreatConnect Environment Server Installation Guide
  • 08 Dec 2022
  • 12 Minutes to read
  • Dark

ThreatConnect Environment Server Installation Guide

  • Dark

System Requirements

In order to install an instance of the ThreatConnect Environment Server, the requirements in the following sections must be met.


The ThreatConnect Environment Server platform requires a server, virtual or physical, that meets the following minimum specifications:

  • 4 CPU/vCPU Cores (2 GHz)
  • 4 GB of memory
  • 10 GB of storage

As the number or frequency of jobs increases, the need to increase system resources will likely occur. The listing in Table 1 highlights typical TC Exchange™ apps and their specific system-resource needs.


App NameFrequencyCPU UsedMemory Used
ArcSight™ EMS ExtractDaily1.4475
Tanium™ Extract v2.0Daily< 1< 50
QRadar® Extract v2.0Daily<1< 50
Palo Alto PAN-OS® Block ListDaily.102.5


The ThreatConnect Environment Server and its supporting packages require the following software environment in order to run properly:

  • Operating System: Red Hat® Linux® variant—either Red Hat Enterprise Linux®(RHEL) 6, 7, or 8 or Community Enterprise Operating System (CentOS™) 6 or 7
    This guide assumes that the user for the installation of ThreatConnect is named threatconnect.
  • Java® Development Kit (JDK): Access to a local installation of Java 11 (OpenJDK or Oracle Java version 11)
  • Python®: Installation of Python 3.6.x for Linux

Python Installation

The instructions in this section compile and install Python from source code. This method is one of multiple ways Python can be installed on the application server.

Developer packages must be installed in order to compile Python from source code:

yum install –y gcc gcc-c++ gcc-gfortran zlib-devel bzip2-devel openssl-devel ncurses-devel sqlite-devel readline-devel tk-devel gdbm-devel db4-devel libpcap-devel xz-devel expat-devel python-setuptools

Download the source code:


Decompress the downloaded archive:

tar -xf Python-3.6.8.tar.xz

Navigate to the directory where the decompressed files reside:

cd Python-3.6.8

Run the following command to configure Python:

./configure --prefix=/usr/local --enable-shared LDFLAGS="-Wl,-rpath /usr/local/lib"

Begin the compile process to ensure there are no errors:

make && make altinstall

Set up a symbolic link:

ln -s /usr/local/bin/python3.6 /usr/local/bin/python
The developer packages may be removed at this point in order to reduce security risks.

SMTP Server

TC Exchange requires an available Simple Mail Transfer Protocol (SMTP) server to send email alerts and to correspond with users. This server must be routable from the server running the platform, and if SMTP authorization is required, the ThreatConnect Environment Server will need access to a username and password in order to generate these emails.

Network Traffic Port Requirements

The ports and protocols listed in Table 2 must be opened when deploying the Environment Server inside a network. Appropriate firewall rules must be enabled for these ports from the machine running the Environment Server in order to allow connectivity to your ThreatConnect Dedicated Cloud instance.


Network PortProtocolTraffic DirectionDescription
443HTTPS/TCPOutbound to DCThis port connects to the ThreatConnect Dedicated Cloud API to download apps for execution. Traffic is limited to app installs and upgrades. App downloads are performed when an execution request is sent from the ThreatConnect Dedicated Cloud instance for the first time.
62000TCPOutbound to DCThis port is defined within the ThreatConnect System Settings. It enables the Environment Server to connect securely with the ThreatConnect Dedicated Cloud message broker to receive real-time commands in order to execute an app to fulfill orchestration requirements, as well as provide command-and-control capabilities. Traffic is lightweight and used primarily in a request/response model to direct app executions.

Preparing the Environment

Java JDK

The system needs access to the Java JDK as outlined in the “Software” section. In addition, the JAVA_HOME environment variable needs to be properly configured to point to that directory.

Some CentOS/Red Hat versions come with a pre-installed, though unsupported, version of OpenJDK.

Downloading Java

The ThreatConnect MEO (Multi-Environment Orchestration) Environment Server requires Java version 11.x to be installed and configured. The latest version of the ThreatConnect MEO software supports both OpenJDK and Oracle JDK version 11.

Installing and Configuring Java

The instructions in this section refer to a specific Oracle JDK version of Java 11. If using a different version, make sure to substitute the correct filename into the given commands.

Execute the following command:

rpm -ivh jdk-11.0.10_linux-x64_bin.rpm

Once installation is complete, execute the following command:

alternatives -- config java

This command will output the current location of the new Java installation.

Typically, an installation of this type will create a symbolic link to /usr/java/latest. The following command will confirm whether this location can be configured as the run location for Java:

cd /usr/java/latest

The next step is to create the threatconnect local OS user account:

adduser threatconnect

Use the following commands to log into and modify the ,bashrc file for the threatconnect account:

su threatconnect
vi ~/.bashrc

Then add the following code as the second line of this file, where <path to Java> would typically look like /user/java/latest:

export JAVA_HOME=

Then reload the bash profile:

source ~/.bashrc


Getting Started

ThreatConnect clients can use this guide to configure and install their own Instance of the ThreatConnect Environment Server. This guide assumes a moderate level of systems-administration expertise and an operating environment that satisfies the requirements detailed previously. See Playbook Environments for more information about how to configure, administrate, and use Environments in ThreatConnect.

Downloading the Installer

The Environment Server installer .zip file is available for download on the Environments tab of the Playbooks screen in ThreatConnect (Figure 1).

Graphical user interface, application  Description automatically generated


Click the vertical ellipsis at the upper-right corner of the desired Environment card and select Download. A window containing the download options for the Environment will be displayed (Figure 2).


This window provides three options for download: Download Bundle (All-in-one), Environment Config Only, and Environment Server Only. The Download Bundle (All-in-one) option includes both the Environment Config and the Environment Server as well as the KeyStore files required to make a secure connection to the host ThreatConnect instance. Select this option, and then click the DOWNLOAD button.

Select Environment Config Only when an existing Environment Server needs to point to a new Environment. Select Environment Server Only when an existing Environment Server needs to be upgraded.

Opening the Installer

Unzipping the File

The ThreatConnect Environment Server .zip file serves as an archive of all the necessary files and folders needed to install the application. There are two ways to unzip this file:

  1. Copy the .zip file to the desired directory on which the ThreatConnect Environment Server will be installed. By default, this directory is /opt, which will result in an installation directory of /opt/threatconnect-envsvr.
  2. Unzip the file from the command-line interface with the following command:
  3. Configure permissions within the operating system to ensure that the threatconnect user can access the ThreatConnect Environment Server files. In the following command, the default values of threatconnect and /opt/threatconnect-envsvr, respectively, are being used:
    chown –R threatconnect:threatconnect /opt/threatconnect-envsvr
  4. Run the following command to ensure that all .shscripts are executable, which is a requirement for the MEO Environment Server:
    chmod +x /opt/threatconnect-envsvr/*.sh

Installation Directory Structure

After the archive has been extracted, the new folder will contain the following directory structure:

  • The .tcenvsvr directory contains the default keystore and broker connection settings.
  • The README.txt file contains instructions on how to install the Environment Server.
  • The file is used to configure the Environment Server settings using a command-line interface.
  • The file is used to run the Environment Server directly from the command line (not as a service).
  • The file is used to shut down the current Environment Server.
  • The file is the init.d service script.
  • The threatconnect-envsvr.jar file is the file for the Environment Server only (i.e., it does not contain the configuration file).
Users patching their ThreatConnect Environment Server Instance to a newer version should select the Environment Server Only option from an Environment instead of the All-in-one Bundle. (See the “Downloading the Installer” section for more information.) This download extracts to a threatconnect-envsvr.jar file. Replace the existing .jar file and restart to complete the upgrade.

The ThreatConnect Environment Server Setup

Creating tc-job User

The information covered in this section is an optional security enhancement.

To provide additional security, it is recommended that a separate user on Linux systems be created to run TC Exchange jobs. It is also recommended that read and write groups be created to control the permissions to these files. Use the following code to perform these tasks:

useradd tc‐job
echo "tc‐job‐pass123" | passwd tc‐job ‐‐stdin
groupadd tc‐job‐read
usermod ‐a ‐G tc‐job‐read tc‐job
chgrp ‐R tc‐job‐read /opt/threatconnect-envsvr/.tcenvsvr/exchange/programs
chmod ‐R 755 /opt/threatconnect-envsvr/.tcenvsvr/exchange/programs
groupadd tc‐job‐write
usermod ‐a ‐G tc‐job‐write tc‐job
chgrp ‐R tc‐job‐write /opt/threatconnect-envsvr/.tcenvsvr/exchange/jobs
chmod ‐R 777 /opt/threatconnect-envsvr/.tcenvsvr/exchange/jobs
chmod +t /opt/threatconnect-envsvr/.tcenvsvr/exchange/jobs

User Privilege Configuration

Add the following lines to /etc/pam.d/su after the first auth command:

auth [success=ignore default=1] user = tc‐job
auth sufficient use_uid user = threatconnect

Configuring sudoers

Create /etc/sudoers.d/threatconnect using the following command:

visudo -f /etc/sudoers.d/threatconnect

Then add the following lines:

Defaults:threatconnect !requiretty
threatconnect ALL=(tc‐job) NOPASSWD: ALL

This configuration allows the threatconnect user to run the jobs as the tc-job user.

Starting the ThreatConnect Environment Server

After completing the installation and configuration procedures, it is time to start the ThreatConnect Environment Server.

Starting as a Linux Service

The options in the previous sections allow a user to run the ThreatConnect Environment Server in a single session. This approach presents a number of limitations: The platform will need to be started manually after each reboot, or a terminal window or Secure Shell (SSH) session may have to be left open. To address this problem, this section details the file configuration to run the ThreatConnect Environment Server as a service in Linux.

Open a terminal window and browse to the app directory within the ThreatConnect Environment Server directory. Run the file as follows:

su - threatconnect -c ./opt/threatconnect-envsvr/

Running this command will ensure proper connectivity to the ThreatConnect Dedicated Cloud instance for your organization. As long as logs indicating connectivity to your DC instance (FQDN:62000 with successful connection) are being generated, the MEO server will connect properly to the DC instance.

Run CTRL-C to force the process to close. Once the process is closed, execute the following command:

su - threatconnect -c ./opt/threatconnect-envsvr/

A menu providing options for configuration of the MEO instance will be provided.

Please select an option:
1: System Configuration
2: Variables
3: Exit

Select 1: System Configuration. The System Configuration menu will be displayed.

System Configuration: Please select an option:
1: List all System Config
2: Edit System Config
3: Export Configuration
4: Go Back

Select 2: Edit System Config. Then edit the Java and Python locations as they are configured within your current MEO server configuration. Typically, the options to select are 3: appsJavaHome and 5: appsPythonHome, respectively.

If implementing a proxy within the Environment Server, the fields in the following menu will need to be configured.

13: proxyExternal = <empty>
14: proxyHost = <empty>
15: proxyPassword = <empty>
16: proxyPort = <empty>
17: proxyTC = <empty>
18: proxyUsername = <empty>
  • Set options 13 and 17 to true.
  • Populate options 14, 15, 16, and 18 according to your organization’s proxy configuration for where this server resides.
The Service Script

Within the ThreatConnect Environment Server installation, there is a script used for running the ThreatConnect Environment Server as an initialized service:


This script must be copied into the /etc/init.d directory for it to be recognized as a system service. Note that users may require privileges to copy to this directory:

cp /opt/threatconnect-envsvr/
Configuring Services

The service script requires proper permissions and paths to be set.

  1. Specify the TCENVSVR_HOME variable within the script to point to the path where the ThreatConnect Environment Server installation exists. By default, this path is /opt/threatconnect-envsvr.
  2. Specify the USER variable within the script to identify which user owns the files for the ThreatConnect Environment Server application. It is advisable, for security reasons, that the root user not be employed. By default, the username is assumed to be threatconnect.
Starting the ThreatConnect Environment Server as a Service

Once the services have been configured, the ThreatConnect Environment Server can be started as a service. To do so, enter one of the following commands while logged in as the root user:

service threatconnect-envsvr start
/etc/init.d/threatconnect-envsvr start

To stop the service, use either one of the following commands:

service threatconnect-envsvr stop


/etc/init.d/threatconnect-envsvr stop

To have the ThreatConnect Environment Server start on system startup, issue the following commands after the script is configured in the /etc/init.d directory:

For sysVinit systems:

chkconfig ‐‐add threatconnect-envsvr
chkconfig threatconnect-envsvr on

For systemd systems:

systemctl enable threatconnect-envsvr

The First Login

Setting Master Key for Keychain

The Keychain feature is required for the ThreatConnect Environment Server. When prompted, enter a Master Password. The Master Password is used to encrypt sensitive values and is required on every server restart.

System Settings Checklist

Users should review their Instance settings to ensure that they are configured according to their needs. Table 3 provides a description of each system configuration value.


System Configuration ValueDescription
apiURLThis setting should point to the URL for the API at port 8443 (e.g.,
appDeliveryTokenThis setting is the token that is used to authenticate with the App Catalog Server.
appsJavaHomeThis setting holds the path to the Java binary.
appsNumberofJobExecutorsThis setting is the number of Job Executors that can run concurrently. It is a factor of the number of CPUs and the available memory on the server. It should not exceed available resources.
appsPythonHomeThis setting holds the path to the Python® binary.
appsSandboxUserThis setting represents the user account used to execute Jobs. It is pertinent only in Linux® installs.
appsSessionDaystoKeepThis setting is placed at 5 in Cloud. It indicates the number of days that logs will be kept in the Jobs log directory: %threatconnect%/exchange/jobs.
brokerHostThis setting is the remote host name of the messaging server to which the Environment Server will connect.
brokerTokenThis setting is the secure key used to authenticate a connection to the remote message broker.
proxyExternalThis setting is set to true when all external connections for apps should be routed through a proxy server.
proxyHostThis setting is the proxy host to use if a proxy server is required. Acceptable values are a valid IP address or host name for a proxy accessible by the ThreatConnect instance.
proxyPasswordThis setting is the proxy password to use if a proxy server requires authentication.
proxyPortThis setting is the proxy port to use if a proxy server is required. Enter a valid proxy port number.
proxyTCThis setting is set to true when all connections to the ThreatConnect host server should be routed through a proxy server.
proxyUsernameThis setting is the proxy username to use if a proxy server requires authentication.
queueTransportThis setting is empty by default and utilizes the raw TCP socket for messaging services. For deployments that require a proxy, set this value to websocket. This will change the transport to an HTTP-based transport protocol supported by secured proxy environments. All traffic will move through port 62000 over HTTP/S. If the proxy is defined, then the Environment Server will utilize this proxy for all messaging traffic.
relaySystemInfoPublishSecondsThe frequency at which to notify the remote ThreatConnect instance of the status of the Environment Server.
serverNameThe name of the Environment Server to display on the ThreatConnect Environments screen and administration page.
serverXidThis setting is a static number that uniquely identifies the given Environment Server. Its value should not be changed.

ThreatConnect® is a registered trademark, and TC Exchange™ is a trademark, of ThreatConnect, Inc.
ArcSight™ is a trademark of Hewlett Packard Enterprise Company.
QRadar® is a registered trademark of IBM Corporation.
Linux® is a registered trademark of Linus Torvalds.
Java® is a registered trademark of Oracle Corporation.
PAN-OS® is a registered trademark of Palo Alto Networks.
Python® is a registered trademark of Python Software Foundation.
Red Hat® and Enterprise Linux® are registered trademarks, and CentOS™ is a trademark, of Red Hat, Inc.
Tanium™ is a trademark of Tanium, Inc.

10028-12 EN Rev. A


Was this article helpful?