Administrating an Environment
  • 18 Sep 2024
  • 8 Minutes to read
  • Dark
    Light

Administrating an Environment

  • Dark
    Light

Article summary

An Environment’s administration screen (Figure 1) provides options for viewing details about the Environment and changing aspects of its configuration. To view this screen, select View from the ⋮ menu of an Environment card or click the name of the Environment at the top of its card.

Note
When an Environment's administration screen is first loaded, there may be a short delay before all information is displayed.

Figure 1_Administrating an Environment_7.7.0

 

Environment Statistics

The Environment Statistics section provides:

  • statistics on the number of messages per hour received by the Environment;
  • the average amount of time (in seconds) that a Job waits in the queue for the Environment before being executed;
  • the roundtrip latency of the Environment [i.e., the amount of time it takes for a roundtrip communication to complete between the host ThreatConnect instance and the Environment Server(s)];
  • the current size of the queue.

Environment Details

The Environment Details section provides the following information on the Environment:

  • Playbook References: The number of Playbooks that reference the Environment (i.e., Dependent Playbooks from the card view in Figure 1).
  • Job References: The number of Jobs that reference the Environment (i.e., Dependent Jobs from the card view in Figure 1).
  • Organization: The Organization to which the Environment belongs (i.e., Owner from the card view in Figure 1).
  • Command Queue Name: The name of the command queue used by the Environment (i.e., the queue for all requests to the host ThreatConnect instance).
  • Response Queue Name and Response Queue Size: The name and size of the response queue used by the Environment, respectively (i.e., the queue for all responses from Environment Servers).
  • Executions Today, Executions Last 7 Days, and Executions Last 30 Days: The number of executions on the Environment during the current day, over the previous week, and over the previous month, respectively.

To view a list of all Playbooks using the Environment, click the number to the right of Playbook References. The Playbooks using <Environment Name> window will be displayed with a list of all Playbooks using the Environment and whether each Playbook is active or inactive (Figure 2). Click the name of a Playbook to open it in the Playbook Designer.

Figure 2_Administrating an Environment_7.7.0

 

To view a list of all Jobs using the Environment, click on the number next to Job References. The Jobs using <Environment Name> window will be displayed with a list of all Jobs using the Environment and whether each Job is active or inactive (Figure 3).

Figure 3_Administrating an Environment_7.7.0

 

Recent App Executions

The Recent App Executions section lists details about the Jobs that have been executed recently on the Environment.

Environment Servers

If an Environment Server has been configured to the Environment, the Environment Servers section will display version, hardware, memory, and other information about the Environment Server:

  • The color of the left border of this section indicates the following:
    • Green: The Environment Server is running.
    • Red: The Environment Server is shut down or in the process of restarting.
      Note
      When this screen is first loaded, there may be a short delay in which the left border will be red even if the Environment Server is running, after which it will turn green.
  • Name: The name of the Environment Server.
  • Version: The version of the Environment Server. Version 2.x operates on instances of ThreatConnect that are at version 5.7 or newer.
  • Machine ID: The unique identification number of the machine on which the Environment Server operates.
  • Agent Status: The color of the circle indicates whether the Environment Server is configured to the Environment. It will typically be green, even when the Environment Server is shut down or restarting, indicating that the Environment Server remains configured to the Environment regardless of the Environment Server’s status. It will turn red if the agent fails or loses connectivity from the remote network.
    Note
    When this screen is first loaded, there may be a short delay in which the circle will be red, after which it will turn green. The delay for the circle’s color change may be slightly longer than the delay for the colored strip’s color change.
  • CPU, Memory, Disk, CPU Utilization, and Memory Utilization: Statistics on the hardware and memory capacities of the Environment Server.
  • Remote Workers: The number of Workers allocated to the Environment Server. Click EditIcon  Description automatically generated to the right of the Remote Workers heading to change the number of Workers allocated to the Environment Server, if desired.
  • Running Tasks: A list of the Apps or Services that are currently running on the Environment Server and the amount of time for which they have been running.
  • ⋮ menu: Click the menu at the top right of the Environment Servers section to display the following options:
    • Shutdown: Select this option to shut down the Environment Server.
    • Start up: Select this option to start the Environment Server.
    • Restart: Select this option to restart the Environment Server.
    • Delete: Select this option to delete the Environment Server.
      Important
      If an Environment Server is running, only the Shutdown and Restart options will be available. If an Environment Server has been shut down, only the Start Up and Delete options will be available.

Command-Line Configuration of an Environment Server

The command-line interface (CLI) provides options for viewing, editing, and exporting system configuration values, as well as for viewing, editing, and deleting keychain variables for an Environment Server.

Important
The Environment Server must first be shut down in order to use the CLI administration options.
  1. Change to the Environment Server directory:
    cd threatconnect-envsvr
  2. Initiate configuration mode:
    ./configure.sh
  3. Once configuration mode is initiated, the following menu will be displayed:
    Please select an option:
    
    1: System Configuration
    
    2: Variables
    
    3: Exit
  4. Select System Configuration from the menu in Step 3 to display the following sub-menu:
    System Configuration: Please select an option:
    
    1: List all System Config
    
    2: Edit System Config
    
    3: Export Configuration
    
    4: Go Back
    • List all System Config: Select this option to list all system configuration values. See the "System Configuration Values" section for a description of each system configuration value.
    • Edit System Config: Select this option to choose a system configuration value and replace its value with a new one.
    • Export Configuration: Select this option to export the system configuration.
    • Go Back: Select this option to return to the menu in Step 3.
  5. Select Variables from the menu in Step 3 to display the following sub-menu:
    Variables: Please select an option:
    
    1: List all Variables
    
    2: Create a Variable
    
    3: Delete a Variable
    
    4: Go Back
    • List all Variables: Select this option to list all keychain variables for the Environment.
    • Create a Variable: Select this option to create a keychain variable for the Environment.
    • Delete a Variable: Select this option to delete a variable from the Environment.
    • Go Back: Select this option to return to the menu in Step 3.
  6. Select Exit from the menu in Step 3 to exit from the Environment Server configuration.

System Configuration Values

Table 1 provides a description of each system configuration value available when you select List all System Config from the sub-menu displayed in Step 4 of the "Command-Line Configuration of an Environment Server" section.

System Configuration ValueDescription
apiURLThe URL for the API at port 8443 (e.g., https://api.threatconnect.com:8443).
appDeliveryTokenThe token used to authenticate with the App Catalog Server.
appsJavaHomeThe path to the Java® binary.
appsNumberofJobExecutorsThe 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.
appsPythonHomeThe path to the Python® binary.
appsSandboxUserThe user account used to execute Jobs. It is pertinent only in Linux® installs.
appsSessionDaystoKeepThe number of days that logs will be kept in the Jobs log directory: %threatconnect%/exchange/jobs. For Dedicated Cloud instances, the value of this setting is 5.
brokerHostThe remote host name of the messaging server to which the Environment Server will connect.
brokerTokenThe secure key used to authenticate a connection to the remote message broker.
proxyExternalWhen this system configuration value is set to true, all external connections for Apps will be routed through a proxy server.
proxyHostThe 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.
Important
Do not include the protocol (e.g., http://, https://) when configuring this system configuration value.
proxyPasswordThe proxy password to use if a proxy server requires authentication.
proxyPortThe proxy port to use if a proxy server is required. Enter a valid proxy port number.
proxyTCWhen this system configuration value is set to true, all connections to the ThreatConnect host server will be routed through a proxy server.
proxyUsernameThe proxy username to use if a proxy server requires authentication.
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.
serverXidA static number that uniquely identifies the given Environment Server. Its value should not be changed.

Queue Options

When the number of Apps, Services, and Jobs that are being remotely executed is larger than the number of available Workers, the remaining executions are put into a queue. Click the menu at the upper-right corner of the administration page for an Environment (Figure 1) to display the following options:

  • Pause Queue: Select this option to pause the queue.
  • Resume Queue: Select this option to resume a queue that is paused.
  • Flush Queue: Select this option to flush the queue.

Environment Settings

Click SettingsPlaybook Settings iconat the upper-right corner of an Environment’s administration screen to open the Environment Settings window (Figure 4). This window provides options for managing the remote variables defined for the Environment and downloading the Environment’s configuration file.

Figure 4_Administrating an Environment_7.7.0

 

Delete a Variable

Click DeleteTrash icon_Blackon the Environment Settings window for an existing variable to delete it. The variable will be deleted immediately and you will not be prompted for confirmation.

Create a Variable

Follow these steps to create a variable and add it to an Environment:

  1. Click Add Variable on the Environment Settings window.
  2. On the Create Remote Variable window, enter the name of a keychain variable that has been defined via the command-line configuration options for the Environment Server. (See the “Command-Line Configuration of an Environment Server” section.) Then click Save to create the variable and add it to the corresponding keychain list for Playbook Apps and Services running on the Environment.

Download Environment Configuration

Click Download Configuration on the Environment Settings window to download the configuration file for the Environment.


ThreatConnect® is a registered trademark of ThreatConnect, Inc.
Linux® is a registered trademark of Linus Torvalds.
Java® is a registered trademark of the Oracle Corporation.
Python® is a registered trademark of the Python Software Foundation.

20080-04 v.06.B


Was this article helpful?