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 file transfers to and from remote hosts
• 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 manage remote hosts and host groups, manage "run as" users, and set several Control-M parameters.

config servers::get

Returns a list of servers. 

CLI Syntax

ctm config servers::get

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $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 server is up and connected.

  {
    "name": "IN01",
    "host": "myhost",
    "state": "Up",
    "message": "Connected",
    "version": "9.0.20.080"
  }

Where:

config server:agent::delete

Removes an agent from the server without shutting the agent down.

CLI Syntax

ctm config server:agent::delete <server> <agent>

Where:

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
agent=myhost
curl -H "x-api-key: $token" -X DELETE "$endpoint/config/server/$server/agent/$agent"

config server:agent:params::get

Get system parameters of an agent registered to the 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:

REST API Syntax

See REST API reference.

Example using  curl:

server=myServer
agent=host
curl -H "x-api-key: $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:

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
agent=quickstart
name=LIMIT_LOG_VERSIONS
value=10
curl -H "x-api-key: $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 agent is available.

ctm config server:agent::ping <server> <agent> [-f <configuration file>]

Where:

The following is a list of the additional parameters that can be used in the configuration file:

{     "discover": true,"timeout":60}

Where:

REST API Syntax

See REST API reference.

Example using  curl:

server=myServer
agent=quickstart
curl -X POST -H "x-api-key: $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 agents registered to the 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:

REST API Syntax

See REST API reference.

Example using  curl:

server=myServer 
curl -H "x-api-key: $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), a list of host groups to which the agent is associated, product version, and host operating system. The following example shows the details returned for each agent:

{
  "agents": [
    {
      "nodeid": "myAgent",
      "status": "Available",
      "hostgroups": [
        "group1",
        "group2",
        "group3"
      ],
      "version": "9.0.20.080",
      "operatingSystem": "Microsoft Windows Server 2016  (Build 14393)"
    }
  ]
}

config server:agent::disable

Disables the agent from the server. New jobs cannot run on the agent.

CLI Syntax

ctm config server:agent::disable <server> <agent>

Where:

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 "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/disable"

config server:agent::enable

Enables jobs to run on the agent. 

CLI Syntax

ctm config server:agent::enable <server> <agent>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -X POST -H "x-api-key: $token" "$endpoint/config/server/$server/agent/$agent/enable"

config server:hostgroups::get

Returns a list of host groups defined in the server. Each entry is a host group name. The list includes only those host groups that you are authorized to manage.

CLI Syntax

ctm config server:hostgroups::get <server>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

server=myServer 
curl -H "x-api-key: $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:

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:

{ 
"tag":"abcdef",
	"agentslist": [
       {
             "host": "agent1",
             "hostgroupAgentParticipation": {
                 "event": "eventString",
                 "orderDate": "AnyDate"
             }
       },
       {
              "host": " agent2",
              "hostgroupAgentParticipation": null
        },
        {
              "host": " agent3”
        }
   ]
}

The following parameters are available for each agent defined in the configuration file:

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 "{\"tag\": \"tagString\", \"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 (provided that you are authorized to manage this host group).

CLI Syntax

ctm config server:hostgroup::delete <server> <hostgroup>

Where:

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-key: $token" -X DELETE "$endpoint/config/server/$server/hostgroup/$hostgroup"

config server:hostgroups:agents::get

Returns a list of host groups defined in the Control-M/Server, along with the list of Agents in each host group. The list includes only those host groups that you are authorized to manage.

CLI Syntax

ctm config server:hostgroups:agents::get <server>

where <server> is the name of a Control-M/Server (currently IN01).

REST API Syntax

See REST API reference.

Example using  curl:

server=controlm
curl -H "x-api-key: $token" "$endpoint/config/server/$server/hostgroups/agents"

config server:hostgroup:agents::get

Returns a list of agents of a host group (provided that you are authorized to manage this host group). Each entry is the logical name of an Agent.

CLI Syntax

ctm config server:hostgroup:agents::get <server> <hostgroup>

REST API Syntax

See REST API reference.

Example using  curl:

server=myServer
hostgroup=HostGroup1 
curl -H "x-api-key: $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:

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:

{      
	"tag":"abcdef",
	"host":"agent3",
   	"hostgroupAgentParticipation":{  
      "event":"agent3Cond",
      "orderDate":"AnyDate"
   }
}

Where:

REST API Syntax

See REST API reference.

Example using  curl:

server=myServer
hostgroup=mygroup 
host=myhost
curl -H "x-api-key: $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 (provided that you are authorized to manage this host group). If the group is empty after the deletion, it is also deleted.

CLI Syntax

ctm config server:hostgroup:agent::delete <server> <hostgroup> <host>

Where:

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=mygroup 
host=myhost
curl -H "x-api-key: $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.

CLI Syntax

ctm config server:runasuser::add <server> <agent> <user> [password] [-f <configuration file>]

Where:

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=myServer
curl -H "x-api-key: $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:

REST API Syntax

See REST API reference.

Example using curl:

server=myServer
curl -H "x-api-key: $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.

CLI Syntax

ctm config server:runasuser::update <server> <agent> <user> [password] [-f <configuration file>]

Where:

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=myServer
curl -H "x-api-key: $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:

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
curl -H "x-api-key: $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:

REST API Syntax

See REST API reference.

Examples using curl:

• Example for testing an existing user:

  server=myServer
  curl -H "x-api-key: $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=myServer
  curl -H "x-api-key: $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). The 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. The response matches the user level of authorization.

CLI Syntax

ctm config server:runasusers::get <server> [-s <query string>] 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

server=myServer
curl -H "x-api-key: $token" "$endpoint/config/server/$server/runasusers?agent=agent1&user=user1"

config systemsettings::get

Retrieves details of general system settings.

The output is returned in JSON format. You can use this output as a template when you set new values for general system settings. For more information about the available settings and their JSON syntax, see System Settings reference.

CLI Syntax

ctm config systemsettings::get [-s "server=<serverName>"] 

The optional -s swtich can be used to filter by name of server instance.

REST API Syntax

See REST API reference.

Example using  curl:

server=myServer
curl -H "x-api-key: $token" $endpoint/config/systemsettings?server=$serverName

config systemsettings::set

Modifies general system settings based on definitions that you provide through a .json file.

You can optionally use this API command to integrate your SAML2 identity provider (IdP) with Control-M to support Single Sign On (SSO) authentication.

CLI Syntax

ctm config systemsettings::set <systemsetting.json> [saml2metadatafile] [server]

REST API Syntax

See REST API reference.

Example using  curl:

serverName=myServer
curl -H "x-api-key: $token" -X POST $endpoint/config/systemsettings?server=$serverName

config systemsettings:server::get

Returns a list of server-related system settings. The following fields are returned for each parameter:

• name
• value
• defaultValue

For more information about this group of settings, see Server Settings reference.

CLI Syntax

ctm config systemsettings:server::get [<server>]

Where:

REST API Syntax

See REST API reference.

Example using  curl:

serverName=IN01
curl -H "x-api-key: $token" $endpoint/config/systemsettings/server?server=$serverName

config systemsettings:server::set

Sets a value for a server-related system setting.

For a list of settings that you can set, see Server Settings reference.

CLI Syntax

ctm config systemsettings:server::set <name> <value> [<server>]

Where:

REST API Syntax

See REST API reference.

Example using  curl:

serverName=IN01
name="CYCLIC_RERUN" 
value="OK"
curl -H "x-api-key: $token" -X POST $endpoint/config/systemsettings/server/$name/$value/set?server=$serverName

config systemsettings:identityprovidermetadata::get

Retrieves metadata from the SAML2 IdP that you integrated with Control-M. The output is SAML2 metadata in XML format.

For information about the steps involved in integrating your SAML2 IdP with Control-M to support Single Sign On (SSO) authentication (prior to running this API command), see System Settings reference.

CLI Syntax

ctm config systemsetting:identityprovidermetadata::get

REST API Syntax

See REST API reference.

Example using  curl:

server=myServer
curl -H "x-api-key: $token" "$endpoint/config/systemsettings/identityprovidermetadata"

config item::recycle

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 agents.

CLI Syntax

ctm config item::recycle <id>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

id="CTMS:Agent:IN01:myAgent"
curl -H "x-api-key: $token" -X POST "$endpoint/config/item/$id/recycle"

_{Back to top}

Configuring Authorizations

Config authorization enables you to manage the authorizations of roles and users, as well organization groups and users (such as LDAP or IdP groups and users), limiting their access to various Control-M entities and actions.

The following table summarizes the actions that you can take for each authorization entity:

Note: If you enable a SAML2 identity provider for Single Sign On (SSO) authentication, certain user authorization management actions are no longer relevant and cannot be performed. These include adding, updating, or deleting a user, as well as getting user details.

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 Configuring role authorizations.

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 "x-api-key: $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.
• For similar details for a user, calculated from all associated roles, see config authorization:user:effectiverights::get.

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 "x-api-key: $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.

CLI Syntax

ctm config authorization:role::update <role> <roleFile>

Where:

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 "x-api-key: $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 "x-api-key: $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:

REST API Syntax

See REST API reference.

Example using curl:

roleName=Adm*
curl -H "x-api-key: $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 Configuring user authorizations.

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 "x-api-key: $token" -F "userFile=@userDefinition.json"
-X POST $endpoint/config/authorization/user

config authorization:user::get

Retrieves the details of an existing user (user name and associated roles), as defined 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 "x-api-key: $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.

CLI Syntax

ctm config authorization:user::update <user> <userFile>

Where <user> is the name of the user that you want to update, and <userFile> is the full path and name of a .json payload file that contains user definitions, as described in Configuring user authorizations.

Note that you cannot update the user name.

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 "x-api-key: $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 "x-api-key: $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. The format for the query string is "name=userName".

As wildcards, use asterisks or question marks (* or ?). To specify multiple user names, use commas.

REST API Syntax

See REST API reference.

Example using curl:

userName=emuser*
curl -H "x-api-key: $token" $endpoint/config/authorization/users?name=$userName

config authorization:user:effectiverights::get

Retrieves details regarding the authorizations and privileges that are in effect for the logged-in user. A user's effective rights are calculated based on the authorizations defined in the various roles that are associated with that user.

Note:

• Only parameters that are set to non-default values are retrieved and displayed in the output.
• For similar details for any specific role, see config authorization:role::get

CLI Syntax

ctm config authorization:user:effectiverights::get

REST API Syntax

See REST API reference.

Example using curl:

curl -H "x-api-key: $token"
"$endpoint/config/authorization/user/effectiverights"

config authorization:ldap:role::add (deprecated)

Deprecated as of version 9.0.21. Replaced by use of the OrganizationGroups property in the role data file, as described in Configuring role authorizations.

Adds a role to an LDAP group (or SAML 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:

REST API Syntax

See REST API reference.

Example using curl:

roleName=myRole
ldapGroup=myGroup
curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X POST "$endpoint/config/authorization/ldap/$ldapGroup/role/$roleName"

config authorization:ldap:role::delete (deprecated)

Deprecated as of version 9.0.21. Replaced by use of the OrganizationGroups property in the role data file, as described in Configuring role authorizations.

Deletes a role from an LDAP group (or SAML group).

CLI Syntax

ctm config authorization:ldap:role::delete <ldapGroup> <role>

Where:

REST API Syntax

See REST API reference.

Example using curl:

roleName=myRole
ldapGroup=myGroup
curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X DELETE "$endpoint/config/authorization/ldap/$ldapGroup/role/$roleName"

config authorization:ldap:roles::get (deprecated)

Deprecated as of version 9.0.21. Replaced by config authorization:organizationgroup:roles::get.

Retrieves a list of roles that are associated with a specific LDAP group (or SAML group).

CLI Syntax

ctm config authorization:ldap:roles::get <ldapGroup> [-s "role=<query pattern>"]

Where:

REST API Syntax

See REST API reference.

Example using curl:

roleName=myRole
ldapGroup=myGroup
curl -H "x-api-key: $token" $endpoint/config/authorization/ldap/$ldapGroup/roles?role=$roleName

config authorization:organizationgroup:roles::get

Retrieves a list of roles that are associated with a specific organization group (such as an LDAP group or IdP group).

CLI Syntax

ctm config authorization:organizationgroup:roles::get <organizationGroup> [-s "role=<query pattern>"]

Where:

REST API Syntax

See REST API reference.

Example using curl:

roleName=myRole
organizationGroup=myGroup
curl -H "x-api-key: $token" $endpoint/config/authorization/organizationgroup/$organizationGroup/roles?role=$roleName

config authorization:organizationgroups::get

Retrieves a list of all organization groups (such as LDAP groups or IdP groups) that are associated with any of the defined roles.

CLI Syntax

ctm config authorization:organizationgroups::get

REST API Syntax

See REST API reference.

Example using curl:

curl -H "x-api-key: $token" $endpoint/config/authorization/organizationgroups

config authorization:organizationuser:roles::get

Retrieves a list of roles that are associated with a specific organization user (such as an LDAP user or IdP user).

CLI Syntax

ctm config authorization:organizationuser:roles::get <organizationUser> [-s "role=<query pattern>"]

Where:

REST API Syntax

See REST API reference.

Example using curl:

roleName=myRole
organizationUser=user5
curl -H "x-api-key: $token" $endpoint/config/authorization/organizationgroup/$organizationUser/roles?role=$roleName

config authorization:organizationusers::get

Retrieves a list of all organization users (such as LDAP users or IdP users) that are associated with any of the defined roles.

CLI Syntax

ctm config authorization:organizationusers::get

REST API Syntax

See REST API reference.

Example using curl:

curl -H "x-api-key: $token" $endpoint/config/authorization/organizationusers

config authorization:role:associates

Retrieves a list of all users, organization users, and organization 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 "x-api-key: $token" $endpoint/config/authorization/role/$roleName/associates

Configuring file transfers to and from remote hosts

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:

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:

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:

{
"hostList" :
 [
  { "physicalHostname": "host1" , "port": "22" },
  { "physicalHostname": "host2" , "port": "1222" }
 ]
}

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:

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.

CLI Syntax

ctm config server:agent:mft:pgptemplate::update <server> <agent> <templateName> -f pgptemplateData.json

Where:

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:

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:

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:

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.

CLI Syntax

ctm config server:agent:mft:zostemplate::update <server> <agent> <templateName> -f zosTemplateData.json

Where:

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:

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:

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:

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.

CLI Syntax

ctm config server:agent:mft:configuration::update <server> <agent> -f mftConfigurationData.json

Where:

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:

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.

CLI Syntax

ctm config server:agent:mft:fts:settings::update <server> <agent> -f ftsSettingsData.json

Where:

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"

_{Back to top}

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>

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 "x-api-key: $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> 

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 "x-api-key: $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>

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 "x-api-key: $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 "x-api-key: $token" "$endpoint/config/secrets"

_{Back to top}