Environment Service

The Environment service enables you to define, select and manage a Control-M environment. An environment is a combination of a REST API endpoint and API token, or a REST API endpoint, username, and password.

The REST API endpoint is a URL that is a point of contact between an API client and an API server. The endpoint has the following format:

https://<controlmEndPointHost>:8443/automation-api

Environments are saved in the env.json file, located in the .ctm folder in the home user directory for the logged in user. This user must have read/write permissions. Sensitive information is automatically encrypted in the env.json file.

The following API commands enable you to manage environments:

environment show

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

The following shows the CLI syntax for the environment show command:

ctm environment show

environment add

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

The following shows the CLI syntax for two different options to run the environment add command:

  • Username and password: ctm environment add <env> <endPoint> <user> [<password>]

    The following example shows a command and response to add an environment named devEnvironment with username and password:

    Copy 
    > ctm environment add devEnvironment "https://<controlmEndPointHost>:8443/automation-api" "<ControlmUser>" "<ControlmPassword>"
     
    info:    Environment 'devEnvironment' was created
    info:    devEnvironment:
    {"endPoint":"https://<controlmEndPointHost>:8443/automation-api","user":"<ControlmUser>"}

  • Token:ctm environment add <env> <endPoint> <token>

    The following example shows a command to add an environment named devEnvironment with a valid token, as described in Authentication Service

    ctm environment add devEnvironment "https://<controlmEndPointHost>:8443/automation-api" "<token>"

The following table describes the environment add command parameters.

Parameter

Description

env

Defines the environment name.

endPoint

Defines the Control-M REST API endpoint.

user

Defines a Control-M username.

If you specify an LDAP user, add a prefix to the username with the following domain:

<domain>\<user>

password

Defines a Control-M password.

You can type the password either as a parameter in the command or include the -p or --prompt switch after the API command to respond with a prompt for the password.

token

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

For more information about API tokens, see Authentication Service.

The system checks for the certificate policy when it adds an environment. If the environment is set to accept self-signed certificates, a warning appears. If you want to apply a stricter policy to only accept certificates signed by a trusted Certificate Authority and not accept self-signed certificates, you can run the environment configure command and set the rootCertificateRequired parameter to true.

environment workbench::add

The environment workbench::add command enables you to add an environment for the installed Control-M Workbench.

The following shows the CLI syntax for the environment workbench::add command:

ctm environment workbench::add [<endPoint>]

where [<endPoint>] is the REST API endpoint for the Control-M Workbench.

By default, the Workbench endpoint is https://localhost:8443/automation-api. The username and password are workbench.

You can include this parameter if you installed the Workbench on a different host.

environment set

The environment set command enables you to set the default environment for interactive work. This command sends all commands to this environment unless you define a different environment with the -e option.

If you do not have any environments defined and you add the very first environment with the environment add or the environment workbench::add command, that first environment is automatically set as the default. If you define additional environments, run this command to set a new default.

The following shows the CLI syntax for the environment set command:

ctm environment set <env>

where <env> is the environment name.

environment delete

The environment delete command enables you to delete an environment.

The following shows the CLI syntax for the environment delete command:

ctm environment delete <env>

where <env> is the environment name.

environment update

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

The following shows the CLI syntax for the environment update command:

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

The following table describes the environment update command parameters.

Parameter

Description

env

Defines the environment name.

name

Determines the name of the property:

  • endPoint

  • user

  • password

  • token

  • additionalLoginHeader

value

Defines the property value for the specified property name:

  • endpoint: Defines a URL that points to the endpoint and begins with https.

  • user: Defines a Control-M username. If you specify an LDAP user, add a prefix to the username with the following domain: <domain>\<user>

  • password: Defines a Control-M password.

  • token: Defines the 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: Defines an additional header to include in login requests from the CLI with the following format: "Header_Name:Header_value"

environment copy

The environment copy command enables you to duplicate an environment.

The following shows the CLI syntax for the environment copy command:

ctm environment <env> <newEnv>

The following table describes the environment copy command parameters.

Parameter

Description

env

Defines the name of the original environment.
newEnv Defines the name of the new environment.

environment load

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

The following shows the CLI syntax for the environment load command:

ctm environment load <enviromentsFile>

where <enviromentsFile> is the env.json file. The env.json file is in the .ctm folder in the home user directory for the logged-in user. This user must have read/write permissions.

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.

The following shows the CLI syntax for the environment configure command:

ctm environment configure <setting name> [setting value]

The following table describes the environment configure command parameters.

Parameter

Description
setting name Defines the parameter name.
setting value Defines the parameter value.

The following table describes possible environment configuration parameters:

Parameter

Description

rootCertificateRequired

Determines whether to disable API calls with a self-signed HTTPS certificate, and only allow certificates signed by a trusted Certificate Authority.

Valid values:

  • true: Allows certificates signed by a trusted Certificate Authority.

  • false: Allows self-signed certificates and certificates signed by a trusted Certificate Authority.

Default: false

EXT_APPLICATION_ARTIFACTS_JSON_URL

Defines a path to a local repository of provisioning images and overrides the default location for provisioning actions performed by the Provision Service.

For more information, see Setting Up a Local Repository for Provision Images and Installation Packages.

EXT_AUTO_DEPLOY

Defines a path to a local repository of installation packages for provisioning actions performed by the Provision Service.

For more information, see Setting Up a Local Repository for Provision Images and Installation Packages.