Provision Service

You must install an Agent for Helix Control-M to run and monitor jobs on your application host. The Provision service enables you to set up an Agent. In addition, you can deploy application plug-ins or integration plug-ins to the Agent during the provision process. The repository contains a group of images, including Agent images for the various operating systems and plug-in images for various Control-M plug-ins.

  • If you run the Provision service, ensure that Control-M Automation API CLI is successfully installed on the same host where you plan to install the Agent. See Setting Up the API.

  • Before the initial setup or installation, you must set the Java environment variable that points to an external Java installation. See Setting the Java Environment Variable.

  • If you provision an Agent on a host that uses a proxy server, ensure that the proxy server settings are defined, as described in Proxy Server Configuration.

Agent and Plug-in Provisioning

Provisioning Agents is based on images. An image is JSON code that lists the installation packages in the order they are installed.

You must obtain the installation packages for the Agent, application plug-ins, or integration plug-ins referenced in the images before the provision process. You might also need to set up a local repository for the installation packages and images. For more information about these administrative tasks, see Control-M Automation API Provisioning.

You can install an Agent with one of the following methods:

  • Run separate image and setup commands: Enables you to download and prepare the installation files for the Agent with the image command. You can set up the Agent and register it to the Control-M/Server with the setup command at a later time. This method is beneficial for dynamic installations, such as installations that use a VM image.

  • Run a single install command: Performs the full Agent installation process with a single install command. This method is beneficial for static architectures that do not distinguish between image building and instantiation.

To provision a plug-in on an Agent that is registered to a Helix Control-M/Server, run the image command only.

The following table describes the API commands to set up repositories for provisioning, provision Agents, and deploy plug-ins, based on which type of Server the Agent is registered.

Command

Description

Server Type

provision images

Gets a list of available images.

  • Helix

  • Self-hosted
provision image Prepares the file system to install an Agent.

  • Helix

  • Self-hosted

provision agent::setup

Registers an Agent and connects it to a Server.

Self-hosted

provision saas:agent::setup

Registers an Agent and connects it to a Server.

Helix

provision agent::install

Runs all phases of image installation, including image and setup.

Self-hosted

provision saas::install

Runs all phases of image installation, including image and setup.

Helix

provision agent::update

Downloads and installs the latest version of Control-M/Agent and any installed plug-ins to the Agent host.

Helix

provision image::remove

Uninstalls an image from the user account but does not unregister it.

  • Helix

  • Self-hosted

provision agent::uninstall

Uninstalls an image from the user account and unregisters it.

  • Helix

  • Self-hosted

provision repository::add

Adds a repository where installation packages and images are stored for provisioning.

Self-hosted

provision repository::get

Gets details of a repository used in provisioning actions.

Self-hosted

provision repositories::get

Gets details of all defined repositories from Control-M/EM.

Self-hosted

provision repository::delete

Deletes a repository for provisioning.

Self-hosted

provision repository::set

Sets the default repository for provisioning actions.

Self-Hosted

provision images

The provision images command enables you to get a list of the images that are available on the Server for a specific operating system. The command returns a list of image names.

CLI Syntax

The following shows the CLI syntax for the provision images command:

ctm provision images <os> [-s version=all|latest|<numeric_string>]

The following table describes the provision images command parameters.

Parameter

Description

os

Determines the operating system specified for the retrieved images.

Valid values:

  • Linux (for Linux 64-bit)

  • Windows (for Windows 64-bit)

-s version

(Optional) Filters the returned list of images by version.

Valid values:

  • latest: Only images of the latest version.

  • numeric_string: Only images that contain the specified numeric string as part of their version number.

  • all: All images in the repository.

Default: latest

The following example shows a request for a list of the latest available images and a typical response:

Copy 
> ctm provision images Linux 
[
   "AWS_plugin.Linux",
   "Agent_Amazon.Linux",
   "Agent_CentOs.Linux",
   "Agent_Oracle.Linux",
   "Agent_RedHat.Linux",
   "Agent_Suse.Linux",
   "Agent_Ubuntu.Linux",
   "Application_Integrator_plugin.Linux",
   "Azure_plugin.Linux",
   "Databases_plugin.Linux",
   "Hadoop_plugin.Linux",
   "Informatica_plugin.Linux",
   "MFT_plugin.Linux",
   "SAP_plugin.Linux"
]

If annotation is enabled for the Configuration Management category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the provision images command in cURL:

Copy 
os=Linux
curl -H "x-api-key: $token" $endpoint/provision/images/$os?version=9.0.20.080

provision image

The provision image command downloads an image and installs it into the current user account.

If the image is a plug-in image, run this command only.

If the image is an Agent image, run this command and then you must register the Agent on the server with the appropriate setup command.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision image command:

ctm provision image <image> -f <configuration file> [-r <repository name>]

The following table describes the provision image command parameters.

Parameter

Description

image

Determines which image to provision.

You can specify the image in one of the following ways:

  • The name of one of the image files returned by the provision images command.

    You do not need to include the OS extension in the name of the image file. For example, you can specify Agent, rather than Agent.Linux. The operating system is detected automatically.

  • If you set up a local repository, as described in Setting Up a Local Repository for Provision Images and Installation Packages, you can specify the image in the following format:

    <name>.<version>

    where the image <name> is one of the following:

    • Agent

    • Hadoop

    • Databases

    • AWS

    • Airflow

    • OEBS

    • PeopleSoft

    • SAP

    • Informatica

    Informatica.9.0.21.300

configuration file

Defines the JSON file that contains the javaHome parameter when you provision an Agent that connects to a self-hosted Control-M/Server.

The following example shows the parameter in a JSON configuration file that indicates the location of the JRE to install an Agent on Windows:

Copy 
{
"javaHome": "C:\\java\\Eclipse_Adoptium_jre-17.0.6.10-hotspot"
}

repository name

Determines which local repository to select for this provisioning action. Select from all the local repositories defined with provision repository::add.

If you do not specify the local repository with the -r option, ensure that you set a default with provision repository::set.

Ensure that the relevant product code is in the installed-versions.txt file located in the Agent home directory to verify that the agent is registered successfully.

The following table shows the plug-in product codes.

Plug-in

Product Code

Application Integrator

DRAIT.9.0.20.080

AWS

DRAMZ.9.0.20.080

Azure

DRAZR.9.0.20.080

Databases

DRMQL.9.0.20.080

Hadoop

DRCBD.9.0.20.080

Informatica

DRINF.9.0.20.080

Managed File Transfer (MFT)

DRAFP.9.0.20.080

SAP

DRRMC.9.0.20.080

provision agent::setup

The provision agent::setup command enables you to connect and register an image with a Control-M environment.

Use this command only to provision an Agent that connects to a self-hosted Control-M/Server. For all other Agents, use provision saas:agent::setup.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision agent::setup command:

ctm provision agent::setup [server] [name] [port] [-f <configuration file>]

The following table describes the provision agent::setup command parameters.

Parameter

Description

server

Defines the Control-M/Server to register the Agent.

If omitted or empty and there is only one Server, the system selects that server. In this scenario, if you define name or port, include "" as a placeholder for the server.

provision agent::setup

provision agent::setup "" "" 2056

provision agent::setup "" "alias1" 2056

name

Defines the hostname or alias of the Agent. This is the logical name of the Agent.

If omitted or empty, the system uses the hostname. In this scenario, if you define server or port, include "" as a placeholder for the name.

port

Defines the port to designate as the Agent listening TCP/IP port.

If omitted or empty, the system uses an available free port. In this scenario, if you define name and server, include "" as a placeholder for the port.

configuration file

(Optional) Defines the JSON file with additional parameters.

The following example shows a configuration file:

Copy 
{
    "connectionInitiator": "AgentToServer",
    "tag": "abc_1234",
    "serverHostName":"ctmServer2",
    "serverPort": 7777,
    "secondaryServerHostName": "ctmServer3"
}

The following table describes additional provision agent::setup command parameters in the configuration file.

Parameter

Description

connectionInitiator

Determines the component that initiates the connection between the Agent and Server.

Values:

  • AgentToServer

  • ServerToAgent

  • BothAllowed

Default: BothAllowed

tag

Defines a tag associated with the Agent in Role-Based Administration (RBA).

Tags can contain alphanumeric characters and underscores. The maximum length is 85 characters.

serverHostName

Defines the name of the server host to override the default server hostname.

This is a required parameter to provision an agent with Role Authorizations.

serverPort

Defines the port number for server-to-agent communication to override the default server port.

This is a required parameter to provision an agent with Role Authorizations.

secondaryServerHostName

Defines the name of the secondary Server host for High Availability (HA) configurations.

This is a required parameter to provision an agent with Role Authorizations.

If annotation is enabled for the Configuration Management category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

provision saas:agent::setup

The provision saas:agent::setup command enables you to register an agent and connects it with a Control-M environment.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision saas:agent::setup command:

ctm provision saas:agent::setup <agentTagName> [name]

The following table describes the provision saas:agent::setup command parameters.

Parameter

Description

agentTagName

Defines the name of the agent tag associated with the agent authorization token.

For information about generating a token, see Generating an Agent Token.

name

(Optional) Defines a name or alias for the agent to appear in the agent list that appears in the Helix Control-M user interface.

Default: hostname-user (if not specified)

Ensure that the relevant product code, DRKAI.9.0.20.080, is in the installed-versions.txt file located in the Agent home directory to verify that the agent is registered successfully.

provision agent::install

The provision agent::install command enables you to combine the image and setup commands into one action. The command downloads the agent, and then connects and registers it with a Server.

Use this command only to provision an Agent that connects to a self-hosted Control-M/Server. For all other Agents, use provision saas::install.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision agent::install command:

ctm provision agent::install <image> [server] [name] [port] [-f <configuration file>] [-r <repository name>]

The following table describes the provision agent::install command parameters.

Parameter

Description

image

Determines which image to install.

You can specify the image in one of the following ways:

  • The name of one of the image files that the provision images command returns.

    You do not need to include the OS extension in the name of the image file. For example, you can specify Agent, rather than Agent.Linux. The operating system is detected automatically.

  • If you set up a local repository, as described in Setting Up a Local Repository for Provision Images and Installation Packages, specify the image in the following format:

    <name>.<version>

    where the image <name> is one of the following:

    • Agent

    • Hadoop

    • Databases

    • AWS

    • Airflow

    • OEBS

    • PeopleSoft

    • SAP

    • Informatica

    Informatica.9.0.21.300

server

Determines the Server to register the Agent.

If omitted or empty and there is only one Server, the system selects that server. In this scenario, if you define name or port, include "" as a placeholder for the server.

provision agent::install

provision agent::install"" "" 2056

provision agent::install"" "alias1" 2056

name

Defines the hostname or alias of the Agent. This is the logical name of the Agent.

If omitted or empty, the system uses the hostname. In this scenario, if you define server or port, include "" as a placeholder for the name.

port

Determines the port to designate as the Agent listening TCP/IP port.

If omitted or empty, the system uses an available free port. In this scenario, if you define name and server, include "" as a placeholder for the port.

configuration file

(Optional) Defines the full path to a JSON file that contains additional parameters.

Mandatory for Control-M/Agent upgrade to version 9.0.21: You must use a configuration file and set the mandatory javaHome parameter.

The following example shows a configuration file:

Copy 
{
    "connectionInitiator": "AgentToServer",
    "tag": "abc_1234",
    "serverHostName":"ctmServer2",
    "serverPort": 7777,
    "javaHome": "C:\\java\\Eclipse_Adoptium_jre-17.0.6.10-hotspot"
}

repository name

Determines which local repository to select for this provisioning action. Select from all the local repositories defined with provision repository::add.

If you do not specify the local repository with the -r option, ensure that you set a default with provision repository::set.

The following table describes additional provision agent::install command parameters for the configuration file.

Parameter

Description

connectionInitiator

Determines the component that initiates the connection between the Agent and Server.

Values:

  • AgentToServer

  • ServerToAgent

  • BothAllowed

Default: BothAllowed

tag

Defines a tag associated with the Agent in Role-Based Administration (RBA).

Tags can contain alphanumeric characters and underscores. The maximum length is 85 characters.

serverHostName

Defines the server hostname to override the default.

This is a required parameter to provision an agent with Role Authorizations.

serverPort

Defines the port number for server-to-agent communication to override the default server port.

This is a required parameter to provision an agent with Role Authorizations.

javaHome

(Mandatory) Defines the full path to a JRE.

If annotation is enabled for the Configuration Management category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

provision saas::install

The provision saas::install command enables you to implement all phases of image installation. For an Agent, this includes both image and setup.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision saas::install command:

ctm provision saas::install <image> <agentTagName> [name]

The following table describes the provision saas::install command parameters.

Parameter

Description

image

Determines which image to install.

You can specify the image in one of the following ways:

  • The name of one of the image files returned by the provision images command.

    You do not need to include the OS extension in the name of the image file. For example, you can specify Agent, rather than Agent.Linux. The operating system is detected automatically.

  • If you have set up a local repository (as described in Setting Up a Local Repository for Provision Images and Installation Packages), you can specify the image in the following format:

    <name>.<version>

    where the image <name> is one of the following:

    • Agent

    • Hadoop

    • Databases

    • AWS

    • Airflow

    • OEBS

    • PeopleSoft

    • SAP

    • Informatica

    Informatica.9.0.21.300

agentTagName

Defines the name of the agent tag associated with the agent authorization token.

For information about generating a token, see Generating an Agent Token.

name

Defines a name or alias for the Agent to appear in the Agent list in the Helix Control-M user interface.

Default: hostname-user (if not specified)

Ensure that the relevant product code, DRKAI.9.0.20.080, is in the installed-versions.txt file located in the Agent home directory to verify that an agent was installed successfully.

provision agent::update

The provision agent::update command enables you to download and install the latest version of Agent and any installed plug-ins to the Agent host that runs the command.

  • This API command is supported only through the CLI and cannot be called through a REST API command.

  • To run this command, the current version of Agent must be 9.0.20.280 or higher.

  • If Control-M MFT or Control-M for SAP is installed on the Agent, you must stop the Agent before you run this API command and start it afterward. To avoid Agent downtime, you can create a host group and include multiple Agents with the same plug-in within the host group. After you shut down one Agent, jobs are routed to another Agent in the host group.

CLI Syntax

The following shows the CLI syntax for the provision agent::update command:

ctm provision agent::update [instanceName]

To skip confirmation messages during installation, add -y after the command.

The following table describes the provision agent::update command parameter.

Parameter

Description

instanceName

(Windows only) Defines which Agent instance to update.

If not defined, the Default installation is updated.

This parameter is required for environments with multiple Agents.

provision image::remove

The provision image::remove command enables you to uninstall an image from a user account without unregistration in Control-M.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision image::remove command:

ctm provision image::remove

provision agent::uninstall

The provision agent::uninstall command enables you to uninstall an image from a user account and unregisters it from the Server.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision agent::uninstall command:

ctm provision agent::uninstall

provision repository::add

The provision repository::add command enables you to define a repository to store installation packages and images for provisioning actions.

This method to define a local repository is an alternative to environment configure. It enables you to define numerous different repositories and each supports multiple Control-M environments.

This method is supported only for Agents that are registered to self-hosted Servers (not for Agents registered to Helix Servers).

CLI Syntax

The following shows the CLI syntax for the provision repository::add command:

ctm provision repository::add <name> <location> [<description>]

The following table describes the provision repository::add command parameters.

Parameter

Description

name

Defines the repository name.

location

Defines the path to the storage location of the installation packages for provisioning actions.

  • Local filesystem: file:///home//localProvisionRepo

  • Amazon S3 Bucket: https://s3-us-west-2.amazonaws.com/localProvisionRepo

description

(Optional) Defines a textual description of the repository.

If annotation is enabled for the Configuration Management category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the provision repository::add command in cURL:

Copy 
name=Location1
location="file:///home//localProvisionRepo"
description="Local repository"
  
curl -H "x-api-key: $token" -X POST  "$endpoint/provision/repository" 
-d '{"name": "$name", "location": "$location", ["description": "$description"]}'

provision repository::get

The provision repository::get command enables you to get details of a repository defined for provisioning actions.

CLI Syntax

The following shows the CLI syntax for the provision repository::get command:

ctm provision repository::get <name>

where <name> is the name of the local repository defined for provisioning actions.

REST API Syntax

The following example shows the REST API syntax for the provision repository::get command in cURL:

Copy 
name=Location1
curl -H "x-api-key: $token" "$endpoint/provision/repository/$name"

provision repositories::get

The provision repositories::get command enables you to get the details of all defined provisioning repositories.

CLI Syntax

The following shows the CLI syntax for provision repositories::get the command:

ctm provision repositories::get

REST API Syntax

The following example shows the REST API syntax for the provision repositories::get command in cURL:

Copy 
curl -H "x-api-key: $token" "$endpoint/provision/repositories"

provision repository::delete

The provision repository::delete command enables you to delete a repository defined for provisioning actions . The response returns the details of all remaining repositories.

CLI Syntax

The following shows the CLI syntax for the provision repository::delete command:

ctm provision repository::delete <name>

where <name> is the name of the defined local repository that you no longer want for provisioning actions.

If annotation is enabled for the Configuration Management category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the provision repository::delete command in cURL:

Copy 
name=Location1
curl -X DELETE -H "x-api-key: $token" "$endpoint/provision/repository/$name"

provision repository::set

The provision repository::set command enables you to set the default repository for provisioning actions (of all defined provisioning repositories).

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision repository::set command:

ctm provision repository::set <name>

where <name> is the name of the defined local repository that you want as the default for provisioning actions.

If the default repository is set in multiple ways, the actual default is determined according to the following order of precedence:

  1. As set by the -r option in the individual provision image or provision agent::install command.

  2. As set by the EXT_AUTO_DEPLOY and EXT_APPLICATION_ARTIFACTS_JSON_URL parameters via environment configure.

  3. As set by the following API command:

    provision repository::set.

See also Setting Up a Local Repository for Provision Images and Installation Packages.