ctmping
The ctmping utility tests, configures, and reports on the connection and availability between a Control-M/Server and its Agents or Agentless Hosts.
ctmping can be included in the Watchdog process. For more information, see Watchdog Process Parameters.
This utility can check if an Agent or Agentless Host is down and, if required, register it in the database as unavailable. When the Agent or Agentless Host again becomes available, the state is changed and information about it is gathered by a Control-M/Server process.
You can only ping and Agent after it completes an upgrade. If you ping an Agent while it is upgrading, the following error message appears:
Cannot ping the Agent. Agent is upgrading.
Running the ctmping Utility
This procedure describes how to run the ctmping utility, which enables you to test, configure, and determine the connection and availability between a Control-M/Server and its Agents or Agentless Hosts.
Begin
-
Do one of the following:
-
UNIX: Log in to a Control-M/Server account.
-
Windows: Open a command prompt where Control-M/Server is installed.
-
-
Type the following command:
ctmping -HOSTID <hostName> [ -HOSTTYPE <REGULAR|REMOTE> ]
-
[ -HOSTID <hostName> [ -HOSTTYPE <REGULAR|REMOTE> ] ]
-
[ -FILE <inputFile> ]
-
[ -DISCOVER <y|n>]
-
[ -DEBUG <debugLevel> ]
-
[ -QUIET ]
-
[ -FULLDETAILS ]
-
ctmping Parameters
The following table describes the ctmping utility parameters.
Parameter |
Description |
---|---|
-HOSTID |
Defines the Host name of the Agent or Agentless Host that is pinged (tested). You must define at least one host ID must every time you run the ctmping utility. You can define additional host IDs can to test communication with multiple Agents in a single run of the utility. |
-HOSTTYPE |
Describes the type of host that is being pinged.
If you do not specify a HOSTTYPE:
If you specify a HOSTTYPE:
|
-FILE |
Defines the full pathname for a file that contains a list of hosts to be pinged. Each line in the specified file contains:
The delimiter between the name and the HOSTTYPE is a blank or any number of blank spaces. Where the host type is not specified, a discovery process attempts to determine the type to be used. See -HOSTTYPE above. Assume the following hosts must be pinged: Name Type dime not specified comet Agent mars Agentless Host The text below specifies the above details in a file: dime(HOSTTYPE is not specified) comet REGULAR mars REMOTE |
-DISCOVER |
Determines whether to update the database.
|
-DEBUG |
Determines whether to activate a debug trace at the level defined Valid Values: 0–5 Default: 0 Performance is slower when operating in debug mode. BMC recommends that you activate debug mode only when requested by Technical Support and use the specified level. |
-QUIET |
Suppresses display of utility output. |
-FULLDETAILS |
Generates a status report of the communication parameters of each specified Agent or Agentless Host. Where an Agent is unavailable, the report displays the reason why the Agent is unavailable. Where a Agentless Host is available it displays the connection information. |
ctmping Examples
-
To connect and perform a communication test with Agent Jacqueline, run the following command:
ctmping -hostid Jacqueline
The response is:
Agent: Jacklin is alive
-
To attempt to connect and test communication with Agent Diana (that is currently down), run the following command:
ctmping -hostid Diana
The response is:
Agent: Diana, Msg: Agent not available.
Add it to the database? y/n:
-
To connect and test communication with the Agent Jacqueline and collect configuration information needed for the discovery process, run the following command:
ctmping -hostid Jacqueline -discover y
The response is:
Agent: Jacklin is alive
-
To connect and test communication with the Agent Jacqueline and generate a debug trace without displaying the results on screen, run the following command:
ctmping -hostid Jacqueline -debug 1 -quiet
Only the return code of the utility indicates if it was successful. The debug trace information is saved to the following file:
~<controlm_owner>/ctm_server/proclog/ping<PID>_<PID>.log
where PID is the process identity number.
-
The Agents comet and mars have been configured to connect to Agentless Host dime. To generate a report showing the result of the test and the connection details, run the following command:
ctmping -hostid dime -hosttype remote -fulldetails
The following response is displayed:
CopyRemote host [dime] is available through Agent [comet]
Connection protocol : SSH
Port number : 22
Encryption method : REMEDY
Compression : No
Remote host [dime] is available through Agent [mars]
Connection protocol : SSH
Port number : 22
Encryption method : REMEDY
Compression : NoAssume the hostid_list.txt text file contains the full path to the following host IDs:
local Agent Jacqueline
Agentless Host dime
regular Agent Diana
-
To generate a report showing the result of pinging the host IDs specified in hostid_list.txt, specify the following command:
ctmping -file ~<controlm_owner>/ctm_server/hostid_list.txt
The response is:
Agent : Jacklin is alive
Remote host : dime is alive
Agent: Diana Msg: Agent not available