ctmhostmap

The ctmhostmap utility manages the mapping of remote host computers to Agents and the conversion of Control-M/Agents to remote host computers. This utility can be run from the command line, or by using the Control-M Configuration Manager.

Each computer that is defined as a remote host is listed in the Control-M/Server database. The ctmhostmap utility enables you to manage the entries in the database.

Running the ctmhostmap Utility

This procedure describes how to run the ctmhostmap utility, which enables you to manage the mapping of remote host computers to Agents and the conversion of Control-M/Agents to remote host computers.

Begin

  1. 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.

  2. Type one of the following commands:

    • ctmhostmap -action add [-force] -host <remoteHost>
      -Agent <AgentsList>
      -protocol SSH|WMI [-sshport <SSHportNumber>
      -sshalg AES|DES|3DES
      -compression <SSH compression Y/N>] [-outputdir <WMIoutputDirectory>]

    • ctmhostmap -action update -host <remoteHost> [-Agent <AgentsList>]
      [-protocol SSH|WMI]
      [[-sshport <SSHportNumber>
      -sshalg AES|DES|3DES
      -compression <SSH compression Y/N>] [-outputdir <WMIoutputDirectory>]]

    • ctmhostmap -action delete -host <remoteHost>

    • ctmhostmap -action list [-host <remoteHost>]

    • ctmhostmap help

For more details on the ctmhostmap parameters, see ctmhostmap Parameters.

ctmhostmap Actions

The following table describes the actions in the ctmhostmap utility:

Action

Description

add

Specifies the details of the remote host computer that is being defined in the Control-M/Server database.

Control-M/Server discovers the specified computer using default remote host map settings if the following is specified without further parameters:

ctmhostmap -action add -host <remoteHost>

Separate the Agent names with a semicolon (;) when adding more than one Agent.

UNIX: If more than one Control-M/Agent is being added, the entire list must be enclosed in quotation marks.

"jupiter;andromeda;taurus"

update

Modifies the details of the specified remote host computer in the Control-M/Server database.

Separate the Agent names with a semicolon when adding more than one Agent.

UNIX: If more than one Control-M/Agents are being added, the entire list must be enclosed in quotation marks.

"jupiter;andromeda;taurus"

Control-M/Server replaces the existing settings of a remote host with the settings of Default if the following command is specified:

ctmhostmap -action update -host "<Default>"

delete

Deletes the details of the specified remote host computer in the Control-M/Server database.

list

Lists the details of the specified remote host computer in the Control-M/Server database. The resultant list includes all remote host computers and their statuses, except when list is specified with -host (see description below).

help

Displays the usage of the ctmhostmap utility.

ctmhostmap Parameters

The following table lists the ctmhostmap utility parameters:

Parameter

Description

-force

Overrides a regular Agent computer that has the same name as the specified computer.

This option is used in order to convert regular Agent to remote host.

For more information, see Defining a remote host.

-host

Specifies the name of the remote host computer or <Default>. The name of the host cannot exceed 50 characters.

This parameter is:

  • mandatory when specified with add, update, and delete

  • optional when specified with list

<Default > is not applicable if the delete action is specified.

If -host is specified with -list, the remote host is not <Default>, and the status is not Discovering, then the details of the specified remote host are displayed.

The output includes the following:

  • all the remote host definition parameter values

  • remote host status

  • status of each Agent, showing which remote host is defined to be available through it

To view the "Default Remote Settings", specify the following command:

ctmhostmap -action list -host "<Default>"

-Agent

Lists Agent names, separated by semi-colons (;). For UNIX: Enclose the entire list in quotation marks.

This parameter is:

  • mandatory when specified with add

  • optional when specified with update

To list more than one Control-M/Agent, the entire list must be separated by semi-colons:

  • Windows: pluto;mars;saturn

  • UNIX: "pluto;mars;saturn".

-protocol

Indicates which protocol is used by the Agent to execute jobs on the remote host computer.

Valid values:

  • SSH: Secure Shell (SSH) for UNIX or Windows computers

  • WMI: Windows Management Instrumentation (WMI) for Windows computers

If SSH is specified, then the following parameters must be specified:

  • -sshport: Specifies the SSH port number that the SSH daemon is listening to on the remote host computer. Valid value: 22 or an integer from 1024 through 65535

  • -sshalg: Indicates which SSH encryption algorithm is being used.

    Valid values:

    • AES

    • DES

    • 3DES

  • -compression:

    Valid values:

    • Y: compression is used

    • N: compression is not used

  • -outputdir: Indicates the directory used for the OUTPUT files created by jobs that have been submitted. The name of the outputdir cannot exceed 1,024 characters.

    Configure the specified directory on the remote host as a shared directory, with the shared name of OUTPUT.

If WMI is specified, then the outputdir parameter must be specified.

The outputdir must either be prefaced with double back-slashes (for example d:\\output_dir), or be enclosed with quotation marks (for example "d:\output_dir").

ctmhostmap Examples

The following are examples of the ctmhostmap utility commands:

  • To add remote host mars to the Control-M/Server database, mapped through Control-M/Agents pluto, neptune, and venus, using SSH protocol, run the following command:

    ctmhostmap -action add -host mars -Agent "pluto;neptune;venus" -protocol ssh -sshport 54 -sshalg des -compression N

  • To add remote host saturn, mapped through Control-M/Agent jupiter, using WMI protocol, run the following command:

    ctmhostmap -action add -host saturn -Agent jupiter -protocol wmi -outputdir d:\\ctm\\data

  • As described above, but the OUTPUT directory contains spaces. Run the following command:

    ctmhostmap -action add -host saturn -Agent jupiter -protocol wmi -outputdir "c:\ctm eur\data"

  • To add remote host saturn, mapped through Control-M/Agents jupiter, andromeda, and taurus using SSH protocol, run the following command:

    ctmhostmap -action add -host mars -Agent "jupiter;andromeda;taurus" -protocol ssh -sshport 22 -sshalg AES -compression N

  • When modifying an existing entry, only the parameters that are being updated are mandatory. To change the SSH port number of remote host mars from 54 to 48, and to change the SSH algorithm from DES to 3DES, run the following command:

    ctmhostmap -action update -host mars -sshport 48 -sshalg 3des

  • To delete remote host mars from the Control-M/Server database, specify the following command:

    ctmhostmap -action delete -host mars

  • To display a list of remote hosts, run the following command:

    ctmhostmap -action list

    The following report is displayed:

    Copy 
    Remote Host          Status
    orion                Available
    taurus               Unavailable
    pegasus              Unavailable
    Action ‘list’ ended successfully.

  • To display the details of remote host orion, run the following command:

    ctmhostmap -action list -host orion

    The following report is displayed:

    Copy 
    Remote host ‘orion’ settings:
    Protocol        : SSH
    Port Number     : 22
    Encryption      : REMEDY
    Compression     : NO
    Agents          : (comet) (meteor) (cyborg)
    Remote Host Status      : Available
    Agents Statuses         : (comet: Available) (meteor: Available) (cyborg: Available)
    Action ‘list’ ended successfully.