Control-M/EM Host Configurations

The em-configure-hostname and em-configure-db utilities enable you to update the Control-M/EM host name configuration and reconfigure the database server connection data in the configuration files and the database in the following scenarios:

  • The em-configure-hostname utility changes the Control-M/EM server components' hostname value only. The utility does not alter the logical names of Control-M components.

  • The em-configure-hostname utility does not change the operating system machine hostname. For this change, contact your IT department.

Hostname Changes

Your administrator might need to change the Control-M/EM hostname for technical reasons or maintenance purposes. After this occurs, you must also update the hostname in the database and configuration files, to avoid inconsistencies with the hostname configuration values in the database, which is necessary for Control-M/EM to function properly.

The following diagram demonstrates a hostname replacement when a single Control-M/EM installation is associated with a remote database that is installed on a separate machine. For information on how to perform the hostname replacement in this scenario, see Replacing the Hostname in a Remote Database.

The following diagram demonstrates a hostname replacement when a multi-Control-M/EM installation is associated with a remote database that is installed on a separate machine. For information on how to perform the hostname replacement in this scenario, see Replacing the Hostname in a Remote Database.

The following diagram demonstrates a hostname replacement when the Control-M/EM database is hosted on the same machine as the single Control-M/EM host. For information on how to perform the hostname replacement in this scenario, see Replacing the Hostname in a Database on a Control-M/EM Host.

The following diagram demonstrates a hostname replacement when the Control-M/EM database is hosted on the same machine as one of the Control-M/EM hosts in a multi-Control-M/EM installation. For information on how to perform the hostname replacement in this scenario, see Replacing the Hostname in a Database on a Control-M/EM Host.

Replacing the Hostname in a Remote Database

This procedure describes how to use the em-configure-hostname utility to replace the hostname in the database and configuration files when Control-M/EM is associated with a remote database that is installed on a separate machine and the Control-M/EM installation host name is modified, as described in Hostname Changes.

Begin

  1. Stop Control-M processes by doing the following:

    If you have multiple Control-M/EM instances installed, stop the processes in the secondary installation environment and then stop the processes in the primary and Control-M/EM Distributed installation environments.

    • Full Installation: Run the following commands in the following order:

      1. stop_em [--silent]

      2. shut_ca

      3. shut_ctm

      4. shut_kafka

    • Control-M/EM Installation: Run the following command:

      stop_em –killKafka [--silent]

  2. On all hosts where the hostname was changed, from a command line, type the following:

    • UNIX: em em-configure-hostname.sh [-silent]

    • Windows: em-configure-hostname.bat [-silent]

  3. Restart Control-M processes by doing the following:

    If you have multiple Control-M/EM instances installed, start the processes in the primary and Control-M/EM Distributed installation environments and then start the processes in the secondary installation environment.

    • Full Installation: Run the following commands in the following order:

      1. start_ctm

      2. start_ca

      3. start_em

    • Control-M/EM Installation: Run the following command:

      start_em

Replacing the Hostname in a Database on a Control-M/EM Host

This procedure describes how to use the em-configure-hostname and em-configure-db utilities to replace the hostname in the database and configuration files when the Control-M/EM database is installed on a Control-M/EM host and the hostname is modified, as described in Hostname Changes.

Begin

  1. Stop Control-M processes by doing the following:

    If you have multiple Control-M/EM instances installed, stop the processes in the secondary installation environment and then stop the processes in the primary and Control-M/EM Distributed installation environments.

    • Full Installation: Run the following commands in the following order:

      1. stop_em [--silent]

      2. shut_ca

      3. shut_ctm

      4. shut_kafka

    • Control-M/EM Installation: Run the following command:

      stop_em –killKafka [--silent]

  2. On the Control-M/EM host where the database is installed, from a command line, type the following:

    • Oracle or PostgreSQL database:

      • UNIX: em em-configure-db.sh [-host <new db host name>] [-silent]

      • Windows: em-configure-db.bat [-host <new db host name>] [-silent]

    • MSSQL database:

      • UNIX: em em-configure-db.sh [-service <new db service name>] [-silent]

      • Windows: em-configure-db.bat [-service <new db service name>] [-silent]

    The -host parameter (which defines the database host) or -service parameter (which defines the database service) is required when you have more than one Control-M/EM host (see the Multi-Control-M/EM Installation diagram), but not when you have a single Control-M/EM host (see the Single Control-M/EM Host diagram).

    • You might need additional parameters if additional database server configurations were changed. For a list of all available parameters, see em-configure-db Parameters.

    • Any parameters that are not included in the command are set to their existing values.

  3. If you have multiple Control-M/EM hosts, repeat the em-configure-db command on all other hosts.

  4. On all Control-M/EM hosts where the hostname was changed, from a command line, type the following:

    • UNIX: em em-configure-hostname.sh [-silent]

    • Windows: em-configure-hostname.bat [-silent]

  5. For a full installation with a PostgreSQL database, update the hostname for the following additional Control-M components:

  6. Restart Control-M processes by doing the following:

    If you have multiple Control-M/EM instances installed, start the processes in the primary and Control-M/EM Distributed installation environments and then start the processes in the secondary installation environment.

    • Full Installation: Run the following commands in the following order:

      1. start_ctm

      2. start_ca

      3. start_em

    • Control-M/EM Installation: Run the following command:

      start_em

Hostname Restore During Disaster Recovery

Disaster Recovery scenarios involve moving your Control-M/EM environment to a stand-by Control-M/EM environment, which contain replicated data or migrated data. Even though production and user data are up-to-date in the stand-by Control-M/EM environment, the host configuration data refers to the original environment, which is not in use at recovery time. This data contains the original hostname in various database tables, such as CONFIG_HA. The em-configure-hostname and em-configure-db utilities enable you to update the configuration data to the values of the stand-by machine, as described in Restoring Hostname Configuration Data During Disaster Recovery.

The following diagram demonstrates a disaster recovery process with database replication:

The following diagram demonstrates a disaster recovery process with Control-M/EM disk replication:

The following diagram demonstrates a disaster recovery process that uses util for export/import:

  • The source and destination database must be from the same database vendor and version.

  • The default administrator user that logs in to the Control-M/EM client is not changed when data is migrated from the primary site to the Disaster Recovery site.

  • If you use the BMC_EM_PROFILE_NAME environment variable, define it on the stand-by machine.

    If you do not use BMC_EM_PROFILE_NAME, ensure that it does not exist on the stand-by machine.

Restoring Hostname Configuration Data During Disaster Recovery

This procedure describes how to use the em-configure-hostname and em-configure-db utilities to restore configuration data during disaster recover, as described in Hostname Restore During Disaster Recovery.

Begin

  1. Stop Control-M processes by doing the following:

    If you have multiple Control-M/EM instances installed, stop the processes in the secondary installation environment and then stop the processes in the primary and Control-M/EM Distributed installation environments.

    • Full Installation: Run the following commands in the following order:

      1. stop_em [--silent]

      2. shut_ca

      3. shut_ctm

      4. shut_kafka

    • Control-M/EM Installation: Run the following command:

      stop_em –killKafka [--silent]

  2. On the primary Control-M/EM host, from a command line, type the following:

    • UNIX: em em-configure-db.sh [changed parameters]

    • Windows: em-configure-db.bat [changed parameters]

    For a list of available parameters, see em-configure-db Parameters.

  3. Run the em-configure-db command on the secondary host and on all Control-M/EM Distributed hosts that are connected to the same database.

  4. On the active Control-M/EM host (typically the primary host), from a command line, type the following:

    • UNIX: em em-configure-hostname.sh [-silent]

    • Windows: em-configure-hostname.bat [-silent]

  5. Repeat the em-configure-hostname command on other hosts where the hostname was changed, including the secondary host and all Control-M/EM Distributed hosts.

  6. Restart Control-M processes by doing the following:

    If you have multiple Control-M/EM instances installed, start the processes in the primary and Control-M/EM Distributed installation environments and then start the processes in the secondary installation environment.

    • Full Installation: Run the following commands in the following order:

      1. start_ctm

      2. start_ca

      3. start_em

    • Control-M/EM Installation: Run the following command:

      start_em

Control-M/EM Database Hostname or Parameter Changes

Your administrator might need to change connection parameters between Control-M/EM and the Control-M/EM database, such as if you move the database server to another host or if you make a change in a parameter.

After this occurs, you must use the em-configure-db utility to update connection data in the database tables and in the configuration files (such as DBU_params.dat file), which enables Control-M/EM processes to connect to the updated database server, as described in Rehosting the Database Server. For a list of the database parameters that you can change, see em-configure-db Parameters.

The utility also updates the data stored in the Control-M/EM database if you executed a data import to the new database that stores the old server connection data. The source and destination database must be from the same database vendor.

The source and destination database must be from the same database vendor and version.

Rehosting the Database Server

This procedure describes how to use the em-configure-db utility to update connection data in the database tables and in the configuration files when parameters are changed for the connection between Control-M/EM and the Control-M/EM database, as described in Control-M/EM Database Hostname or Parameter Changes.

Begin

  1. Stop Control-M processes by doing the following:

    If you have multiple Control-M/EM instances installed, stop the processes in the secondary installation environment and then stop the processes in the primary and Control-M/EM Distributed installation environments.

    • Full Installation: Run the following commands in the following order:

      1. stop_em [--silent]

      2. shut_ca

      3. shut_ctm

      4. shut_kafka

    • Control-M/EM Installation: Run the following command:

      stop_em –killKafka [--silent]

  2. On the Control-M/EM database host, from a command line, type the following:

    • UNIX: em em-configure-db.sh [relevant parameters]

    • Windows: em-configure-db.bat [relevant parameters]

    For a list of available parameters, see em-configure-db Parameters.

  3. Run the em-configure-db command on the secondary host and on all Control-M/EM Distributed hosts that are connected to the same database.

  4. Restart Control-M processes by doing the following:

    If you have multiple Control-M/EM instances installed, start the processes in the primary and Control-M/EM Distributed installation environments and then start the processes in the secondary installation environment.

    • Full Installation: Run the following commands in the following order:

      1. start_ctm

      2. start_ca

      3. start_em

    • Control-M/EM Installation: Run the following command:

      start_em

em-configure-db Parameters

The following table describes the available em-configure-db input parameters.

All parameters are followed by a space and then a value, except for the -silent parameter.

Parameter

Database Type

Description

-silent

ALL

Runs the utility in silent mode, with no need for interactive input.

If you do not include this parameter in the command line, parameter values that are going to change appear, and you are prompted to approve the changes.

-host

ALL

Defines the new hostname of the database endpoint.

-port

ALL

Defines the new port number of the database endpoint.

-dbname

ALL

Defines the new database schema name.

-owner

ALL

Defines the new database owner name.

This parameter is relevant only in Database Rehost scenarios.

-password

ALL

Defines the dbo password.

This parameter is relevant only in Database Rehost scenarios.

-password_file

ALL

Defines the full path to a password file.

This parameter is an alternative to specifying the dbo password.

This parameter is relevant only in Database Rehost scenarios.

-service

MSSQL

Defines the new database service name.

-data_file_path

MSSQL

Defines the full path to the new data file location.

-log_file_path

MSSQL

Defines the full path to the new database log file location.

-datafile_path

Oracle

Defines the full path to the new datafile location.

Virtual or Alias Control-M/EM Hostname Setup

A virtual or alias Control-M/EM host setup is used to support a cluster configuration or when you want to use a virtual hostname that is different from the machine hostname. The em-configure-hostname utility enables you to update the virtual hostname in the database and configuration files with the value of the BMC_EM_PROFILE_NAME environment variable, as described in Setting a Virtual or Alias Hostname in the Database and Configuration Files.

The following diagram demonstrates this setup when a DNS alias is configured for multiple hosts in a cluster configuration:

The following diagram demonstrates this setup when multiple hosts have different profile names:

Differing Profile Names

Setting a Virtual or Alias Hostname in the Database and Configuration Files

This procedure describes how to use the em-configure-hostname utility to update the virtual hostname in the database and configuration files with the value of the BMC_EM_PROFILE_NAME environment variable.

Before You Begin

Ensure that the BMC_EM_PROFILE_NAME environment variable is set with the relevant value.

Begin

  1. Stop Control-M processes by doing the following in both the primary and the Control-M/EM Distributed installation environments:

    • Full Installation: Run the following commands in the following order:

      1. stop_em [--silent]

      2. shut_ca

      3. shut_ctm

      4. shut_kafka

    • Control-M/EM Installation: Run the following command:

      stop_em –killKafka [--silent]

  2. On all Control-M/EM hosts where the virtual hostname is used, from a command line, type the following:

    • UNIX: em em-configure-hostname.sh [-silent]

    • Windows: em-configure-hostname.bat [-silent]

  3. Restart Control-M processes by doing the following in both the primary and the Control-M/EM Distributed installation environments:

    • Full Installation: Run the following commands in the following order:

      1. start_ctm

      2. start_ca

      3. start_em

    • Control-M/EM Installation: Run the following command:

      start_em

To cancel this Virtual or Alias Hostname configuration, delete the BMC_EM_PROFILE_NAME environment variable and then perform the same procedure described above.

Control-M/EM Web URL Configuration

You might need to set a web URL that is different from the default web URL provided for Control-M/EM. For example, if your Control-M/EM runs in a cloud environment with a different URL, or if you want to change the URL used by Control-M/EM to a fully qualified domain name (FQDN).

After you set the new web URL, the restore_host_config utility with the –interface_name switch enables you to update the web URL in the database and configuration files, as described in Setting the Web URL in the Database and Configuration Files.

The following diagram demonstrates Web URL configuration when a DNS alias is mapped to multiple hosts:

The following diagram demonstrates Web URL configuration in a cloud environment:

Cloud Configuration

Setting the Web URL in the Database and Configuration Files

This procedure describes how to use the restore_host_config utility to update Control-M/EM configuration in the Control-M/EM database and configuration files after you set a new web URL for Control-M/EM. For this action, you must provide a password to connect to the Control-M/EM database.

Begin

  1. Stop Control-M processes by doing the following in the secondary installation environment and then in the primary and Control-M/EM Distributed installation environments:

    • Full Installation: Run the following commands in the following order:

      1. stop_em [--silent]

      2. shut_ca

      3. shut_ctm

      4. shut_kafka

    • Control-M/EM Installation: Run the following command:

      stop_em –killKafka [--silent]

  2. From a command line type one of the following:

    • UNIX: em restore_host_config –interface_name [-silent] -name <new web URL> [-password <dbo password>] / [-password_file <file_path>]

    • Windows: restore_host_config –interface_name [-silent] -name <new web URL> [-password <dbo password>] / [-password_file <file_path>]

    • <new web URL> is the new web URL to publish.

    • If the -silent flag is not specified in the command line and you do not provide a required parameter, the script prompts you for the missing values during execution.

    • The script must also be executed on the secondary or each Control-M/EM Distributed installation where the web URL name needs to be set or changed.

  3. Restart Control-M processes by doing the following in the primary and Control-M/EM Distributed installation environments and then in the secondary installation environment:

    • Full Installation: Run the following commands in the following order:

      1. start_ctm

      2. start_ca

      3. start_em

    • Control-M/EM Installation: Run the following command:

      start_em

Control-M/Server Hostname Update

Your Control-M administrator might need to change the Control-M/Server hostname. After this occurs, the restore_host_config utility with the -rehost_ctm switch enables you to associate Control-M/EM with the new Control-M/Server hostname by updating Control-M/EM database and configuration files, as described in Updating a Control-M/Server Hostname in Control-M/EM Database.

The following diagram demonstrates a Control-M/Server hostname update:

Updating a Control-M/Server Hostname in Control-M/EM Database

This procedure describes how to use the restore_host_config utility to update Control-M/EM configuration in the Control-M/EM database and configuration files after you change the Control-M/Server hostname. For this action, you must provide a password to connect to the Control-M/EM database.

Begin

  1. Stop Control-M processes by doing the following in the secondary installation environment and then in the primary and Control-M/EM Distributed installation environments:

    • Full Installation: Run the following commands in the following order:

      1. stop_em [--silent]

      2. shut_ca

      3. shut_ctm

      4. shut_kafka

    • Control-M/EM Installation: Run the following command:

      stop_em –killKafka [--silent]

  2. From a command line type one of the following:

    • UNIX: em restore_host_config -rehost_ctm [-silent] [-old_host <old host name>] [-new_host <new host name>] [-password <dbo password>] / [-password_file <file_path>]

    • Windows: restore_host_config -rehost_ctm [-silent] [-old_host <old host name>] [-new_host <new host name>] [-password <dbo password>] / [-password_file <file_path>]

    If the -silent flag is not specified in the command line and you do not provide a required parameter, the script prompts you for the missing values during execution.

  3. Restart Control-M processes by doing the following in the primary and Control-M/EM Distributed installation environments and then in the secondary installation environment:

    • Full Installation: Run the following commands in the following order:

      1. start_ctm

      2. start_ca

      3. start_em

    • Control-M/EM Installation: Run the following command:

      start_em

Secondary High-Availability Component Removal

Your Control-M administrator might need to uninstall the secondary high-availability Control-M/EM installation component. For example, in one of the following scenarios:

  • You want to move the Control-M/EM secondary environment to a different machine.

  • You no longer want to work with High-Availability configuration.

  • Your Control-M/EM secondary environment is no longer available.

You might also want to set the primary environment as the secondary environment.

After you uninstall the secondary environment, the restore_host_config utility with the -remove_secondary switch enables you to update Control-M/EM configuration in the Control-M/EM database and configuration files, as described in Removing the Secondary High-Availability Installation Component Data in the Control-M/EM Database.

The following diagram demonstrates the removal of a secondary High Availability Control-M/EM installation:

Removing the Secondary High-Availability Installation Component Data in the Control-M/EM Database

This procedure describes how to use the restore_host_config utility to update Control-M/EM configuration in the Control-M/EM database and configuration files after you uninstall the secondary high-availability Control-M/EM installation component. For this action, you must provide a password to connect to the Control-M/EM database.

Begin

  1. Stop Control-M processes by doing the following in the secondary installation environment and then in the primary and Control-M/EM Distributed installation environments:

    • Full Installation: Run the following commands in the following order:

      1. stop_em [--silent]

      2. shut_ca

      3. shut_ctm

      4. shut_kafka

    • Control-M/EM Installation: Run the following command:

      stop_em –killKafka [--silent]

  2. From a command line type one of the following:

    • UNIX: em restore_host_config -remove_secondary [-silent] [-switch_primary_to_secondary] [-password <dbo password>] / [-password_file <file_path>]

    • Windows: restore_host_config -remove_secondary [-silent] [-switch_primary_to_secondary] [-password <dbo password>] / [-password_file <file_path>]

    • The optional -switch_primary_to_secondary flag switches between the secondary and primary environments.

    • If you want to remove the secondary environment without switching between the secondary and primary environments, ensure that your primary environment is active.

      If the primary environment is not active and the -switch_primary_to_secondary is not used, the script exits without removing, and an error message appears.

    • If the -silent flag is not specified in the command line and you do not provide a password or password file, the script prompts you for the missing values during execution.

  3. Restart Control-M processes by doing the following in the primary and Control-M/EM Distributed installation environments and then in the secondary installation environment:

    • Full Installation: Run the following commands in the following order:

      1. start_ctm

      2. start_ca

      3. start_em

    • Control-M/EM Installation: Run the following command:

      start_em