Config service

The config service allows you to configure the Control-M environment:

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:

ParameterDescription
<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

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:

REST API
host=`hostname`
id=123
ctm=myserver
port=2369
 
curl -X POST $endpoint/config/server/ -H 'accept: application/json' -H 'authorization: Bearer &token' -H 'content-type: 
application/json' -d '{"host": "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 <ctm> 

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:

REST API
endpoint=https://<controlm>:8443/automation-api
token=
ctm= 
curl -X DELETE -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm"

config servers::get

Returns a list of Control-M/Servers. 

CLI Syntax

CLI
ctm config servers::get

REST API Syntax

See REST API reference.

Example using curl:

REST API
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"
  }

Where:

ParameterDescription
nameControl-M/Server name
hostControl-M/Server host name
state

Determines the state of the Control-M/Server

Options:

  • Up
  • Down
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

CLI
ctm config server:failover <ctm> 

Where <ctm> 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:

REST API
ctm=controlm
curl -H "Authorization: Bearer $token" -X PUT "$endpoint/config/server/$ctm/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

CLI
ctm config server:setasprimary <ctm> 

Where <ctm> 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:

REST API
ctm=controlm
curl -H "Authorization: Bearer $token" -X PUT "$endpoint/config/server/$ctm/setasprimary" 

config server:remotehost::add

The remotehost add command enables you to add a remote host to a Control-M/Server. 

CLI Syntax

CLI
ctm config server:remotehost::add <ctm> <remotehost> [port] [-f <configuration file>]

Where:

Parameter

Description

<ctm>

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 REST request parameters that can be used:

{
    "remotehost" : "xx", 
    "port" : 22,
    "agents": [
        "<local>"
    ]
    "encryptAlgorithm": "BLOWFISH",
    "compression": "false",
    "authorize: "true"
}

Where:

ParameterDescription
agents

Control-M/Agents that manage the remote host. If not defined, the default Control-M/Agent will be used.

Default: local

portDefault: 22
encryptAlgorithm

Encryption algorithm type used to encrypt data between the Control-M/Agent and the remote host. The options are:

  • BLOWFISH
  • AES
  • DES
  • 3DES

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:

REST API
ctm=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/$ctm/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

CLI
ctm config server:remotehost::authorize <ctm> <remotehost>

Where:

Parameter

Description

<ctm>

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:

REST API
ctm=controlm
remotehost=myhost
curl -H "Authorization: Bearer %token%" -H "Content-Type: application/json" -X POST 
"%endpoint%/config/server/$ctm/remotehost/$remotehost/authorize"

config server:remotehost::delete

Deletes a remote host from the Control-M/Server. 

CLI Syntax

CLI
ctm config server:remotehost::delete <ctm> <remotehost>

Where:

Parameter

Description

<ctm>

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:

REST API
ctm=controlm
remotehost=myhost
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/server/$ctm/remotehost/$remotehost"

config server:remotehosts::get

Returns a list of all remote hosts registered to the Control-M/Server. 

CLI Syntax

CLI
ctm config server:remotehosts::get <ctm>

Where:

Parameter

Description

<ctm>

Name of the Control-M/Server

REST API Syntax

See REST API reference.

Example using curl:

REST API
ctm=controlm 
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/remotehosts"

config server:remotehost::get

Returns the remote host configuration properties from the Control-M/Server. 

CLI Syntax

CLI
ctm config server:remotehost::get <ctm> <remotehost>

Where:

Parameter

Description

<ctm>

Name of the Control-M/Server

<remotehost>Name of host or alias of the remote host

REST API Syntax

See REST API reference.

Example using curl:

REST API
ctm=controlm
remotehost=myhost
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/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

CLI
ctm config server:agent::add <ctm> <host> <port> [-f <configuration file>]

Where:

Parameter

Description

<ctm>

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.

[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 REST request parameters that can be used:

{    
	"persistentConnection": true
} 

Where:

ParameterDescription
persistentConnection

Creates a permanent connection between Control-M/Server and Control-M/Agent for a firewall environment.

true | false

Default: false

REST API Syntax

See REST API reference.

Example using curl:

REST API
ctm=controlm
host=myhost
port=7006

curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d "{\"host\":\"$host\",\"port\":\"$port\"}" "$endpoint/config/server/$ctm/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

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

Where:

Parameter

Description

<ctm>

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:

REST API
ctm=controlm
agent=myhost
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/server/$ctm/agent/$agent"

config server:agent:params::get

Get parameters of a Control-M/ Agent registered to a Control-M/Server. Returns a list of Control-M/Agent parameters. Each entry is a pair which consists of parameter name and value. 

CLI Syntax

CLI
ctm config server:agent:params::get <ctm> <agent>

Where:

Parameter

Description

<ctm>

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:

REST API
ctm=controlm
agent=host
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/agent/$agent/params"

config server:agent:param::set

Set the value of a specific Control-M/Agent parameter.

CLI Syntax

CLI
ctm config server:agent:param::set <ctm> <agent> <name> <value>

Where:

Parameter

Description

<ctm>

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:

REST API
ctm=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/$ctm/agent/$agent/param/$name"

config server:agent::ping

Checks if the Control-M/Agent is available.

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

Where:

ParameterDescription
<ctm>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 REST request parameters that can be used:

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

Where:

ParameterDescription
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:

ctm=controlm
agent=quickstart
curl -X POST -H "Authorization: Bearer $token"  -H "Content-Type: application/json" -d "{\"discover\": false, \"timeout\":60}" "$endpoint/config/server/$ctm/agent/$agent/ping"

config server:agents::get

Returns a list of all Control-M/Agents registered to the Control-M/Server and the state of each agent. You can optionally filter the list for Agents that match a specific pattern.

The states supported are:   

  • Available
  • Unavailable
  • Disabled
  • Discovering

CLI Syntax

CLI
ctm config server:agents::get <ctm> ["agent=<agent_pattern>"]

Where:

Parameter

Description

<ctm>

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: "agent=Agent*" or "agent=*Agent*"

REST API Syntax

See REST API reference.

Example using curl:

REST API
ctm=controlm 
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/agents?agent=Agent*1*"

config server:agent::disable

Disables Control-M/Agent from Control-M/Server. New jobs cannot run on the Control-M/Agent.

CLI Syntax

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

Where:

Parameter

Description

ctm

Name of Control-M/Server

agentName 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:

REST API
endpoint=https://<yourhost>:8443/automation-api
token=
ctm=
agent=

curl -X POST -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/agent/$agent/disable"

config server:agent::enable

Enables jobs to run on the Control-M/Agent. 

CLI Syntax

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

Where:

Parameter

Description

ctm

Name of Control-M/Server

agentName of Control-M/Agent

REST API Syntax

See REST API reference.

Example using curl:

REST API
endpoint=https://<yourhost>:8443/automation-api
token=
ctm=
agent=

curl -X POST -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/agent/$agent/enable"

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

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

Where:

Parameter

Description

<ctm>

Name of Control-M/Server

REST API Syntax

See REST API reference.

Example using curl:

REST API
ctm=controlm 
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/hostgroups"

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

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

Parameter

Description

<ctm>

Name of Control-M/Server

<hostgroup>Name of host group

REST API Syntax

See REST API reference.

Example using curl:

REST API
ctm=controlm
hostgroup=HostGroup1 
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/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

CLI
ctm config server:hostgroup:agent::add <ctm> <hostgroup> <host> [-f <configuration file>]

Where:

Parameter

Description

<ctm>

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 REST request parameters that can be used:

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

Where:

ParameterDescription
host

Name of host or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent.

hostgroupAgentParticipationOnly if event occurs, the host will be part of host group
orderDate

The work day on which to schedule the requested action. Possible values:

Date TypeDescription
AnyDateAny scheduled date
OrderDateControl-M scheduled date
NoDateNot date-specific
MMDD

Specific date

Example: "0511"

event

Name of an event

REST API Syntax

See REST API reference.

Example using curl:

REST API
ctm=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/$ctm/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

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

Where:

Parameter

Description

<ctm>

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:

REST API
ctm=controlm
hostgroup=mygroup 
host=myhost
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/server/$ctm/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

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

Where:

Parameter

Description

<ctm>

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:

  • Password authentication A password for the user, either plain text or a predefined secret.
  • Key authentication A key and passphrase for an SSH connection to a remote host. The passphrase can be either plain text or a predefined secret.

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.

REST API
ctm=controlm
curl -H "Authorization: Bearer $token" 
-H "Content-Type: application/json" --data "@runasUserDefinition.json" 
-X POST "$endpoint/config/server/$ctm/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

CLI
ctm config server:runasuser::get <ctm> <agent> <user>

Where:

Parameter

Description

<ctm>

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

REST API Syntax

See REST API reference.

Example using curl:

REST API
ctm=controlm
curl -H "Authorization: Bearer $token" 
$endpoint/config/server/$ctm/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

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

Where:

Parameter

Description

<ctm>

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 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:

  • Password authentication A password for the user, either plain text or a predefined secret.
  • Key authentication A key and passphrase for an SSH connection to a remote host. The passphrase can be either plain text or a predefined secret.

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. 

REST API
ctm=controlm
curl -H "Authorization: Bearer $token" 
-H "Content-Type: application/json" --data "@runasUserDefinition.json" 
-X POST "$endpoint/config/server/$ctm/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

CLI
ctm config server:runasuser::delete <ctm> <agent> <user>

Where:

Parameter

Description

<ctm>

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

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:

REST API
ctm=controlm
curl -H "Authorization: Bearer $token" 
-X DELETE $endpoint/config/server/$ctm/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

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

Where:

Parameter

Description

<ctm>

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 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:

    ctm=controlm
    curl -H "Authorization: Bearer $token" 
    -H "Content-Type: application/json" --data "{}"  
    -X POST $endpoint/config/server/$ctm/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:

    ctm=controlm
    curl -H "Authorization: Bearer $token" 										
    -H "Content-Type: application/json" --data "@runasUserDefinition.json"
    -X POST "$endpoint/config/server/$ctm/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.

CLI Syntax

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

Where:

Parameter

Description

<ctm>

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:

  • agent
  • user

For example:
agent=agent1*&user=user1*

REST API Syntax

See REST API reference.

Example using curl:

REST API
ctm=controlm
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/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

CLI
ctm config server:params::get <ctm>

Where:

Parameter

Description

<ctm>

Name of Control-M/Server

REST API Syntax

See REST API reference.

Example using curl:

REST API
ctm=controlm 
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/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

CLI
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:

REST API
paramName=api_key
value=true
curl -H "Authorization: Bearer $token" -X POST -d "{\"value\":\"$value\"}" "$endpoint/config/em/$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

CLI
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:

"<type>:<host>:<name>"

The ID is composed of the following elements:

  • type — The type of Control-M component.
    For recycling of an agent, the type is CTMS:Agent.
  • host — The name of the machine that hosts the Control-M component.
    For an agent, this is the name of the Control-M/Server.
  • name — The logical name of the Control-M component.
    For an agent, this is the host name or alias of the Control-M/Agent.

REST API Syntax

See REST API reference.

Example using curl:

REST API
id="CTMS:Agent:controlm:myAgent"
curl -H "Authorization: Bearer $token" -X POST "$endpoint/config/item/$id/recycle"

Back to top

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:

{note

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

CLI
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:

REST API
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

CLI
ctm config authorization:role::get <role>

Where <role> is the name of the role.

REST API Syntax

See REST API reference.

Example using curl:

REST API
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:

  1. Obtain ALL current role settings by runing the config authorization:role::get command.
  2. Use the output from the previous step to create your role data file, a .json file.
  3. 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.
  4. Proceed with running the Update command.

CLI Syntax

CLI
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:

REST API
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

CLI
ctm config authorization:role::delete <role>

Where <role> is the name of the role.

REST API Syntax

See REST API reference.

Example using curl:

REST API
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

CLI
ctm config authorization:roles::get [-s <search query>]

The optional -s swtich 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
  • role
  • description
  • As wildcards, use asterisks or question marks (* or ?).
  • To specify multiple values for a field, use commas.

"description=Ad*"
"role=AdminRole&description=Ad*"
"role=AdminRole,OperatorRole"

If you include multiple fields in the query, separate them with an ampersand (&).

REST API Syntax

See REST API reference.

Example using curl:

REST API
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

CLI
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:

REST API
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.

CLI Syntax

CLI
ctm config authorization:user::get <user>

Where <user> is the name of the user.

REST API Syntax

See REST API reference.

Example using curl:

REST API
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:

  1. Use the output from the previous step to create your user data file, a .json file.
  2. 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.
  3. Proceed with running the Update command.

CLI Syntax

CLI
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:

REST API
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

CLI
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:

REST API
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

CLI
ctm config authorization:users::get [-s <search query>]

The optional -s swtich 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
  • name
  • fullname
  • description
  • As wildcards, use asterisks or question marks (* or ?).
  • To specify multiple values for a field, use commas.

"description=super user*"
"name=em*&description=super*"
"name=emuser,emoperator"

If you include multiple fields in the query, separate them with an ampersand (&).

REST API Syntax

See REST API reference.

Example using curl:

REST API
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

CLI
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:

REST API
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

CLI
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:

REST API
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

CLI
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:

  • Plain text
  • Predefined secret, with the following format: "Secret:<secretKey>"

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.

REST API
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

CLI
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:

REST API
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

CLI
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:

REST API
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

CLI
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:

REST API
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

CLI
ctm config authorization:role:associates <role>

Where <role> is the name of the role.

REST API Syntax

See REST API reference.

Example using curl:

REST API
roleName=myRole
curl -H "Authorization: Bearer $token"
$endpoint/config/authorization/role/$roleName/associates

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:

REST API
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:

REST API
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:

REST API
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:

REST API
curl -H "Authorization: Bearer $token"  "$endpoint/config/secrets"

Back to top

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

Comments