ctmping

The ctmping utility tests, configures, and reports on the connection and availability between Control-M/Server and Control‑M/Agents or remote host computers.

ctmping can be included in the Watchdog process. For more information, see Watchdog process parameters.

This utility can check if an Agent or remote host is down and, if required, register it in the database as unavailable. When the Agent or remote host again becomes available, the state is changed and information about it is gathered by a Control‑M/Server process.

You cannot ping the Agent if the Agent is upgrading. When the Agent becomes available again, then you can ping the Agent. 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 report on the connection and availability between Control-M/Server and Control‑M/Agents or remote host computers.

Begin

Do one of the following:
- UNIX: Log in to a Control-M/Server account
- Windows: Open a command prompt window 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 lists the ctmping utility parameters:

Parameter	Description
-HOSTID	Defines the Host name of the Agent or remote host computer to be pinged (tested). At least one Host ID must be specified for each run of the ctmping utility. Additional Host IDs can optionally be specified to enable a single run of this utility to test communication with more than one Agent computer.
-HOSTTYPE	Describes the type of computer that is being pinged. REGULAR: A computer that is registered as an Agent in the Control-M/Server database. Control-M/Agent is installed on this computer. REMOTE: A computer that is registered as a remote host in the Control-M/Server database. It is not necessary for a Control-M/Agent to be installed on this computer. A computer that has a Control-M/Agent installed on it, can also be registered as a remote host. If you do not specify a HOSTTYPE: If the host ID of the computer is already defined, the HOSTTYPE that was defined is used again If the host ID of the computer was not used previously, then REGULAR is used as the default In the event that the type is unknown, that is, still in host discovery state, the utility is unable to complete the request. Wait for the discovery process to complete, then run the utility again. If you specify a HOSTTYPE: If the host ID is already defined in Control-M/Server and it conflicts with the earlier definition (for example, it was defined earlier as REGULAR and you are now specifying REMOTE), then the utility will not be able to complete the request. If the intention was to convert the defined host type, then for more information about how to convert a computer from one type to another, see ctmhostmap and Host Groups. If the host ID is already defined in Control-M/Server and the HOSTTYPE being specified now is same as that of the earlier definition, then the utility will use the specified HOSTTYPE for the host ID. If the host ID has not been previously defined in Control-M/Server, then the utility will use the specified HOSTTYPE for the host ID.
-FILE	Defines the full path and name of a file containing a list of host computers to be pinged. Each line in the specified file contains: The name (host ID) of the Agent or remote host (mandatory) The HOSTTYPE (optional) The delimiter between the name and the HOSTTYPE is a blank or any number of blank spaces. Where the computer type is not specified, a discovery process attempts to determine the type to be used. See -HOSTTYPE above. Assume the following computers must be pinged: Name Type dime not specified comet Control-M/Agent mars remote host computer The text below specifies the above details in a file: dime(HOSTTYPE is not specified) comet REGULAR mars REMOTE
-DISCOVER	Indicates whether to update the database. Y: Update the database with information gathered by the utility N: Do not update the database If -DISCOVER is not specified, ctmping performs an automatic discovery, as follows: If an Agent is available: the Control-M/Server database is updated with the details of the Agent or remote host unavailable: for a new Agent or remote host in the Control-M/Server database, a message is displayed, asking if you want to add the discovered Agent to the Control-M/Server database Default: automatic discovery
-DEBUG	Activates a debug trace at the specified level. 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 remote host. Where an Agent is unavailable, the report displays the reason why the Agent is unavailable. Where a remote host is available it displays the connection information.

ctmping Examples

To connect and perform a communication test with the Agent Jacklin, specify the following command:

ctmping -hostid Jacklin

The response is:
Copy
```
Agent: Jacklin is alive
```
To attempt to connect and test communication with Agent Diana (that is currently down), specify the following command:

ctmping -hostid Diana

The response is:
Copy
```
Agent: Diana, Msg: Agent not available.
Add it to the database? y/n:
```
To connect and test communication with the Agent Jacklin and collect configuration information needed for the discovery process, specify the following command:

ctmping -hostid Jacklin -discover y

The response is:
Copy
```
Agent: Jacklin is alive
```
To connect and test communication with the Agent Jacklin and generate a debug trace without displaying the results on screen, specify the following command:

ctmping -hostid Jacklin -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

PID is the Process Identity number.
The Agents, comet and mars, have been configured to connect to remote host dime. To generate a report showing the result of the test and the connection details, specify the following command:

ctmping -hostid dime -hosttype remote -fulldetails

The following response is displayed:
Copy
```
Remote 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         : No
```
Assume the hostid_list.txt text file contains the full path to the following host IDs:

local Agent Jacklin

remote 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:
Copy
```
Agent : Jacklin is alive
Remote host : dime is alive
Agent: Diana Msg: Agent not available
```