Environment Service

The Environment service enables you to manage environments, including defining and selecting the Control-M environment to use. An environment is a combination of an endpoint and API token.

An endPoint has the following format:

https://<controlmEndPointHost>/automation-api

The Helix Control-M endpoint host has the following format: <tenant-name>-aapi.prod.controlm.com

Environments are saved in the env.json file, which is located under the .ctm folder, on the home user that has read/write permissions only for the logged in user. Sensitive information, such as passwords and tokens, is encrypted in the env.json file.

For example, the following command adds an environment named myEnvironment. In this command, you include a valid token, as described in Authentication Service.

Copy

ctm environment add myEnvironment "https://tenant-123-aapi.prod.controlm.com/automation-api" "<token>"

The following API commands enable you to manage environments:

environment show
environment add
environment set
environment delete
environment update
environment copy
environment load
environment configure

environment show

The environment show command enables you to return a list of all defined environments.

Copy

ctm environment show

environment add

The environment add command enables you to add a new environment for a Control-M instance.

Copy

ctm environment add <env> <endPoint> <token>

The following table describes the environment add command parameters.

Parameter	Description
<env>	Environment name.
<endPoint>	Control-M REST API endPoint.
<token>	An API authentication token that allows the logged-in user to submit API requests. For more information about API tokens, see Authentication Service.

Parameter

Description

<env>

Environment name.

Control-M REST API endPoint.

<token>

An API authentication token that allows the logged-in user to submit API requests.

For more information about API tokens, see Authentication Service.

While the environment is added, it is checked for its policy regarding certificates. If the environment is currently set to accept self-signed certificates, a warning is displayed. If you want to apply a stricter policy of accepting only certificates signed by a trusted Certificate Authority (and not accepting self-signed certificates), you can use the environment configure command to set the rootCertificateRequired parameter to true.

environment set

The environment set command enables you to set the default environment for interactive work. All commands are sent to this environment unless a different environment is defined using the -e option.

When no environments are defined and you add the very first environment (using the environment add command), that first environment is automatically set as the default. Later, after additional environments have been defined, use this command to set a new default.

Copy

ctm environment set <env>

Where <env> is the environment name.

environment delete

The environment delete command enables you to delete an environment.

Copy

ctm environment delete <env>

Where <env> is the environment name.

environment update

The environment update command enables you to update an environment property.

Copy

ctm environment update <env> <name> <value>

The following table describes the environment update command parameters.

Parameter

Description

<env>

Environment name.

<name>

The name of the property:

endPoint
keyToken
additionalLoginHeader

<value>

Property value for the specified property name:

Property

Description

endpoint

A URL that points to the endpoint and begins with https.

keyToken

Name of an API authentication token that allows the logged-in user to submit API requests.

For more information about API tokens, see Authentication Service.

additionalLoginHeader

An additional header to include in login requests sent by the CLI, with the following format:

"Header_Name:Header_value"

environment copy

The environment copy command enables you to duplicate an environment.

Copy

ctm environment <env> <newEnv>

Where <env> is the name of the original environment and <newEnv> is the name of the new environment.

environment load

The environment load command enables you to load one or more predefined environments using the env.json file.

Copy

ctm environment load <enviromentsFile>

Where <enviromentsFile> is the env.json file, which is located under the .ctm folder, on the home user that has read/write permissions only for the logged in user.

Do not encrypt sensitive information, such as passwords and tokens, in the env.json file. This sensitive information is encrypted automatically when the file is loaded.

environment configure

The environment configure command enables you to set parameters for all environments.

Copy

ctm environment configure <setting name> [setting value]

Where <setting name> is the name of the parameter and [setting value] is the value for the parameter.

The following table describes possible environment configure parameters:

Parameter	Value	Default	Description
rootCertificateRequired	false \| true	false	Disable API calls that use a self-signed HTTPS certificate, and allow only certificates that are signed by a trusted Certificate Authority. By default, self-signed certificates are allowed.
listenerLogSizeMb	maximum log size in megabytes	10 MB	The maximum size of Alerts listener logs stored in <HOME>/.ctm/logs.
listenerMaxFileCount	number of log files to save	10 logs	The number of most recent Alerts listener log files to save in <HOME>/.ctm/logs.
listenerLogLevel	In descending severity and ascending detail: error warn info debug trace	info	The level of severity and detail of messages in the Alerts listener logs stored in <HOME>/.ctm/logs.