Agent Configuration

The following API commands enable you to configure an Agent:

• config server:agent::update

• config server:agent::delete

• config server:agent::ping

• config server:agents::get

• config server:agent::disable

• config server:agent::enable

• config item::recycle

• config server:hostRestrictions::get

• config server:hostRestriction::add

• config server:hostRestriction::update

• config server:hostRestriction::delete

config server:agent::update

The config server:agent::update command enables you to update one of the parameters in the configuration of the Control-M/Agent, as registered to the Server.

CLI Syntax

ctm config server:agent::update <server> <agent> <name> <value> [-f <json file>]

The following table describes the config server:agent::update command parameters.

{
    "name": "maximumRetries",
    "value": "9"
}

The following table describes the Agent parameters that are supported by the config server:agent::update and config server:agent::test API commands.

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

server=IN01
agent=myHost
name=maximumRetries
value=10

curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST 
-d "{\"name\":\"$name\", \"value\":\"$value\"}" "$endpoint/config/server/$server/agent/$agent/update"

config server:agent::delete

The config server:agent::delete command enables you to delete an Agent from the Server without shutting the Agent down.

CLI Syntax

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

The following table describes the config server:agent::delete command 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

server=controlm
agent=myhost
curl -H "x-api-key: $token" -X DELETE "$endpoint/config/server/$server/agent/$agent"

config server:agent::ping

The config server:agent::pingcommand enables you to check if the Agent is available.

CLI Syntax

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

The following table describes the config server:agent::ping command parameters.

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

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

The following table describes additional config server:agent::ping command parameters.

REST API Syntax

server=IN01
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

The config server:agents::get command enables you to get 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=<agent_pattern>"]

The following table describes the config server:agents::get command parameters.

REST API Syntax

server=IN01
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.21.080",
      "operatingSystem": "Microsoft Windows Server 2016  (Build 14393)"
    }
  ]
}

config server:agent::disable

The config server:agent::disable command enables you to disable the Agent from the Server. New jobs cannot run on the Agent.

CLI Syntax

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

The following table describes the config server:agent::disable command 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

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

config server:agent::enable

The config server:agent::enable command enables you to enable jobs to run on the Agent after it was disabled.

CLI Syntax

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

The following table describes the config server:agent::enable command parameters.

REST API Syntax

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

config item::recycle

The config item::recycle command enables you to recycle a specific Control-M component. Use this command to restart a component to solve server issues. You can use this command to recycle Agents.

CLI Syntax

ctm config item::recycle <id>

The following table describes the config item::recycle command parameters.

REST API Syntax

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

config server:hostRestrictions::get

The config server:hostRestrictions::get command enables you to get all the Agent (Host) Restrictions for a Server.

Agent (Host) Restrictions enables you to restrict the resources used and the number of concurrent jobs that you can execute on one or more Agents. This helps prevent resource overload.

CLI Syntax

ctm config server:hostRestrictions::get <server>

where server is the name of the Server.

REST API Syntax

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

config server:hostRestriction::add

The config server:hostRestriction::add command enables you to add an Agent (Host) restriction to an Agent.

Agent (Host) Restrictions enables you to restrict the resources used and the number of concurrent jobs that you can execute on one or more Agents. This helps prevent resource overload.

CLI Syntax

ctm config server:hostRestriction::add <server> <nodePrefix> <maxJobsAllowed> <maxCPUPct>

The following table describes the config server:hostRestriction::add command parameters.

REST API Syntax

server=IN01
curl -H "x-api-token: $token" -H "Content-Type: application/json" -X POST \
-d "{\"nodePrefix\":\"ctm21200\",\"maxJobsAllowed\":\"UNLIMITED\",\"maxCPUPct\":\"80\"}" \
"$endpoint/config/server/$server/hostRestriction"

config server:hostRestriction::update

The config server:hostRestriction::update command enables you to update the Agent (Host) restrictions on an Agent.

CLI Syntax

ctm config server:hostRestriction::update <server> <nodePrefix> <maxJobsAllowed> <maxCPUPct>

The following table describes the config server:hostRestriction::update command parameters.

REST API Syntax

server=IN01
curl -H "x-api-token: $token" -H "Content-Type: application/json" -X PUT \
-d "{\"nodePrefix\":\"ctm21200\",\"maxJobsAllowed\":\"UNLIMITED\",\"maxCPUPct\":\"80\"}" \
"$endpoint/config/server/$server/hostRestriction"

config server:hostRestriction::delete

The config server:hostRestriction::delete command enables you to remove all the Agent (Host) restrictions on one or more Agents.

CLI Syntax

ctm config server:hostRestriction::delete <server> <nodePrefixes>

The following table describes the config server:hostRestriction::delete command parameters.

REST API Syntax

server=IN01 
nodePrefixes = "agent1,agent2"
curl -H "x-api-token: $token" -X DELETE "$endpoint/config/server/$server/hostRestriction?nodePrefix=$nodePrefixes"