Agent Utilities

The following table describes Agent command line utilities that you can run on the Agent host.

Utility	Description
start-ag/shut-ag	Enables you to start up and shut down the Agent.
ctmag	Enables you to maintain, view, and modify the Agent configuration parameters.
ctmagcfg	Enables you to configure the Agent.
ctmunixcfg	Enables you to interactively view and modify most of the plug-in configuration parameters on Linux.
ctmwincfg	Enables you to interactively view and modify most of the plug-in configuration parameters on Windows.
ctmagcpk	Enables you to change a key password and apply the new key to job owner credentials for all installed plug-ins that support the AES algorithm.
set_agent_mode	Enables root, non-root, and Sudo modes on Linux.
ag_diag_comm	Verifies the ability of the Agent computer to communicate with the Control-M/Server.
ag_ping	Verifies whether the Control-M/Server is active and connected to the Agent.
_exit	Terminates processes on Windows.
_sleep	Suspends execution for a defined interval of time.
File Watcher (ctmfw)	Detects the successful creation or deletion of a file or a file transfer activity.
Health Check	Collects the environment information, logs, and saves them to a zip or tar.Z file for troubleshooting purposes.
agdbglvl	Enables you to change the Agent debug level.
Agent Toolbox	Analyzes proper functionality and troubleshoots issues on the Agent.

The following table describes additional utilities that are accessed via the Agent and invoke the Control-M/Server, along with the alternative service or command in Automation API.

To run these utilities, ensure that the ENABLE_AGENT_UTIL parameter is set to Y. Use the config systemsettings:server::set API command to configure this parameter.
If you have migrated from Control-M (On-Premises) to Control-M SaaS and have been using the ctmsec utility, all authorizations assigned through the ctmsec utility are NOT enforced after the migration. In such a case, BMC recommends that you do NOT enable the Agent utilities—that is, keep the default ENABLE_AGENT_UTIL=N. If you still want to enable this parameter, first check whether your users are allowed to run these utilities.

Utility	Description	Automation API Service or Command
ctmcontb	Enables you to perform operations on prerequisite conditions.	Run Service Event Management
ctmcreate	Inserts a specific job, SMART folder, or Sub Folder directly into the Active Jobs database.	Run Service Event Management
ctmdeffolder	Creates a definition for a new SMART folder.	Deploy Service
ctmdefine	Adds a job processing definition to a folder or sub-folder in the Control-M/Server database.	Deploy Service
ctmdefsubfolder	Creates a definition for a new sub-folder.	Deploy Service
ctmhostgrp	Enables you to maintain and view host groups.	Config Service Host Group Configuration
ctmkilljob	Terminates a specified Control‑M job that is currently executing and all its processes.	Run Service run job::kill
ctmloadset	Records current resource usage in the Resource Pools table.
ctmorder	Runs or forces one or more jobs from a SMART folder.	Run Service run run order
ctmpsm	Enables you to perform functions that affect jobs or conditions in the Active Jobs database of the data center.	Run Service Deploy Service
ctmshout	Sends a message to a specified user or destination.
ctmstvar	Displays the current value of a variable or function.	Run Service Job Management
ctmudly	Runs jobs whose folders are associated with a specific User Daily name. This utility is always enabled and is not controlled by the ENABLE_AGENT_UTIL parameter.	Run Service run order
ctmvar	Enables you to manage variables.	Run Service Variable Management
ecaqrtab	Enables you to perform operations in the Resource Pools table.	Run Service Resource Management
ecactltb	Displays a list of Lock Resources and the status of each resource.

If you have multiple Agents installed on a Windows host, the first Agent that is installed is the default Agent and is assigned the Agent instance name Default. If you want to run a utility on a different Agent instance that is on this host, you must run the following command:

<utility_Name> <Parameters> -agent <Agent_Instance_Name>
If your Agent is connected to more than one Control-M/Server and you need to run an Agent utility on the non-default Control-M/Server, you must add the -server_code <Control-M/Server_Code> flag to the Agent utility command. This enables you to determine which Control-M/Server information the Agent utility accesses. For more information, see Agent Connection to Multiple Control-M/Servers.

The following table lists utilities that are not available in Control-M SaaS but have an equivalent service or command in Automation API.

Utility	Automation API Service or Command
ctmwhy	Run Service run job::waitingInfo