Config service
The config service allows you to configure the Control-M environment:
- Configuring the major components of the Control-M environment
- Configuring Authorizations
- Configuring Job Archiving
- Configuring file transfers to and from remote hosts
- Configuring file transfers to and from external users
- Configuring Secrets
Configuring the major components of the Control-M environment
Using the Config service, you can access, update, and add configuration data for the major components of the Control-M environment. For example, you can list available Control-M/Servers, add Control-M/Agents, manage remote hosts and host groups, manage "run as" users, and set several Control-M/EM parameters.
config server::add
Add a Control-M/Server to a Control-M environment (the Control-M/Server will be registered on the Control-M/Enterprise Manager).
To verify the Control-M/Server is up and running, run the config servers::get command to check the status of the Control-M/Server.
ctm config server::add <host> <ctm> <id> [port]
Where:
Parameter | Description |
---|---|
<host> | Control-M/Server host name |
<ctm> | Control-M/Server name |
<id> | Defines a unique 3-character code to identify the Control-M/Server |
[port] | (Optional) Control-M/Server port Default: 2369 Valid range:
|
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.
Example using curl:
host=`hostname`
id=123
ctm=myserver
port=2369
curl -X POST $endpoint/config/server -H 'Authorization: Bearer &token'
-H 'Content-Type: application/json' -d '{"host": "$host","id": "$id","ctm": "$ctm","port": $port}'
config server::delete
Deletes a Control-M/Server from the Control-M environment (the Control-M/Server will be un-registered from the Control-M/Enterprise Manager).
ctm config server::delete <server>
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.
Example using curl:
endpoint=https://<controlm>:8443/automation-api
token=
server=
curl -X DELETE -H "Authorization: Bearer $token" "$endpoint/config/server/$$server"
config servers::get
Returns a list of Control-M/Servers.
CLI Syntax
ctm config servers::get
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" "$endpoint/config/servers"
Response
The following example shows the parameters in the config servers::get response. In this example, the operational state of the Control-M/Server is up and connected.
{
"name": "controlm",
"host": "myhost",
"state": "Up",
"message": "Connected",
"version": "9.0.20.000"
}
Where:
Parameter | Description |
---|---|
name | Control-M/Server name |
host | Control-M/Server host name |
state | Determines the state of the Control-M/Server Options:
|
message | Description of the state or error message. Possible values: Connected, Disconnected, "", error message |
config server::failover
The failover command enables you to perform a manual failover of a Control-M/Server to a secondary host, provided that High Avilability (HA) is set up for this server.
For more information, see the section about High Availability in the Control-M Administrator Guide in the Control-M Online Help.
CLI Syntax
ctm config server::failover <server>
Where <server> is the name of the Control-M/Server.
If annotation is enabled for the High availability 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.
Example using curl:
server=controlm
curl -H "Authorization: Bearer $token" -X PUT "$endpoint/config/server/$server/failover"
config server::setasprimary
The setasprimary command enables you to set a secondary server as the primary Control-M/Server.
Use this command only after performing a successful manual failover on the server that functioned as the primary server until now. You must have High Availability (HA) set up for these servers.
For more information, see the section about High Availability in the Control-M Administrator Guide in the Control-M Online Help.
CLI Syntax
ctm config server::setasprimary <server>
Where <server> is the name of the Control-M/Server.
If annotation is enabled for the High availability 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.
Example using curl:
server=controlm
curl -H "Authorization: Bearer $token" -X PUT "$endpoint/config/server/$server/setasprimary"
config server:remotehost::add
The remotehost add command enables you to add a remote host to a Control-M/Server.
CLI Syntax
ctm config server:remotehost::add <server> <remotehost> [port] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<server> | Name of the Control-M/Server |
<remotehost> | Name of host or alias of the remote host |
[port] | (Optional) SSH port number. Default value: 22 |
[configuration file] | (Optional) JSON file that contains additional parameters. |
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.
The following is a list of the additional parameters that can be used in the configuration file:
{
"remotehost" : "xx",
"port" : 22,
"agents": [
"<local>"
],
"encryptAlgorithm": "BLOWFISH",
"compression": "false",
"authorize": "true"
}
Where:
Parameter | Description |
---|---|
agents | Control-M/Agents that manage the remote host. If not defined, the default Control-M/Agent will be used. Default: local |
port | Default: 22 |
encryptAlgorithm | Encryption algorithm type used to encrypt data between the Control-M/Agent and the remote host. The options are:
Default: BLOWFISH |
compression | true | false Default: false |
authorize | Enables you to add the machine to the SSH remote host authorization list. If true, you will not be prompted to connect at each attempted connection. true | false Default: true |
REST API Syntax
See REST API reference.
Example using curl:
server=controlm
remotehost=myhost
agent=realAgent
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST
-d "{\"agents\": [ \"$agent\" ], \"compression\": true, \"encryptAlgorithm\": \"BLOWFISH\"}"
"$endpoint/config/server/$server/remotehost/$remotehost?port=22"
config server:remotehost::authorize
The remotehost authorize command enables you to add the machine to the SSH remote host authorization list (if this was not already done when the machine was added to the Control-M/Server).
CLI Syntax
ctm config server:remotehost::authorize <server> <remotehost>
Where:
Parameter | Description |
---|---|
<server> | Name of the Control-M/Server |
<remotehost> | Name of host or alias of the remote host |
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.
Example using curl:
server=controlm
remotehost=myhost
curl -H "Authorization: Bearer %token%" -H "Content-Type: application/json" -X POST
"%endpoint%/config/server/$server/remotehost/$remotehost/authorize"
config server:remotehost::delete
Deletes a remote host from the Control-M/Server.
CLI Syntax
ctm config server:remotehost::delete <server> <remotehost>
Where:
Parameter | Description |
---|---|
<server> | Name of the Control-M/Server |
<remotehost> | Name of host or alias of the remote host |
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
Example using curl:
server=controlm
remotehost=myhost
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/server/$server/remotehost/$remotehost"
config server:remotehosts::get
Returns a list of all remote hosts registered to the Control-M/Server.
CLI Syntax
ctm config server:remotehosts::get <server>
Where:
Parameter | Description |
---|---|
<server> | Name of the Control-M/Server |
REST API Syntax
Example using curl:
server=controlm
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$server/remotehosts"
config server:remotehost::get
Returns the remote host configuration properties from the Control-M/Server.
CLI Syntax
ctm config server:remotehost::get <server> <remotehost>
Where:
Parameter | Description |
---|---|
<server> | Name of the Control-M/Server |
<remotehost> | Name of host or alias of the remote host |
REST API Syntax
Example using curl:
server=controlm
remotehost=myhost
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$server/remotehost/$remotehost"
config server:agent::add
Adds a Control-M/Agent to a specific Control-M/Server. This allows the Control-M/Server to run jobs on this host where the Agent is installed. Also, it verifies the connectivity between the Control-M/Server and the Control-M/Agent.
CLI Syntax
ctm config server:agent::add <server> <host> <port> [tag] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
<host> | Name of host or alias of the Control-M/Agent. This will be registered in Control-M/Server as the logical name of the Control-M/Agent. |
<port> | Number of port for communiation from Control-M/Server to Control-M/Agent. Valid values are between 1025 and 65535. For example, 7006. |
[tag] | 9.0.20.000 (Optional) A tag associated with the Control-M/Agent, used in Role-Based Administration (RBA) Tags can contain alphanumeric characters, as well as the underscore character, and can be up to 85 characters long. Note:
|
[configuration file] | (Optional) JSON file that contains additional parameters |
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.
The following is a list of the additional parameters that can be used in the configuration file:
{
"persistentConnection": true,
"sslState": "Enabled",
"tag": "abc_12345"
}
Where:
Parameter | Description |
---|---|
persistentConnection | Creates a permanent connection between Control-M/Server and Control-M/Agent for a firewall environment. true | false Default: false |
sslState | 9.0.20.000 The Secure Socket Layer (SSL) status of the Control-M/Agent, one of the following:
Note that this parameter is available only if your Control-M/EM Server is of version 9.0.20 or later. |
tag | 9.0.20.000 Agent tag, as described above |
REST API Syntax
Example using curl:
server=controlm
host=myhost
port=7006
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X POST -d "{\"host\":\"$host\",\"port\":\"$port\",\"tag\":\"abc_12345\",\"sslState\":\"Default\"}"
"$endpoint/config/server/$server/agent"
config server:agent::delete
Deletes a Control-M/Agent from the Control-M/Server database. This removes the Control-M/Agent from a Control-M/Server without shutting the Agent down.
CLI Syntax
ctm config server:agent::delete <server> <agent>
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
<agent> | Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. |
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.
Example using curl:
server=controlm
agent=myhost
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/server/$server/agent/$agent"
config server:agent:params::get
Get system parameters of a Control-M/ Agent registered to a Control-M/Server. Returns a list of Agent-related system parameters. Each entry is a pair which consists of parameter name and value.
CLI Syntax
ctm config server:agent:params::get <server> <agent>
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
<agent> | Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. |
REST API Syntax
See REST API reference.
Example using curl:
server=controlm
agent=host
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$server/agent/$agent/params"
config server:agent:param::set
Set the value of a specific Agent-related system parameter.
CLI Syntax
ctm config server:agent:param::set <server> <agent> <name> <value>
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
<agent> | Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. |
<name> | Name of parameter |
<value> | Value of parameter |
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.
Example using curl:
server=controlm
agent=quickstart
name=LIMIT_LOG_VERSIONS
value=10
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d "{\"value\":\"$value\"}" "$endpoint/config/server/$server/agent/$agent/param/$name"
config server:agent::ping
Checks if the Control-M/Agent is available.
ctm config server:agent::ping <server> <agent> [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
<agent> | Name of Control-M/Agent |
[configuration file] | (Optional) JSON file that contains additional parameters. |
The following is a list of the additional parameters that can be used in the configuration file:
{ "discover": true,"timeout":60}
Where:
Parameter | Description |
---|---|
discover | When true, the Control-M/Agent is added to the Control-M/Server when the ping status is unavailable. true | false Default: false |
timeout | Maximum time (in seconds) to wait for a ping response Default : 60 |
REST API Syntax
See REST API reference.
Example using curl:
server=controlm
agent=quickstart
curl -X POST -H "Authorization: Bearer $token" -H "Content-Type: application/json" -d "{\"discover\": false, \"timeout\":60}" "$endpoint/config/server/$server/agent/$agent/ping"
config server:agents::get
Returns a list of all Control-M/Agents registered to the Control-M/Server, along with basic details about each agent. You can optionally filter the list for Agents that match a specific pattern.
CLI Syntax
ctm config server:agents::get <server> ["<agent_pattern>"]
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
<agent_pattern> | (Optional) Filter the list to include only agents that match a specified pattern. As wildcards, use asterisks (*). For example: |
REST API Syntax
See REST API reference.
Example using curl:
server=controlm
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$server/agents?agent=Agent*1*"
Response
For each agent, the following details are provided: node ID, status (Available, Unavailable, Disabled, or Discovering), product version, and host operating system. The following example shows the details returned for each agent:
{
"agents": [
{
"nodeid": "myAgent",
"status": "Available",
"version": "9.0.20.000",
"operatingSystem": "Microsoft Windows Server 2016 (Build 14393)"
}
]
}
config server:agent::disable
Disables Control-M/Agent from Control-M/Server. New jobs cannot run on the Control-M/Agent.
CLI Syntax
ctm config server:agent::disable <server> <agent>
Where:
Parameter | Description |
---|---|
server | Name of Control-M/Server |
agent | Name of Control-M/Agent |
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.
Example using curl:
curl -X POST -H "Authorization: Bearer $token" "$endpoint/config/server/$server/agent/$agent/disable"
config server:agent::enable
Enables jobs to run on the Control-M/Agent.
CLI Syntax
ctm config server:agent::enable <server> <agent>
Where:
Parameter | Description |
---|---|
server | Name of Control-M/Server |
agent | Name of Control-M/Agent |
REST API Syntax
See REST API reference.
Example using curl:
curl -X POST -H "Authorization: Bearer $token" "$endpoint/config/server/$server/agent/$agent/enable"
config server:agent:crt:expiration::get
9.0.20.000 Returns the expiration date of an SSL certificate from an SSL-configured Control-M/Agent. The date is returned exactly as it appears in the certificate.
This feature is offered in an environment with Control-M 9.0.20 or later.
For information about using this API command in a script to automate certificate updates, see Automating SSL certificate updates on Control-M/Agents.
CLI Syntax
ctm config server:agent:crt:expiration::get <server> <agent>
Where:
Parameter | Description |
---|---|
server | Name of Control-M/Server |
agent | Name of Control-M/Agent |
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$server/agent/$agent/crt/expiration"
config server:agent:csr::create
9.0.20.000 Creates a Certificate Signing Request (CSR) for an SSL-configured Control-M/Agent.
This feature is offered in an environment with Control-M 9.0.20 or later.
For information about using this API command in a script to automate certificate updates, see Automating SSL certificate updates on Control-M/Agents.
CLI Syntax
ctm config server:agent:csr::create <server> <agent> -f <configuration file>
Where:
Parameter | Description |
---|---|
server | Name of Control-M/Server |
agent | Name of Control-M/Agent |
configuration file | JSON file that contains required parameters for the CSR Here is an example for the content of this file:
For country, use the two-letter code abbreviation of the country where your organization is located. For example, CO is Colombia. Note that the CN property is set automatically by the Agent. Do not include the CN property in this configuration file. |
Tip: To save the CSR output (a block of encoded text) in a file, you can append the following to the end of the CLI command: > fileName
REST API Syntax
See REST API reference.
Example using curl:
curl -X POST -H "Authorization: Bearer $token" -H "Content-Type: application/json"
--data "@examples\configuration.json" "$endpoint/config/server/$server/agent/$agent/csr"
Tip: To save the output in a CSR file, you can append the following to the end of the command:
-o $file_path$file_name
config server:agent:crt::deploy
9.0.20.000 Deploy a signed certificate to an SSL-configured Control-M/Agent. The new certificate that you deploy replaces the existing certificate.
Note: For the new certificate to take effect after the deployment, recycle the Control-M/Agent. If the new certificate was signed by a new CA, ensure that this CA is recognized also by the Control-M/Server.
This feature is offered in an environment with Control-M 9.0.20 or later.
For information about using this API command in a script to automate certificate updates, see Automating SSL certificate updates on Control-M/Agents.
CLI Syntax
ctm config server:agent:crt::deploy <server> <agent> <crt_filepath> <ca_chain_filepath>
Where:
Parameter | Description |
---|---|
server | Name of Control-M/Server |
agent | Name of Control-M/Agent |
crt_filepath | Full path to the certificate file |
ca_chain_filepath | Full path to the Certificate Authority (CA) chain file |
REST API Syntax
See REST API reference.
Example using curl:
curl -X POST -H "Authorization: Bearer $token" -F "crtFile=@examples/crt.pem"
-F "caChainFile=@examples/ca_chain.pem" "$endpoint/config/server/$server/agent/$agent/crt"
config server:hostgroups::get
Returns a list of host groups defined in the Control-M/Server. Each entry is a host group name.
CLI Syntax
ctm config server:hostgroups::get <server>
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
REST API Syntax
See REST API reference.
Example using curl:
server=controlm
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$server/hostgroups"
config server:hostgroup::update
Updates the list of Control-M/Agents that are in a host group, overwriting the current list of Control-M/Agents. If the specified host group does not exist, a new host group is created.
This API command is especially useful if you want to add or remove multiple agents in a host group, all at once, or to create a new host group with multiple associated agents.
CLI Syntax
ctm config server:hostgroup::update <server> <hostgroup> -f <configuration file>
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
<hostgroup> | Name of host group |
<configuration file> | JSON file that contains definitions of Control-M/Agents within the host group The configuration file must contain definitions of at least one agent. Tip: As your starting point, you can use config server:hostgroup:agents::get to obtain a list of all defined agents in a host group. Ensure that you edit the output from that command to match the required format described below. |
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.
The following sample configuration file defines (or updates) three agents in the host group:
{
"agentslist": [
{
"host": "agent1",
"hostgroupAgentParticipation": {
"event": "eventString",
"orderDate": "AnyDate"
}
},
{
"host": " agent2",
"hostgroupAgentParticipation": null
},
{
"host": " agent3”
}
]
}
The following parameters are available for each Control-M/Agent defined in the configuration file:
Parameter | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
host | (Required) Name of host or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. | ||||||||||
hostgroupAgentParticipation | (Optional) Only if a specified event occurs, the host will be part of host group | ||||||||||
event | Name of an event | ||||||||||
orderDate | The work day on which to schedule the requested action. Possible values:
|
REST API Syntax
See REST API reference.
Example using curl, with one agent defined in the host group:
server=myServer
hostgroup=myHostGroup
curl -H "x-api-token: $token" -H "Content-Type: application/json" -X POST
-d "{\"agentslist\": [{\"host\": \"$host\",
\"hostgroupAgentParticipation\": {\"event\": \" eventString\", \"orderDate\": \"AnyDate\"}}]}"
"$endpoint/config/server/$server/hostgroup/$hostgroup"
config server:hostgroup::delete
Deletes a specified host group from the Control-M/Server.
CLI Syntax
ctm config server:hostgroup::delete <server> <hostgroup>
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
<hostgroup> | Name of host group |
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.
Example using curl:
server=myServer
hostgroup=myHostGroup
curl -H "x-api-token: $token" -X DELETE "$endpoint/config/server/$server/hostgroup/$hostgroup"
config server:hostgroup:agents::get
Returns a list of agents of a host group. Each entry is the logical name of an Agent.
CLI Syntax
ctm config server:hostgroup:agents::get <server> <hostgroup>
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
<hostgroup> | Name of host group |
REST API Syntax
See REST API reference.
Example using curl:
server=controlm
hostgroup=HostGroup1
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$server/hostgroup/$hostgroup/agents"
config server:hostgroup:agent::add
Adds a Control-M/Agent to a host group and creates the host group if it does not exist.
CLI Syntax
ctm config server:hostgroup:agent::add <server> <hostgroup> <host> [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
<hostgroup> | Name of host group |
<host> | Name of host or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. |
[configuration file] | (Optional) JSON file that contains additional parameters |
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.
The following is a list of the additional parameters that can be used in the configuration file:
{
"host":"agent3",
"hostgroupAgentParticipation":{
"event":"agent3Cond",
"orderDate":"AnyDate"
}
}
Where:
Parameter | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
host | Name of host or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. | ||||||||||
hostgroupAgentParticipation | Only if event occurs, the host will be part of host group | ||||||||||
event | Name of an event | ||||||||||
orderDate | The work day on which to schedule the requested action. Possible values:
|
REST API Syntax
See REST API reference.
Example using curl:
server=controlm
hostgroup=mygroup
host=myhost
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d "{\"host\": \"$host\", \"hostgroupAgentParticipation\":{ \"event\": \"agent3Cond\", \"orderDate\": \"AnyDate\"}}" "$endpoint/config/server/$server/hostgroup/$hostgroup/agent"
config server:hostgroup:agent::delete
Removes a Control-M/Agent from a hostgroup. If the group is empty after the deletion, it is also deleted.
CLI Syntax
ctm config server:hostgroup:agent::delete <server> <hostgroup> <host>
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
<hostgroup> | Name of host group |
<host> | Name of host or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. |
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.
Example using curl:
server=controlm
hostgroup=mygroup
host=myhost
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/server/$server/hostgroup/$hostgroup/agent/$host"
config server:runasuser::add
Adds a new user to the list of users that are available for running jobs on an Agent. Whenever you define a job, you can choose a "run as" user from the list of predefined users.
Tips
Before adding a new "run as" user, you might want to use the config server:runasuser::test command to test the connection to the user and verify the authentication details that you defined in your configuration file.
The following video demonstrates how to manage "run as" users: https://youtu.be/Xfv-2UStyBE
CLI Syntax
ctm config server:runasuser::add <server> <agent> <user> [password] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<server> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent, or "All" for all agents |
<user> | Name of user |
[password] | A valid password for the specified user Note: You can instead specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence. |
[configuration file] | Full path to a JSON file that contains authentication details for the "run as" user. You can choose one of the following options: |
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.
Content of configuration file
The following example configuration file contains a password in plain text.
{
"password": "pass1"
}
The following example configuration file contains the name of a predefined secret instead of a password.
{
"password": "Secret:topSecretPassword"
}
The following example configuration file contains key authentication details for an SSH connection. In this example, the passphrase is specified as a predefined secret.
{
"key": {
"keyname": "keyName",
"passphrase": "Secret:topSecretPassphrase"
}
}
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.
server=controlm
curl -H "Authorization: Bearer $token"
-H "Content-Type: application/json" --data "@runasUserDefinition.json"
-X POST "$endpoint/config/server/$server/runasuser"
When using a REST API command to add a "run as" user, the configuration file must contain full user credentials, including the Agent and user name, as shown in the following example. In this example, authentication details are for an SSH connection to a remote host (based on a key and passphrase).
{
"user": "user1",
"agent": "All",
"key": {
"keyname": "keyName",
"passphrase": "passphrase1"
}
}
config server:runasuser::get
Retrieves the details of a specific "run as" user. You can use this command to verify that a certain user exists in the list of defined users. Each "run as" user is uniquely identified by its combination of agent and user name.
CLI Syntax
ctm config server:runasuser::get <server> <agent> <user>
Where:
Parameter | Description |
---|---|
<server> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent, or "All" for all agents |
<user> | Name of user Note: If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. |
REST API Syntax
See REST API reference.
Example using curl:
server=controlm
curl -H "Authorization: Bearer $token"
$endpoint/config/server/$server/runasuser/realAgent/user1
config server:runasuser::update
Updates the authentication parameters of an existing "run as" user. Each "run as" user is uniquely identified by its combination of agent and user name.
Tip
Before updating the "run as" user, you might want to use the server:runasuser::test command to test the connection to the user and verify the validity of the user's authentication details.
CLI Syntax
ctm config server:runasuser::update <server> <agent> <user> [password] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<server> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent, or "All" for all agents |
<user> | Name of user Note: If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. |
[password] | A new valid password for the specified user Note: You can instead specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence. |
<configuration file> | Full path to a JSON file that contains authentication details that you want to update for the "run as" user. You can choose one of the following options:
For example contents of a configuration file, see the description under the runasuser::add command. |
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.
The REST API command specifies the Agent and user, and the configuration file contains only the authentication details (either a password or a key and passphrase). In the following curl example, note that the path to the configuration file is prefixed with an @ character.
server=controlm
curl -H "Authorization: Bearer $token"
-H "Content-Type: application/json" --data "@runasUserDefinition.json"
-X POST "$endpoint/config/server/$server/runasuser/realAgent/user1"
config server:runasuser::delete
Deletes a "run as" user from the list of users that are available for running jobs on an Agent. Each "run as" user is uniquely identified by its combination of agent and user name.
CLI Syntax
ctm config server:runasuser::delete <server> <agent> <user>
Where:
Parameter | Description |
---|---|
<server> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent, or "All" for all agents |
<user> | Name of user Note: If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. |
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.
Example using curl:
server=controlm
curl -H "Authorization: Bearer $token"
-X DELETE $endpoint/config/server/$server/runasuser/realAgent/user1
config server:runasuser::test
Tests the connection for a "run as" user that you specify. You can use this command in the following ways:
- Specify the Agent and user name in the command line, but do not specify authentication credentials. This is especially useful for verifying the validity of the credentials of a defined "run as" user before updating the user's authentication parameters.
- Specify also the password in the command line or specify authentication details in a configuration file. This is especially useful for verifying the validity and connectivity of a user before adding the user to the list of "run as" users.
CLI Syntax
ctm config server:runasuser::test <server> <agent> <user> [password] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<server> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent Note: The "All" value is not supported when testing a "run as" user. |
<user> | Name of user Note: If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. |
[password] | A password to test for the specified user Note: You can instead specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence. |
<configuration file> | Full path to a JSON file that contains authentication details of the "run as" user. For example contents of a configuration file, see the description under the runasuser::add command. |
REST API Syntax
See REST API reference.
Examples using curl:
Example for testing an existing user:
server=controlm curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" --data "{}" -X POST $endpoint/config/server/$server/runasuser/realAgent/user1/test
For this test, a configuration file is not necessary, because authentication details are not required.
Example for testing a user that has not yet been added:
server=controlm curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" --data "@runasUserDefinition.json" -X POST "$endpoint/config/server/$server/runasuser/realAgent/user1/test"
For this test, the REST API command specifies the Agent and user, and the configuration file contains only the authentication details (either a password or a key and passphrase). T he path to the configuration file is prefixed with an @ character.
config server:runasusers::get
Retrieves details about all "run as" users that match a specified search criteria.
CLI Syntax
ctm config server:runasusers::get <server> [-s <query string>]
Where:
Parameter | Description |
---|---|
<server> | Name of the Control-M/Server |
<query string> | A string to search for, with the following format: "field1=criteria1&field2=criteria2" You can include the following fields in the query string:
For example: |
REST API Syntax
See REST API reference.
Example using curl:
server=controlm
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$server/runasusers?agent=agent1&user=user1"
config server:params::get
Returns a list of parameters of a Control-M/Server. The following fields are returned:
- name
- value
- defaultValue
CLI Syntax
ctm config server:params::get <server>
Where:
Parameter | Description |
---|---|
<server> | Name of Control-M/Server |
REST API Syntax
See REST API reference.
Example using curl:
server=controlm
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$server/params"
config em:param::set
Set the value of a Control-M/Enterprise Manager system parameter. Supports only a select group of system parameters. The user can set this value only if they have permissions to that specific environment.
CLI Syntax
ctm config em:param::set <paramName> <value>
Where:
Parameter | Description |
---|---|
<paramName> | The system parameter defined in the Control-M/Enterprise Manager, one of the following supported system parameters:
|
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.
Example using curl:
paramName=api_key
value=true
curl -H "Authorization: Bearer $token" -X POST -d "{\"value\":\"$value\"}" "$endpoint/config/em/param/$paramName"
config item::recycle
9.0.19.120 Recycles a specific Control-M component. Use this command to restart a component to solve server issues. Currently, this command supports only the recycling of Control-M/Agents.
CLI Syntax
ctm config item::recycle <id>
Where:
Parameter | Description |
---|---|
<id> | The ID of the component that you want to recycle. This ID has the following syntax:
The ID is composed of the following elements:
|
REST API Syntax
See REST API reference.
Example using curl:
id="CTMS:Agent:controlm:myAgent"
curl -H "Authorization: Bearer $token" -X POST "$endpoint/config/item/$id/recycle"
Configuring Authorizations
Config authorization enables you to manage the authorizations of users, roles, and LDAP groups, limiting their access to various Control-M entities and actions.
Configuration of authorizations is available in a Control-M environment with Control-M/Enterprise Manager version 9.0.19.000 or later.
The following table summarizes the actions that you can take for each authorization entity:
Role | User | LDAP Group |
---|---|---|
Tip
The following videos demonstrate how to manage authorizations:
https://youtu.be/ooVUsgws570 — Managing roles and authorizations
https://youtu.be/gxZ9coj48M0 — Creating users and assigning roles to users and LDAP groups
config authorization:role::add
Creates a new role based on role settings that you define through a role data file.
CLI Syntax
ctm config authorization:role::add <roleFile>
Where <roleFile> is the full path and name of a .json payload file that contains role definitions, as described in Role data for authorization configuration.
If annotation is enabled for the Account 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.
Example using curl:
curl -H "Authorization: Bearer $token" -F "roleFile=@roleDefinition.json"
-X POST $endpoint/config/authorization/role
config authorization:role::get
Retrieves the details of an existing role, as defined in the role data file.
Note: Only parameters that are set to non-default values are retrieved and displayed in the output.
CLI Syntax
ctm config authorization:role::get <role>
Where <role> is the name of the role.
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
curl -H "Authorization: Bearer $token"
"$endpoint/config/authorization/role/$roleName"
config authorization:role::update
Updates the definitions of an existing role based on role settings that you define through a role data file.
Note
Besides applying all settings that are explicitly defined in the role data file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:
- Obtain ALL current role settings by running the config authorization:role::get command.
- Use the output from the previous step to create your role data file, a .json file.
- In the role data file, change the specific settings that you want to update, and keep all other content in the file.
For full details about all role settings, see Role data for authorization configuration. - Proceed with running the Update command.
CLI Syntax
ctm config authorization:role::update <role> <roleFile>
Where:
Parameter | Description |
---|---|
<role> | Name of the role that you want to update |
<roleFile> | Full path and name of a .json payload file that contains role definitions, as described in Role data for authorization configuration |
If annotation is enabled for the Account 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.
Example using curl:
roleName=myRole
curl -H "Authorization: Bearer $token" -F "roleFile=@roleDefinition.json"
-X POST "$endpoint/config/authorization/role/$roleName"
config authorization:role::delete
Deletes an existing role and disassociates all users who were associated with the role.
CLI Syntax
ctm config authorization:role::delete <role>
Where <role> is the name of the role.
If annotation is enabled for the Account 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.
Example using curl:
roleName=myRole
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/authorization/role/$roleName"
config authorization:roles::get
Retrieves a list of names of configured roles.
CLI Syntax
ctm config authorization:roles::get [-s <search query>]
The optional -s switch can be used to filter for roles by role name or description (or both). The format for the query string is "field1=criteria1&field2=criteria2", according to the following guidelines:
Fields | Criteria | Examples |
---|---|---|
|
|
|
If you include multiple fields in the query, separate them with an ampersand (&). |
REST API Syntax
See REST API reference.
Example using curl:
roleName=Adm*
curl -H "Authorization: Bearer $token"
$endpoint/config/authorization/roles?role=$roleName
config authorization:user::add
Creates a new user based on user settings that you define through a user data file.
CLI Syntax
ctm config authorization:user::add <userFile>
Where <userFile> is the full path and name of a .json payload file that contains user definitions, as described in User data for authorization configuration .
If annotation is enabled for the Account 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.
Example using curl:
curl -H "Authorization: Bearer $token" -F "userFile=@userDefinition.json"
-X POST $endpoint/config/authorization/user
config authorization:user::get
Retrieves the details of an existing user, as defined in the user data file.
Note:
- Only parameters that are set to non-default values are retrieved and displayed in the output.
- For security reasons, the user's password is returned as KEEP_EXISTING. When you use the output from this command to prepare a user data file (a .json file) for the Update command, you can keep this value in the user data file.
CLI Syntax
ctm config authorization:user::get <user>
Where <user> is the name of the user.
REST API Syntax
See REST API reference.
Example using curl:
userName=myUser
curl -H "Authorization: Bearer $token"
"$endpoint/config/authorization/user/$userName"
config authorization:user::update
Updates the definitions of an existing user based on user settings that you define through a user data file.
Note
Besides applying all settings that are explicitly defined in the user data file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:
- Obtain ALL current user settings by running the config authorization:user::get command.
- Use the output from the previous step to create your user data file, a .json file.
- In the user data file, change the specific settings that you want to update, and keep all other content in the file.
For full details about all user settings, see User data for authorization configuration. - Proceed with running the Update command.
CLI Syntax
ctm config authorization:user::update <user> <userFile>
Where:
Parameter | Description |
---|---|
<user> | Name of the user that you want to update |
<userFile> | Full path and name of a .json payload file that contains user definitions, as described in User data for authorization configuration |
If annotation is enabled for the Account 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.
Example using curl:
userName=myuser
curl -H "Authorization: Bearer $token" -F "userFile=@userDefinition.json"
-X POST "$endpoint/config/authorization/user/$userName"
config authorization:user::delete
Deletes an existing user and disassociates it from all roles with which it was associated.
CLI Syntax
ctm config authorization:user::delete <user>
Where <user> is the name of the user.
If annotation is enabled for the Account 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.
Example using curl:
userName=myuser
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/authorization/user/$userName"
config authorization:users::get
Retrieves a list of names of configured users.
CLI Syntax
ctm config authorization:users::get [-s <search query>]
The optional -s switch can be used to filter for users by user name, full name of user, or description (or any combination of these fields). The format for the query string is "field1=criteria1&field2=criteria2", according to the following guidelines:
Fields | Criteria | Examples |
---|---|---|
|
|
|
If you include multiple fields in the query, separate them with an ampersand (&). |
REST API Syntax
See REST API reference.
Example using curl:
userName=emuser*
curl -H "Authorization: Bearer $token"
$endpoint/config/authorization/users?name=$userName
config authorization:user:role::add
Assigns a role to a user.
CLI Syntax
ctm config authorization:user:role::add <user> <role>
Where:
Parameter | Description |
---|---|
<user> | Name of user |
<role> | Name of role |
REST API Syntax
See REST API reference.
Example using curl:
userName=myuser
roleName=myRole
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X POST "$endpoint/config/authorization/user/$userName/role/$roleName"
config authorization:user:role::delete
Removes a role from a user.
CLI Syntax
ctm config authorization:user:role::delete <user> <role>
Where:
Parameter | Description |
---|---|
<user> | Name of user |
<role> | Name of role |
REST API Syntax
See REST API reference.
Example using curl:
userName=myuser
roleName=myRole
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X DELETE "$endpoint/config/authorization/user/$userName/role/$roleName"
config user:password::adminUpdate
Changes the password for a user.
CLI Syntax
ctm config user:password::adminUpdate <user> [newPassword] [-p]
Where:
Parameter | Description |
---|---|
<user> | Name of user whose password you want to change |
[newPassword] | A new password for the user, either of the following:
|
The newPassword parameter is optional because you can, alternatively, use the -p
(or -prompt
) option through the CLI. With this option, you do not need to enter the password in the command. Instead, you are prompted for the password (twice) after you enter the command. Note that if you use both the newPassword parameter and the -p
option, the password that you enter through the command prompt overrides the password that you specify in the command.
REST API Syntax
See REST API reference.
When using a REST API command, you must provide the password (or secret) in a payload .json file. In the following curl example, note that the path to the payload file is prefixed with an @ character.
userName=myuser
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-d "@c:\tmp\data.json" -X POST "$endpoint/config/user/$userName/password/adminUpdate"
Here is an example of the contents of a payload .json file, with the password specified as a predefined secret :
{
"newPassword":"Secret:secretKey"
}
config authorization:ldap:role::add
Adds a role to an LDAP group, so that any user in the LDAP group will inherit the permissions and authorizations defined for the role.
CLI Syntax
ctm config authorization:ldap:role::add <ldapGroup> <role>
Where:
Parameter | Description |
---|---|
<ldapGroup> | Name of LDAP group |
<role> | Name of role |
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
ldapGroup=myGroup
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X POST "$endpoint/config/authorization/ldap/$ldapGroup/role/$roleName"
config authorization:ldap:role::delete
Deletes a role from an LDAP group.
CLI Syntax
ctm config authorization:ldap:role::delete <ldapGroup> <role>
Where:
Parameter | Description |
---|---|
<ldapGroup> | Name of LDAP group |
<role> | Name of role |
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
ldapGroup=myGroup
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X DELETE "$endpoint/config/authorization/ldap/$ldapGroup/role/$roleName"
config authorization:ldap:roles::get
Retrieves a list of roles that are associated with a specific LDAP group.
CLI Syntax
ctm config authorization:ldap:roles::get <ldapGroup> [-s "role=<query pattern>"]
Where:
Parameter | Description |
---|---|
<ldapGroup> | Name of LDAP group |
<query pattern> | (Optional) A pattern for filtering role names. The pattern contains a wildcard (* or ?). For multiple patterns in the same query, use commas. |
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
ldapGroup=myGroup
curl -H "Authorization: Bearer $token"
$endpoint/config/authorization/ldap/$ldapGroup/roles?role=$roleName
config authorization:role:associates
Retrieves a list of all users and LDAP groups to which a specific role is associated.
CLI Syntax
ctm config authorization:role:associates <role>
Where <role> is the name of the role.
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
curl -H "Authorization: Bearer $token"
$endpoint/config/authorization/role/$roleName/associates
Configuring Job Archiving
9.0.20.000 Config archive enables you to manage the setup of Job Archiving, as provided by the Control-M Workload Archiving add-on. Config archive enables you to manage the rules in Workload Archiving policies, as well as to delete accumulated data from the Workload Archiving server. This feature is offered in an environment with Control-M 9.0.20 or later.
For information about searching and retrieving archived data after performing the setup, see Archive service.
config archive:rules::get
Retrieves details of all defined Workload Archiving policy rules.
The output is returned in JSON format. You can use this output as a template for your own Archive Rule files when creating new rules or editing existing rules. For more information about the syntax of Workload Archiving policy rules, see Job Archiving configuration.
CLI Syntax
ctm config archive:rules::get
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" $endpoint/config/archive/rules
config archive:statistics::get
Retrieves statistics regarding job archiving for all defined Workload Archiving policy rules.
CLI Syntax
ctm config archive:statistics::get
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" $endpoint/config/archive/statistics
Response
The following example shows the job archiving statistics that are returned when only one rule is defined:
{
"rulesStatisticList": {
"ruleStatistics": [
{
"ruleName": "Collect all DS jobs",
"retention": 1,
"retentionType": "Year",
"oldestItem": "2019-01-28 12:29:01 PM",
"newestItem": "2019-02-08 07:00:11 AM",
"totalJobs": 30,
"dataSize": "1 MB"
}
]
},
"summary": {
"totalNumberOfJobs": 30,
"totalDataSize": "1 MB",
"actualDbSize": "9 MB",
"diskUsage": "37%"
}
}
config archive:rule::add
Creates a new Workload Archiving policy rule based on rule settings that you define through an Archive Rule file.
CLI Syntax
ctm config archive:rule::add -f <archiveRule>
Where <archiveRule> is the full path and name of a .json payload file that contains definitions for the rule, as described in Job Archiving configuration.
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.
Example using curl:
curl -H "Authorization: Bearer $token"
-X POST -H "Content-Type: application/json"
-d @ruleDefinition.json "$endpoint/config/archive/rule"
config archive:rule::update
Updates the definitions of an existing Workload Archiving policy rule based on rule settings that you define through an Archive Rule file.
Tip
To help you author your Archive Rule file, you can use the output for a specific rule from the config archive:rules::get command as your template. You can edit or remove lines, as applicable. However, ensure that the name
property appears with the correct rule name. For full details about all rule settings, see Job Archiving configuration.
CLI Syntax
ctm config archive:rule::update <ruleName> [-f <archiveRule>]
Where:
Parameter | Description |
---|---|
<ruleName> | Name of the archiving policy rule that you want to update |
<archiveRule> | Full path and name of a .json payload file that contains definitions for the rule, as described in Job Archiving configuration |
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.
Example using curl:
ruleName=rule5
curl -H "Authorization: Bearer $token"
-X POST -H "Content-Type: application/json"
-d @ruleDefinition.json "$endpoint/config/archive/rule/$ruleName"
config archive:rule::delete
Deletes an existing Workload Archiving policy rule.
CLI Syntax
ctm config archive:rule::delete <ruleName> <deleteRuleDataFlag>
Where:
Parameter | Description |
---|---|
<ruleName> | Name of the archiving policy rule that you want to update |
<deleteRuleDataFlag> | The scope of deletion, one of the following values:
|
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.
Example using curl:
ruleName=rule5
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/archive/rule/$ruleName?deleteRuleDataFlag=deleteRuleWithoutData"
config archive::cleanup
Enables you to delete job data (including job output and job logs) that has accumulated in the Workload Archiving server, based on search criteria that you specify.
CLI Syntax
ctm config archive::cleanup -s <search query>
-s is used to run a search using the query string format "field1=criteria1&field2=criteria2&field3=criteria3".
The following fields are available for use in the search query:
Field | Criteria guidelines |
---|---|
|
Note: The server field was previously named ctm (deprecated name). |
|
|
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.
Example using curl:
curl -H "Authorization: Bearer $token" -X DELETE
"$endpoint/config/archive/cleanup?jobname=jobA*&jobnameExceptions=jobABC*&application=B*"
Configuring file transfers to and from remote hosts
9.0.20.035 A group of commands that begin with config server:agent:mft
enable you to manage the setup of your integration with Control-M Managed File Transfer (MFT), to enable file transfers to, from, and between remote hosts.
Using Automation API commands, you can configure the following aspects of Control-M MFT:
- SSH settings — generate SSH keys, authorize an SSH host, or authorize an SSH cluster
- PGP templates — add, update, or delete a PGP template, or retrieve details of PGP templates
- z/OS templates — add, update, or delete a z/OS template, or retrieve details of z/OS templates
- MFT configuration — retrieve details of MFT configuration and update MFT configuration
- File Transfer Server (FTS) settings — retrieve details of FTS settings and update FTS settings
config server:agent:mft:ssh:key::generate
Generates an SSH key pair (private and public keys) in the MFT client and returns the public key. This enables the SFTP client to authenticate itself to the SFTP server instead of using a password.
After the keys are generated, you need to send the public key to the SFTP server administrator to activate public key authentication.
CLI Syntax
ctm config server:agent:mft:ssh:key::generate <server> <agent> <keyName> <keyPassphrase> [keySize]
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
<keyName> | A name for the private and public keys. |
<keyPassphrase> | A password for the private key file. |
[keySize] | (Optional) A maximum size for the key, in bits The default key size is 2048 bits. |
REST API Syntax
See REST API reference.
Example using curl:
server=myInstance
agent=myAgent
curl -H "x-api-key: $token" -X POST
"$endpoint/config/server/$server/agent/$agent/mft/ssh/key?keyName=MyKey1&keyPassphrase=123456"
config server:agent:mft:ssh:host::authorize
Authorizes an SSH host by adding or updating its fingerprint in the local known_hosts file.
CLI Syntax
ctm config server:agent:mft:ssh:host::authorize <server> <agent> <hostname> [port]
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
<hostName> | Name of the SSH host |
[port] | (Optional) Port number of the SSH host The defalt port is 22. |
REST API Syntax
See REST API reference.
Example using curl:
server=myInstance
agent=myAgent
hostname=myGreatHost
curl -H "x-api-key: $token" -X POST "$endpoint/config/server/$server/agent/$agent/mft/ssh/host/$hostname?port=7999"
config server:agent:mft:ssh:cluster::authorize
Authorizes an SSH cluster by adding or updating fingerprints for its nodes in the local known_hosts file.
CLI Syntax
ctm config server:agent:mft:ssh:cluster::authorize <server> <agent> <clusterName> -f nodePortDefinitions.json
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
<clusterName> | Name of the SSH cluster |
nodePortDefinitions | Full path and name of a .json payload file that contains node and port definitions for the SSH hosts in the cluster. Here is an example of the contents of such a Definitions file:
|
REST API Syntax
See REST API reference.
Example using curl:
server=myInstance
agent=myAgent
clusterName=myGreatCluster
curl -H "x-api-key: $token" -X POST "$endpoint/config/server/$server/agent/$agent/mft/ssh/cluster/$clusterName"
--data "nodePortDefinitions.json"
config server:agent:mft:pgptemplate::add
Creates a new PGP template, which enables you to define PGP commands for file transfers. PGP commands enable you to use PGP applications to encrypt files on a local computer before a transfer and decrypt files on a local computer after a transfer.
CLI Syntax
ctm config server:agent:mft:pgptemplate::add <server> <agent> <templateName> -f pgptemplateData.json
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
<templateName> | Name of the PGP template |
pgptemplateData | Full path and name of a .json payload file that contains definitions of the PGP template, as described in PGP Template Data file in Configuration reference for file transfers to or from remote hosts. |
REST API Syntax
See REST API reference.
Example using curl:
server=myInstance
agent=myAgent
templateName=pgpTemplate1
curl -H "x-api-key: $token" -X POST "$endpoint/config/server/$server/agent/$agent/mft/pgptemplate/$templateName"
--data "pgptemplateData.json"
config server:agent:mft:pgptemplate::update
Updates an existing PGP template based on template definitions that you provide through a .json file. PGP templates enables you to define PGP commands for encyrption and dycription of files involved in file transfers.
Note
Besides applying all settings that are explicitly defined in the PGP Template Data file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:
- Obtain ALL current settings of the template by running the config server:agent:mft:pgptemplates::get command.
- Use the current definitions of the relevant template (from the output of the previous step) to create your PGP Template Data file, a .json file.
- In the PGP Template Data file, change the specific settings that you want to update, and keep all other content in the file.
For full details about all template definitions, see PGP Template Data file in Configuration reference for file transfers to or from remote hosts. - Proceed with running the Update command.
CLI Syntax
ctm config server:agent:mft:pgptemplate::update <server> <agent> <templateName> -f pgptemplateData.json
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
<templateName> | Name of the PGP template |
pgptemplateData | Full path and name of a .json payload file that contains definitions of the PGP template, as described in PGP Template Data file in Configuration reference for file transfers to or from remote hosts. |
REST API Syntax
See REST API reference.
Example using curl:
server=myInstance
agent=myAgent
templateName=pgpTemplate1
curl -H "x-api-key: $token" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/pgptemplate/$templateName"
--data "pgptemplateData.json"
config server:agent:mft:pgptemplate::delete
Deletes an existing PGP template in Control-M MFT.
CLI Syntax
ctm config server:agent:mft:pgptemplate::delete <server> <agent> <templateName>
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
<templateName> | Name of the PGP template |
REST API Syntax
See REST API reference.
Example using curl:
server=myInstance
agent=myAgent
templateName=pgpTemplate1
curl -H "x-api-key: $token" -X DELETE "$endpoint/config/server/$server/agent/$agent/mft/pgptemplate/$templateName"
config server:agent:mft:pgptemplates::get
Retrieves details of defined PGP templates in Control-M MFT.
The output is returned in JSON format. You can use this output as the starting point for creating your own PGP Template Data files when creating new PGP templates or editing existing PGP templates. For more information about the syntax of definitions, see PGP Template Data file in Configuration reference for file transfers to or from remote hosts.
CLI Syntax
ctm config server:agent:mft:pgptemplates::get <server> <agent> [-s "name=<pattern>"]
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
In addition, the optional -s runs a search and filters the output based on template name. For multiple values, use wildcards (* or ?) or commas.
For example: -s "name=a*"
REST API Syntax
See REST API reference.
Examples using curl, one without a filter and one with a filter:
curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/pgptemplates"
curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/pgptemplates?name=a*"
config server:agent:mft:zostemplate::add
Creates a new z/OS template for z/OS file transfers.
CLI Syntax
ctm config server:agent:mft:zostemplate::add <server> <agent> <templateName> -f zosTemplateData.json
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
<templateName> | Name of the z/OS template |
zosTemplateData | Full path and name of a .json payload file that contains definitions of the z/OS template, as described in z/OS Template Data file in Configuration reference for file transfers to or from remote hosts. |
REST API Syntax
See REST API reference.
Example using curl:
server=myInstance
agent=myAgent
templateName=zosTemplate1
curl -H "x-api-key: $token" -X POST "$endpoint/config/server/$server/agent/$agent/mft/zostemplate/$templateName"
--data "zosTemplateData.json"
config server:agent:mft:zostemplate::update
Updates an existing z/OS template based on template definitions that you provide through a .json file. z/OS templates are used for z/OS file transfers.
Note
Besides applying all settings that are explicitly defined in the z/OS Template Data file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:
- Obtain ALL current settings of the template by running the config server:agent:mft:zostemplates::get command.
- Use the current definitions of the relevant template (from the output of the previous step) to create your z/OS Template Data file, a .json file.
- In the z/OS Template Data file, change the specific settings that you want to update, and keep all other content in the file.
For full details about all template definitions, see z/OS Template Data file in Configuration reference for file transfers to or from remote hosts. - Proceed with running the Update command.
CLI Syntax
ctm config server:agent:mft:zostemplate::update <server> <agent> <templateName> -f zosTemplateData.json
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
<templateName> | Name of the z/OS template |
zosTemplateData | Full path and name of a .json payload file that contains definitions of the z/OS template, as described in z/OS Template Data file in Configuration reference for file transfers to or from remote hosts. |
REST API Syntax
See REST API reference.
Example using curl:
server=myInstance
agent=myAgent
templateName=zosTemplate1
curl -H "x-api-key: $token" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/zostemplate/$templateName"
--data "zosTemplateData.json"
config server:agent:mft:zostemplate::delete
Deletes an existing z/OS template in Control-M MFT.
CLI Syntax
ctm config server:agent:mft:zostemplate::delete <server> <agent> <templateName>
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
<templateName> | Name of the z/OS template |
REST API Syntax
See REST API reference.
Example using curl:
server=myInstance
agent=myAgent
templateName=zosTemplate1
curl -H "x-api-key: $token" -X DELETE "$endpoint/config/server/$server/agent/$agent/mft/zostemplate/$templateName"
config server:agent:mft:zostemplates::get
Retrieves details of defined z/OS templates in Control-M MFT.
The output is returned in JSON format. You can use this output as the starting point for creating your own z/OS Template Data files when creating new z/OS templates or editing existing z/OS templates. For more information about the syntax of definitions, see z/OS Template Data file in Configuration reference for file transfers to or from remote hosts.
CLI Syntax
ctm config server:agent:mft:zostemplates::get <server> <agent> [-s "name=<pattern>"]
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
In addition, the optional -s runs a search and filters the output based on template name. For multiple values, use wildcards (* or ?) or commas.
For example: -s "name=a*"
REST API Syntax
See REST API reference.
Examples using curl, one without a filter and one with a filter:
curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/zostemplates"
curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/zostemplates?name=a*"
config server:agent:mft:configuration::get
Retrieves details of MFT configuration.
The output is returned in JSON format. You can use this output as the starting point for updating MFT configuration. For more information about the various details returned in the output JSON, see MFT Configuration Data file in Configuration reference for file transfers to or from remote hosts.
CLI Syntax
ctm config server:agent:mft:configuration::get <server> <agent>
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
REST API Syntax
See REST API reference.
Example using curl:
curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/configuration"
config server:agent:mft:configuration::update
Update MFT configuration properties based on configuration that you provide through a .json file.
Note
In your MFT Configuration Data file, you can choose to include only those properties that you want to update. Any MFT settings that are not included in your MFT Configuration Data file are not updated and remain untouched.
For full details about all MFT configurtion settings, as returned by the config server:agent:mft:configuration::get command, see MFT Configuration Data file in Configuration reference for file transfers to or from remote hosts.
CLI Syntax
ctm config server:agent:mft:configuration::update <server> <agent> -f mftConfigurationData.json
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
mftConfigurationData | Full path and name of a .json payload file that contains MFT configuration details, as described in MFT Configuration Data file in Configuration reference for file transfers to or from remote hosts. |
REST API Syntax
See REST API reference.
Example using curl:
server=myInstance
agent=myAgent
curl -H "x-api-key: $token" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/configuration"
--data "mftConfigurationData.json"
config server:agent:mft:fts:settings::get
Retrieves the details of File Transfer Server (FTS) settings. FTS settings contain configuration data of FTP/SFTP servers, FTS general settings, and authentication details.
The output is returned in JSON format. For more information about the various details returned in the output JSON, see FTS Settings Data file in Configuration reference for file transfers to or from remote hosts.
CLI Syntax
ctm config server:agent:mft:fts:settings::get <server> <agent>
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
REST API Syntax
See REST API reference.
Example using curl:
curl -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/mft/fts/settings"
config server:agent:mft:fts:settings::update
Update FTS settings based on configuration that you provide through a .json file.
Note
In your FTS Settings Data file, you can choose to include only those properties that you want to update. Any FTS settings that are not included in your FTS Settings Data file are not updated and remain untouched.
For full details about all FTS settings, as returned by the config server:agent:mft:fts:settings::get command, see FTS Settings Data file in Configuration reference for file transfers to or from remote hosts.
CLI Syntax
ctm config server:agent:mft:fts:settings::update <server> <agent> -f ftsSettingsData.json
Where:
Parameter | Description |
---|---|
<server> | Name of the instance |
<agent> | Name of host or alias of the Control-M/Agent |
ftsSettingsData | Full path and name of a .json payload file that contains details of FTS settings, as described in FTS Settings Data file in Configuration reference for file transfers to or from remote hosts. |
REST API Syntax
See REST API reference.
Example using curl:
server=myInstance
agent=myAgent
curl -H "x-api-key: $token" -X PUT "$endpoint/config/server/$server/agent/$agent/mft/fts/settings"
--data "ftsSettingsData.json"
Configuring file transfers to and from external users
9.0.20.000 Config mft enables you to manage the setup of your integration with Control-M Managed File Transfer (MFT) Enterprise B2B, to enable file transfers to and from external users outside of your organization (such as business partners). This feature is offered in an environment with Control-M 9.0.20 or later.
Control-M MFT Enterprise B2B uses the following major objects in file transfers to and from external users:
- Hub
- Gateway
- Virtual folders
- External users
- User groups
The following table lists the actions that you can perform through Control-M Automation API to set up the required objects.
Hub | Gateway | Virtual folder | External user | Groups |
---|---|---|---|---|
config mft:hub:status::get
Retrieves the current status of the MFT Enterprise B2B Hub, along with some basic information about the Hub (including details of the communication protocols used by the Hub and details regarding the associated gateways).
The Hub is the File Transfer Server that is installed with Control-M MFT, with added settings that enable it to manage external file transfers. In addition to the internal users that have access to the File Transfer Server, the Hub allows access also to external users.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:hub:status::get <nodeId>
Where <nodeId> is the ID of the host agent of the Hub.
REST API Syntax
See REST API reference.
Example using curl:
nodeId=abc-12-34
curl -H "Authorization: Bearer $token" $endpoint/config/mft/hub/$nodeId/status
config mft:cluster:hub::add
Adds a Hub to a cluster in a High Availability (HA) environment.
The Hub is the File Transfer Server that is installed with Control-M MFT, with added settings that enable it to manage external file transfers. In addition to the internal users that have access to the File Transfer Server, the Hub allows access also to external users.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:cluster:hub::add <agentname>
Where <agentname> is the name of the host that you want to add to the cluster, a host with a Control-M/Agent and Control-M MFT installed.
REST API Syntax
See REST API reference.
Example using curl:
agentname=myhost
curl -H "Authorization: Bearer $token" -X POST "$endpoint/config/mft/cluster/hub/$agentname"
config mft:cluster:hub::delete
Removes a Hub from a cluster in a High Availability (HA) environment.
CLI Syntax
ctm config mft:cluster:hub::delete <agentname>
Where <agentname> is the name of the host (with a Control-M/Agent) that you want to remove from the cluster.
REST API Syntax
See REST API reference.
Example using curl:
agentname=myhost
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/mft/cluster/hub/$agentname"
config mft:gateway::add
Adds a Control-M MFT Enterprise B2B Gateway.
The MFT Enterprise B2B Gateway is a proxy server that is installed on Linux in the DMZ. It listens for incoming connections from external user accounts defined in the MFT B2B Hub. The MFT Enterprise B2B Gateway communicates with the Hub, but does not store any transfer file data.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:gateway::add <gatewayHost> <port>
Where <gatewayHost> is the name of the gateway host, and <port> is the number of the port that the gateway listens to (default: 9443).
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST "$endpoint/config/mft/gateway/$gatewayHost/$port"
config mft:gateway::delete
Removes a Control-M MFT Enterprise B2B Gateway.
CLI Syntax
ctm config mft:gateway::delete <gatewayHost>
Where <gatewayHost> is the name of the host of the gateway that you want to delete.
REST API Syntax
See REST API reference.
Example using curl:
gatewayHost=myhost
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/mft/gateway/$gatewayHost"
config mft:gateways::get
Retrieves the details of all installed MFT Enterprise B2B Gateways. Details for each gateway include the gateway host, port, status (OK or ERROR), and a status message.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:gateways::get
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" "$endpoint/config/mft/gateways"
config mft:externaluser::add
Creates a new external user based on user definitions that you provide through the command or through an External User Data file.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:externaluser::add <user> <email> <companyName> [password] [-f ExternalUserData.json] [-p]
Where:
Parameter | Description |
---|---|
<user> | Name of the external user that you want to create The name must be unique, that is, not used by any other external user or user group. |
<email> | Email address of the user |
<companyName> | Name of the company with which the user is associated |
[password] | A password that controls the user's access to the file transfer mechanism, one of the following inputs:
If you are updating user definitions and do not want to change the existing password, enter the following string: |
[ExternalUserData] | Full path and name of a .json payload file that contains definitions for the external user, as described in External User Data file in Configuration reference for file transfers to or from external users. |
Specifying the password through the command is optional, because you have the following alternatives:
- Provide a password or predefined secret through the External User Data file.
- Use the
-p
(or-prompt
) option through the CLI. With this option, you do not need to enter the password in the command. Instead, you are prompted for the password (twice) after you enter the command.
Note: If you use both the password parameter and the-p
option, the password that you enter through the command prompt overrides the password that you specify in the command.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -F "ExternalUserData=@externalUser1.json"
-X POST $endpoint/config/mft/externaluser
config mft:externaluser::update
Updates an existing external user based on user definitions that you provide through an External User Data file.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
Note
Besides applying all settings that are explicitly defined in the External User Data file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:
- Obtain ALL current settings of the external user by running the config mft:externalusers::get command.
- Use the current definitions of the relevant external user (from the output of the previous step) to create your External User Data file, a .json file.
- In the External User Data file, change the specific settings that you want to update, and keep all other content in the file.
For full details about all user definitions, see External User Data file in Configuration reference for file transfers to or from external users. - Proceed with running the Update command.
CLI Syntax
ctm config mft:externaluser::update <name> <-f ExternalUserData.json> [-p]
Where:
Parameter | Description |
---|---|
<name> | Name of the external user that you want to update |
<ExternalUserData> | Full path and name of a .json payload file that contains definitions for the external user, as described in External User Data file in Configuration reference for file transfers to or from external users. |
If you do not want to specify the user's password through the External User Data file, you can include the -p
(or -prompt
) option in the CLI command. With this option, you are prompted for the password (twice) after you enter the command.
REST API Syntax
See REST API reference.
Example using curl:
name=user3
curl -H "Authorization: Bearer $token" -F "ExternalUserData=@externalUser1.json"
-X POST "$endpoint/config/mft/externaluser/$name"
config mft:externaluser::delete
Deletes an existing external user.
CLI Syntax
ctm config mft:externaluser::delete <name>
Where <name> is the name of the external user.
REST API Syntax
See REST API reference.
Example using curl:
name=user5
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/mft/externaluser/$name"
config mft:externalusers::get
Retrieves details of defined external users.
The output is returned in JSON format. You can use this output as a template for your own External User Data files when creating new external users or editing existing external users. For more information about the syntax of user definitions, see External User Data file in Configuration reference for file transfers to or from external users.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:externalusers::get [-s <search query>]
The optional -s is used to filter results by running a search using the query string format "field1=criteria1&field2=criteria2&field3=criteria3".
The following fields are available for use in the search query:
Field | Criteria guidelines |
---|---|
| For multiple values, use wildcards (* or ?) or commas. |
REST API Syntax
See REST API reference.
Examples using curl:
curl -H "Authorization: Bearer $token" $endpoint/config/mft/externalusers
curl -H "Authorization: Bearer $token" "$endpoint/config/mft/externalusers?name=a*&email=b*"
config mft:externaluser:virtualfolders::get
Retrieves a list of virtual folders that a specific external user is authorized to access.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:externaluser:virtualfolders::get <user>
Where <user> is the name of the external user.
REST API Syntax
See REST API reference.
Examples using curl:
user=user5
curl -H "Authorization: Bearer $token" $endpoint/config/mft/externaluser/$user/virtualfolders
config mft:virtualfolder::add
Creates a new virtual folder based on folder settings that you define through a Folder Properties file.
Virtual folders are used to transfer incoming and outgoing files between external and internal users. Authorizations applied at the folder level determine which external and internal users can access the folders. Folders can be configured to define a maximum retention period, and can generate email notifications to associated users when new files are available.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:virtualfolder::add <name> [-f folderPropertiesData.json]
Where:
Parameter | Description |
---|---|
<name> | Name of the virtual folder that you want to create |
<folderPropertiesData> | Full path and name of a .json payload file that contains definitions for the virtual folder, as described in Folder Properties Data file in Configuration reference for file transfers to or from external users |
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -F "folderPropertiesData=@virtualFolder1.json"
-X POST $endpoint/config/mft/virtualfolder
config mft:virtualfolder::update
Updates an existing virtual folder based on folder settings that you define through a Folder Properties file.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
Note
Besides applying all settings that are explicitly defined in the Folder Properties file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:
- Obtain ALL current settings of the virtual folder by running the config mft:virtualfolders::get command.
- Use the current definitions of the relevant virtual folder (from the output of the previous step) to create your Folder Properties file, a .json file.
- In the Folder Properties file, change the specific settings that you want to update, and keep all other content in the file.
For full details about all folder settings, see Folder Properties Data file in Configuration reference for file transfers to or from external users. - Proceed with running the Update command.
CLI Syntax
ctm config mft:virtualfolder::update <name> [-f folderPropertiesData.json]
Where:
Parameter | Description |
---|---|
<name> | Name of the virtual folder that you want to update |
<folderPropertiesData> | Full path and name of a .json payload file that contains definitions for the virtual folder, as described in Folder Properties Data file in Configuration reference for file transfers to or from external users. |
REST API Syntax
See REST API reference.
Example using curl:
name=folder3
curl -H "Authorization: Bearer $token" -F "folderPropertiesData=@virtualFolder1.json"
-X POST "$endpoint/config/mft/virtualfolder/$name"
config mft:virtualfolder::delete
Deletes an existing virtual folder.
CLI Syntax
ctm config mft:virtualfolder::delete <name>
Where <name> is the name of the virtual folder.
REST API Syntax
See REST API reference.
Example using curl:
name=folder5
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/mft/virtualfolder/$name"
config mft:virtualfolders::get
Retrieves details of defined virtual folders.
The output is returned in JSON format. You can use this output as a template for your own Folder Properties files when creating new virtual folders or editing existing virtual folders. For more information about the syntax of virtual folder definitions, see Folder Properties Data file in Configuration reference for file transfers to or from external users.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:virtualfolders::get [-s "name=<pattern>"]
The optional -s runs a search and filters the output based on folder name. For multiple values, use wildcards (* or ?) or commas.
For example: -s "name=a*"
REST API Syntax
See REST API reference.
Examples using curl:
curl -H "Authorization: Bearer $token" $endpoint/config/mft/users/virtualfolders
curl -H "Authorization: Bearer $token" "$endpoint/config/mft/users/virtualfolders?name=a*"
config mft:virtualfolder:user::add
Adds an external user or a user group to an existing virtual folder's list of authorized users and groups.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:virtualfolder:user::add <folder> <userOrGroup>
Where:
Parameter | Description |
---|---|
<folder> | Name of the virtual folder |
<userOrGroup> | Name of external user or user group |
REST API Syntax
See REST API reference.
Example using curl:
name=folder5
userOrGroup=userA
curl -H "Authorization: Bearer $token" -X POST "$endpoint/config/mft/virtualfolder/$name/user/$userOrGroup"
config mft:virtualfolder:user::remove
Removes an external user or user group from an existing virtual folder's list of authorized users and groups.
CLI Syntax
ctm config mft:virtualfolder:user::remove <folder> <userOrGroup>
Where:
Parameter | Description |
---|---|
<folder> | Name of the virtual folder |
<userOrGroup> | Name of external user or user group |
REST API Syntax
See REST API reference.
Example using curl:
name=folder5
userOrGroup=userA
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/mft/virtualfolder/$name/user/$userOrGroup"
config mft:usergroup::add
Creates a new group of users (external users or ldap users) based on group settings that you define through a User Group Properties file.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:usergroup::add <name> [-f UserGroupPropertiesData.json]
Where:
Parameter | Description |
---|---|
<name> | Name of the group that you want to create |
<UserGroupPropertiesData> | Full path and name of a .json payload file that contains definitions for the group, as described in User Group Properties Data file in Configuration reference for file transfers to or from external users. |
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -F "UserGroupPropertiesData=@group1.json"
-X POST $endpoint/config/mft/usergroup
config mft:usergroup::update
Updates an existing group of users (external users or ldap users) based on group settings that you define through a User Group Properties file.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:usergroup::update <name> <-f UserGroupPropertiesData.json>
Where:
Parameter | Description |
---|---|
<name> | Name of the group that you want to update |
<UserGroupPropertiesData> | Full path and name of a .json payload file that contains definitions for the group, as described in User Group Properties Data file in Configuration reference for file transfers to or from external users. This file is similar to the properties file that you use when adding a new user group. However, in the file used for updating an existing user group, you do NOT specify the name of the group. |
REST API Syntax
See REST API reference.
Example using curl:
name=group4
curl -H "Authorization: Bearer $token" -F "UserGroupPropertiesData=@group4.json"
-X POST "$endpoint/config/mft/usergroup/$name"
config mft:usergroup::delete
Deletes an existing group of users.
CLI Syntax
ctm config mft:usergroup::delete <name>
Where <name> is the name of the group.
REST API Syntax
See REST API reference.
Example using curl:
name=group6
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/mft/usergroup/$name"
config mft:usergroups::get
Retrieves details of defined groups.
The output is returned in JSON format. You can use this output as a template for your own User Group Properties files when creating new groups or editing existing groups. For more information about the syntax of group definitions, see User Group Properties Data file in Configuration reference for file transfers to or from external users.
To use this API command, you must be using Control-M MFT Enterprise B2B version 9.0.20 or later.
CLI Syntax
ctm config mft:usergroups::get [-s <search query>]
The optional -s is used to filter results by running a search using the query string format "field1=criteria1&field2=criteria2&field3=criteria3".
The following fields are available for use in the search query:
Field | Criteria guidelines |
---|---|
| For multiple values, use wildcards (* or ?) or commas. |
REST API Syntax
See REST API reference.
Examples using curl:
curl -H "Authorization: Bearer $token" $endpoint/config/mft/usergroups
curl -H "Authorization: Bearer $token" "$endpoint/config/mft/usergroups?name=a*&externalUsers=b*"
Configuring Secrets
Config secrets allows you to add, delete, or update named secrets in the Control-M vault. The Control-M vault is a secured collection of name and value pairs of secrets.
To learn how to use Secrets in Code, see Secrets in Code.
config secret::add
Creates a pair which consists of named secret and value in the Control-M vault.
ctm config secret::add <name> <value>
Parameter | Description |
---|---|
<name> | Name of the secret |
<value> | Value of the secret |
If annotation is enabled for the Scheduling definitions 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.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST -d "{\"name\":\"$name\",\"value\":\"$value\"}" "$endpoint/config/secret"
config secret::delete
Deletes the pair of named secret and value from the Control-M vault.
ctm config secret::delete <name>
Parameter | Description |
---|---|
<name> | Name of the secret |
If annotation is enabled for the Scheduling definitions 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.
Example using curl:
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/secret/$name"
config secret::update
Updates the value of the named secret in the Control-M vault.
ctm config secret::update <name> <value>
Parameter | Description |
---|---|
<name> | Name of the secret |
<value> | New value of secret |
If annotation is enabled for the Scheduling definitions 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.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST -d "{\"value\":\"$value\"}" "$endpoint/config/secret/$name"
config secrets::get
Returns a list of names of defined secrets.
ctm config secrets::get
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" "$endpoint/config/secrets"
Comments
Please provide sample JSON file that contains additional parameters. I can't find any example with possible parameters and values.
Log in or register to comment.