Provision service

For Control-M to run and monitor jobs on your application host, a Control-M/Server and Control-M/Agent should be installed. The Provision service allows you access to the full cycle of the following setup processes for agents and servers:

Provisioning a new Control-M/Agent and deploying application plug-ins

For a new installation, the Provision service includes the following major commands:

  • Image: prepares the file system installation of the Agent
  • Setup: registers and configures the Agent with a Control-M/Server
  • Install: runs image and setup in a single step

Separating the Image and Setup phases can help in a situation in which installing and setting up Agents dynamically is required by your architecture. In this scenario, you can prepare your image (whether it is a VM image, a Docker image, AWS AMI, etc.) with the Agent inside it. Then when required, use the setup command to dynamically perform Agent setup and register it to the Control-M/Server.

For a more static architecture, where there is no distinction between building an image and instantiation, you can use the provision install command, which allows you to install in a single step.

Additional commands are available for removing an image and for uninstalling a Control-M/Agent from the application host.

The images used during provisioning are JSON code too. Each image contains a list of installation packages in the order that they are installed. Several default images are provided with the base installation of Control-M Automation API, and you can create additional custom images (for example, for installation of a newer version of the Control-M/Agent). To prepare for provisioning, you must obtain the installation packages that are referenced within the images. You can also (optionally) customize the location in which to save these packages (for example, you might want to save the packages in a JFrog Artifactory repository, in Amazon S3 Buckets, or in your local file system). For more information about these preparatory tasks, see the Control-M Administrator Guide in the Control-M Online Help.

provision images

Get a list of the images available for a specific OS. Returns a list of image names.

CLI Syntax

CLI
ctm provision images <os>

Where:

Parameter

Description

<os>

OS can be one of the following:

  • Linux (for Linux 64-bit)
  • Windows (for Windows 64-bit)
  • Solaris
  • AIX

Here is an example of requesting a list of available images and a typical response:

> ctm provision images Linux -e devEnvironment
[
  "Agent.Linux",
  "Agent_18.Linux",
  "ApplicationsAgent.Linux",
  "BigDataAgent.Linux",
  "Server.Linux"
]

provision image

Downloads an image and prepares it for installation.

In the case of an Agent image, this command also installs the image into the current user account, but does not configure it or register it with a Control-M/Server.

CLI Syntax

CLI
ctm provision image <image>

Where:

Parameter

Description

<image>

The image that you want to prepare for installation, one of the images returned by the provision images command

provision agent::setup  

Connects and registers an image with a Control-M environment.

CLI Syntax

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

Where:

Parameter

Description

[ctm]

The agent registers to this Control-M/Server. If omitted or empty and only one Control-M/Server exists in the system, it will be selected.

[name]

The host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. If omitted or empty, the machine's name will be used.

[port]

This port is used as the Control-M/Agent listening TCP/IP port. If omitted or empty, an available free port will be used.

[configuration file]

(Optional) JSON file that contains additional parameters.

The following is a list of the additional REST request parameters that can be used:

{
    "connectionInitiator": "AgentToServer"
}

Where:

connectionInitiator

The component that initiates the connection between the Control-M/Agent and Control-M/Server.

The values supported are:

  • AgentToServer
  • ServerToAgent
  • BothAllowed (default)

For example:

provision setup
provision setup ""          ""       2056
provision setup "controlm1" ""       2056
provision setup ""          "alias1" 2056
provision setup -f persistent.json

provision agent::install

Combines the image and the setup commands into one action. Downloads the agent and then connects and registers it with a Control-M/Server.

CLI Syntax

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

Where:

Parameter

Description

<image>

The image that you want to install (one of the images returned by the provision images command)

[ctm]

The agent registers to this Control-M/Server. If omitted or empty and only one Control-M/Server exists in the system, it will be selected.

[name]

The host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. If omitted or empty, the machine's name will be used.

[port]

This port is used as the Control-M/Agent listening TCP/IP port. If omitted or empty, an available free port will be used.

[configuration file]

(Optional) JSON file that contains additional parameters.

The following is a list of the additional REST request parameters that can be used:

{
    "connectionInitiator": "AgentToServer"
}

Where:

ParameterDescription
connectionInitiator

The component that initiates the connection between the Control-M/Agent and Control-M/Server.

The values supported are:

  • AgentToServer
  • ServerToAgent
  • BothAllowed (default)

provision image::remove

Uninstalls a Control-M image from this user account without unregistering it in Control-M.

CLI Syntax

CLI
ctm provision image::remove

provision agent::uninstall

Uninstalls a Control-M image from this user account and unregisters it from the Control-M/Server.

CLI Syntax

ctm provision agent::uninstall

Upgrading an existing Control-M/Agent and deploying application plug-ins

You can use API commands to perform various upgrade activities on existing Control-M/Agents, including agent upgrades and plug-in deployments. The following table lists the various activities that you can perform using the provision upgrade group of API commands:


Control-M/AgentControl-M
Managed File Transfer
(MFT)
Control-M
Application Pack
Upgrade to a new version(tick)(tick)(tick)
Roll back to a previous version(tick)(tick)(tick)
Install new plug-in on existing AgentNA(tick)(tick)
Remove plug-in from AgentNA(tick)(error)

To prepare for provisioning, you must obtain the Control-M/Agent installation packages that you plan to use in your upgrades and place them in the <EM_HOME>/AUTO_DEPLOY directory. You must also ensure that the <EM_HOME>/CM_DEPLOY directory contains packages that are available for deployment, from your installations of Control-M MFT and Control-M Application Pack. For more information about preparing the packages, see the Control-M Administrator Guide in the Control-M Online Help.

The Provision service offers the following commands for upgrade processes:

CommandDescription
provision upgrades:versions::getObtains a list of upgrades that are available, based on the installation packages that you have in your directories.
provision upgrades:agents::getObtains a list of agents in your environment that are eligible for an upgrade.
provision upgrade::installTransfers a deployment package and installs it.
provision upgrade::uninstallRollls back an upgrade deployment package at the target Control-M/Agent.
provision upgrade::getObtains status details for a specific upgrade activity.
provision upgrades::get

Obtains status details for all upgrade activities or for multiple upgrade activities based on specified filters.

provision upgrade:output::get

Retrieves output log messages from the Control-M/Agent regarding a specific upgrade activity.

provision upgrade::retry

Retries to run an upgrade activity that failed previously.

provision upgrade::deleteDeletes the record of an upgrade activity that has finished running.
provision upgrade::cancelAborts an upgrade activity that is currently running.

provision upgrades:versions::get

Obtains a list of upgrades that are available, based on the installation packages that are currently stored in your directories — Control-M/Agent packages in <EM_HOME>/AUTO_DEPLOY, Control-M MFT and Control-M Application Pack packages in <EM_HOME>/CM_DEPLOY.

CLI Syntax

CLI
ctm provision upgrades:versions::get

REST API Syntax

See REST API reference.

curl -H "Authorization: Bearer $token" $endpoint/provision/upgrades/versions

Response

The response lists all available upgrades according to type (Agent, MFT, or AppPack) and target version, as in the following example:

[
 {
   "type": "Agent",
   "version": "9.0.18.200"
 },{
   "type": "AppPack",
   "version": "9.0.18.100"
 },{
   "type": "MFT",
   "version": "9.0.18.100"
 }
]

provision upgrades:agents::get

Obtains a list of agents in your environment that are eligible for upgrade using any of the packages that are found in your directories. You can optionally limit the list to upgrades of a certain type (Agent, MFT, or AppPack) and target version.

CLI Syntax

CLI
ctm provision upgrades:agents::get [-s <query string>]

Where <query string> can contain one or both of the following fields:

FieldValues
typeAgent, MFT, or AppPack
version

Target version to which you want to upgrade

For example: 9.0.00, 9.0.00.100, 9.0.18.000, or 9.0.18.200

The following example command will return details for agents that can be upgraded to version 9.0.18.200:

ctm provision upgrades:agents::get -s "type=Agent&version=9.0.18.200"

The following example command will return details for agents on which Control-M MFT can be deployed (installed or upgraded):

ctm provision upgrades:agents::get -s "type=MFT"

REST API Syntax

See REST API reference.

curl -H "Authorization: Bearer $token" 
"$endpoint/provision/upgrades/agents?type=Agent&version=9.0.18.000"

Response

The response provides details for each agent and each possible upgrade that can be performed on it. In the following example, one agent was found eligible for upgrade from version 9.0.00 to version 9.0.18.100. The same agent was found eligible for installation of Control-M MFT version 9.0.18.000 (which is currently not installed).

[
    {
		"agent": "vw-one-ae65",
		"ctm": "vw-one-ae65",
		"type": "Agent",
		"platform": "windows_x86_64",
		"fromVersion": "9.0.00",
		"toVersion": "9.0.18.100"
	},{
		"agent": "vw-tlv-one-ae65",
		"ctm": "vw-tlv-one-ae65",
		"type": "MFT",
		"platform": "windows_x86_64",
		"fromVersion": "",
		"toVersion": "9.0.18.000"
	}
]

provision upgrade::install

Transfers a deployment package to the agent host and installs it there. Use this API command to perform any of the following activities:

  • Upgrade a Control-M/Agent to a newer version
  • Install a new plug-in (Control-M MFT or Control Application Pack) on an existing Agent
  • Upgrade a plug-in (Control-M MFT or Control Application Pack) on the Agent

CLI Syntax

CLI
ctm provision upgrade::install <ctm> <agent> <type> <version> [activityName] [-f <configuration file>]

Where:

Parameter

Description

<ctm>

Name of the Control-M/Server

<agent>

Name of host or alias of the Control-M/Agent

<type>

Type of upgrade — Agent, MFT, or AppPack

<version>Target version to which to upgrade
[activityName]

(Optional) A name for this upgrade activity.

If you do not specify an activity name, the default activity name is "<ctm>, <agent>, <type>".

[configuration file]

Full path to a JSON file that contains installation details

If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

In the following curl example, note that the path to the configuration file is prefixed with an @ character.

REST API
curl -H "Authorization: Bearer $token" 
-H "Content-Type:application/json" --data "@installConfigurationFile.json" 
-X POST $endpoint/provision/upgrade/install

Configuration file for provision upgrade or rollback

You need a configuration file in the following scenarios:

  • If you are using a REST API command, use the configuration file to specify values for the various upgrade parameters or rollback parameters (which can be included in a CLI command). These parameters include several required parameters (ctm, agent, type, and version) and the optional activityName.
  • To specify values for the following additional parameters. These parameters cannot be included in the CLI command:

    ParameterDescription
    installUserThe user account used to perform the installation of the package.

    This parameter is required if all of the following conditions exist:

    • The Control-M/Agent is hosted on a Windows computer.
    • The Control-M/Agent is currently at a version earlier than 9.0.00.300 (version 9.0.00, fix pack 3).
    • The Control-M/Agent's security setting "Logon as User" is set to Yes. For more information, see Security parameters in the Control-M Online Help.

    In all other cases, the user is set automatically, and any value that you set through this parameter is ignored.

    NOTE: Due to JSON character escaping, if the user name includes a backslash, each backslash must be doubled (for example, "domain\\userName").

    notifyAddressA list of email addresses of recipients of notifications regarding this upgrade or rollback process.

    Use the semicolon character (;) to separate multiple email addresses.

    descriptionA description for the upgrade activity.

The following sample configuration file contains all possible parameters (including the optional parameters and the parameters that you could alternatively set through the CLI command):

{
  "ctm": "localControlM",
  "agent": "agent1",
  "type": "Agent",
  "version": "9.0.18.100",   
  "activityName": "Agent1 upgrade for localControlM",
  "installUser": "user3",
  "notifyAddress": "joe@example.com;jane@example.com",
  "description": "Upgrading the agent to version 9.0.18.100"
}

Response

The installation package is deployed and installed, and an upgradeID is returned. The upgradeID has the following format: <ctm>:<activityNumber> (for example, LocalControlM:12)

provision upgrade::uninstall

Uninstalls an upgrade deployment package at the target Control-M/Agent. Use this API command to perform any of the following activities:

  • Roll back the newest version of a Control-M/Agent
  • Roll back the newest version of a plug-in (Control-M MFT or Control Application Pack)
  • Remove the Control-M MFT plug-in from the Agent (if no previous version was installed)

CLI Syntax

CLI
ctm provision upgrade::uninstall <ctm> <agent> <type> <version> [activityName] [-f <configuration file>]

Where:

Parameter

Description

<ctm>

Name of the Control-M/Server

<agent>

Name of host or alias of the Control-M/Agent

<type>

Type of upgrade that you are uninstalling — Agent, MFT, or AppPack

<version>Version to uninstall
[activityName]

(Optional) A name for this upgrade activity.

If you do not specify an activity name, the default activity name is "<ctm>, <agent>, <type>".

[configuration file]

Full path to a JSON file that contains uninstallation details

For more details about this configuration file, see Configuration file for provision upgrade or rollback.

If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

In the following curl example, note that the path to the configuration file is prefixed with an @ character.

REST API
curl -H "Authorization: Bearer $token" 
-H "Content-Type:application/json" --data "@installConfigurationFile.json" 
-X POST $endpoint/provision/upgrade/uninstall

Response

The installation package is uninstalled, and an upgradeID is returned. The upgradeID has the following format: <ctm>:<activityNumber> (for example, LocalControlM:12)

provision upgrade::get

Obtains status details for a specific upgrade activity.

The response provides the status of the upgrade activity, as well as various additional details (such as UTC timestamps of certain phases during the upgrade activity).

CLI Syntax

CLI
ctm provision upgrade::get <upgradeID>

Where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).

REST API Syntax

See REST API reference.

upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrade/$upgradeID"

provision upgrades::get

Obtains status details for all upgrade activities or for multiple upgrade activities based on specified filters.

The response provides the status of each upgrade activity, as well as various additional details (such as timestamps of certain phases during the upgrade activity).

CLI Syntax

CLI
ctm provision upgrades::get [-s <query string>]

Where <query string> can contain any of the following fields.

Note: For multiple values, use commas. As wildcards, you can use question mark and asterisk characters (? and *).

FieldDescription

ctm

Name of the Control-M/Server

agent

Name of host or alias of the Control-M/Agent

fromVersion

Source version (before the upgrade activity was performed)

For example: 9.0.00.100

toVersion

Target version

For example: 9.0.18.200

acivityType of upgrade activity, either Install or Uninstall
status

Status of the activity; one of the following:

  • Running
  • TransferCompleted
  • Completed
  • Canceled
  • Failed
  • Unavailable
activityNameName of the upgrade activity

The following example command will return status details for upgrades or rollbacks to version 9.0.18 and its fix packs on Agent1 and Agent2:

ctm provision upgrades::get -s "agent=Agent1,Agent2&toVersion=9.0.18*"

REST API Syntax

See REST API reference

curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrades?agent=Agent2&toVersion=9.0.18*" 

provision upgrade:output::get

Retrieves output log messages from the Control-M/Agent regarding a specific upgrade activity. The output log messages are displayed on-screen.

CLI Syntax

CLI
ctm provision upgrade:output::get <upgradeID>

Where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).

REST API Syntax

See REST API reference.

upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrade/$upgradeID/output"

provision upgrade::retry

Retries to run an upgrade activity that failed previously.

Note: The original upgrade activity was already assigned an upgradeID, and the retry activity does not create a new one. The response only returns a message that the retry has started.

CLI Syntax

CLI
ctm provision upgrade::retry <upgradeID>

Where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).

If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrade/$upgradeID/retry"

provision upgrade::delete

Deletes the record of an upgrade activity that has finished running (that is, an upgrade activity in status Completed, Cancelled, or Failed).

CLI Syntax

CLI
ctm provision upgrade::delete <upgradeID>

Where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).

If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" -X DELETE $endpoint/provision/upgrade/$upgradeID

provision upgrade::cancel

Aborts an upgrade activity that is currently running (that is, an upgrade activity in status Running or TransferCompleted).

CLI Syntax

CLI
ctm provision upgrade::cancel <upgradeID>

Where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).

If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" -X POST $endpoint/provision/upgrade/$upgradeID/cancel

Provisioning a Control-M/Server

Provisioning of a Control-M/Server is supported on Windows with an MS SQL database and on Linux with an Oracle database. You can create a new Control-M/Server or you can transfer an existing Control-M/Server from one machine to another (server rehydration).

When provisioning a Control-M/Server you can choose betwen running two separate commands or one command:

MethodTypical scenarioCommands
Two separate commands

Dynamic installation:

An image (such as a VM image) is prepared with the Control-M/Server ready inside it. Setup is performed at a later time, when required.

  • Image — downloads and prepares installation files for the Control-M/Server
  • Setup — installs and registers the Control-M/Server
One commandA more static architecture, with no distinction between building an image and instantiation.
  • Install — runs both Image and Setup in a single step

An additional command is available for uninstalling a Control-M/Server from the host machine.

Setup or installation of a Control-M/Server is based on settings that you define in a configuration file (a payload JSON file). For the full description of this configuration file, see Server Provisioning configuration.

The images used during provisioning are JSON code too. Each image contains a list of installation packages in the order that they are installed. Default images are provided with the base installation of Control-M Automation API, and you can create additional custom images (for example, for installation of a newer version of the Control-M/Server). To prepare for provisioning, you must obtain the installation packages that are referenced within the images. You can also (optionally) customize the location in which to save these packages (for example, you might want to save the packages in a JFrog Artifactory repository, in Amazon S3 Buckets, or in your local file system). For more information about these preparatory tasks, see the Control-M Administrator Guide in the Control-M Online Help.

Note

Image-related commands are used to manage images of both Control-M/Agents and Control-M/Servers. For details of these commands see their descriptions above:

provision server::setup  

Installs a Control-M/Server and registers it in the Control-M environment.

CLI Syntax

CLI
ctm provision server::setup -f <configuration file>

Where:

Parameter

Description

<configuration file>

JSON file that contains Control-M/Server definitions.

For the full description of this configuration file, see Server Provisioning configuration.

provision server::install

Combines the image and the setup commands into one action. Downloads the Control-M/Server, installs it, and registers it in the Control-M environment.

CLI Syntax

ctm provision server::install <image> -f <configuration file>

Where:

Parameter

Description

<image>

The image that you want to install (one of the images returned by the provision images command)

<configuration file>

JSON file that contains Control-M/Server definitions.

For the full description of this configuration file, see Server Provisioning configuration.

provision server::uninstall

Uninstalls a Control-M/Server from this user account and unregisters it from the Control-M environment.

CLI Syntax

ctm provision server::uninstall [ctm]

Where:

Parameter

Description

ctm

For a Linux machine that has multiple Control-M/Servers installed: Name of the Control-M/Server

Back to top


Was this page helpful? Yes No Submitting... Thank you

Comments