ctmhostmap

The ctmhostmap utility enables you to convert Remote Hosts to Agents and convert Agents to Remote Hosts. This utility can be run from the command line or the Control-M Configuration Manager (CCM).

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 map Remote Hosts to Agents and convert Agents to Remote Hosts.

Begin

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

  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 information, see ctmhostmap Parameters.

ctmhostmap Actions

The following table describes the ctmhostmap utility actions.

Action

Description

add

Specifies the details of the Remote Host that is being defined in the Control-M/Server database.

Control-M/Server discovers the specified host using the 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 you add more than one Agent.

UNIX: If you are want to add more than one Agent, you must enclose the entire list in " (quotation marks).

"jupiter;andromeda;taurus"

update

Modifies the details of the specified Remote Host in the Control-M/Server database.

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

UNIX: If you are want to add more than one Agent, you must enclose the entire list in " (quotation marks).

"jupiter;andromeda;taurus"

Control-M/Server replaces the existing settings of a Remote Host with the Default settings if the following command is specified:
ctmhostmap -action update -host "<Default>"

delete

Deletes the details of the specified Remote Host from the Control-M/Server database.

list

Lists the details of the specified Remote Host in the Control-M/Server database. The new list includes all Remote Hosts 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 an Agent computer that has the same name as the specified computer.

This option is used in order to convert an Agent to a Remote Host.

For more information, see Defining a Remote Host.

-host

Specifies the name of the Remote Host or <Default>. The hostname 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.

  • The Remote Host status.

  • The status of each Agent, showing which Remote Host is defined to be available through it.

To view the Default Remote Settings, type the following command:
ctmhostmap -action list -host "<Default>"

-Agent

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

UNIX: If you are want to add more than one Agent, you must enclose the entire list in " (quotation marks).

This parameter is:

  • Mandatory when specified with add.

  • Optional when specified with update.

  • Windows: pluto;mars;saturn

  • UNIX: "pluto;mars;saturn"

-protocol

Indicates which protocol is used by the Agent to execute jobs on the Remote Host.

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.

    Valid Value: 22, or an integer from 1,024 through 65,535.

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

    Valid Values:

    • AES

    • DES

    • 3DES

  • -compression:

    Valid values:

    • Y: Compress data.

    • N: Do not compress data.

  • -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 be prefaced with \\ (to backslashes), or enclosed with " quotation marks, for example d:\\output_dir or "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 Agents pluto, neptune, and venus, using an 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 Agent jupiter, using a 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 Agents jupiter, andromeda, and taurus, using an SSH protocol, run the following command:
    ctmhostmap -action add -host mars -Agent "jupiter;andromeda;taurus" -protocol ssh -sshport 22 -sshalg AES -compression N

  • When you modify an existing entry, only the parameters that you update are mandatory. To change the Remote Host mars SSH port number 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, run 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 appears:

    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 appears:

    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.