restore_host_config

The Control-M/EM restore_host_config utility enables you to update the host name configuration in the following situations:

• Host name data restore in Disaster Recovery sites.

• Local host name changes.

• Interface name (public host name) definition in cloud computers.

• Alternative host name (profile name) utilization.

• Database server communication parameter property updates.

• Control-M/Server host name updates.

• Removing the high-availability secondary host data.

Restoring Hostname and Configuration Data During Disaster Recovery

This procedure describes how to restore the hostname and configuration data in the database during disaster recovery when moving to the stand-by Control-M/EM environment, which contains replicated data. Although production and user data are up-to-date, the host and environment 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, and must be updated to the post installation values of the stand-by machine.

Begin

1. Stop all Control-M/EM processes in the secondary installation environment and then in the primary and distributed installation environments.

2. From a command line type the following:

   • UNIX/Linux: em restore_host_config [-silent] -dr [[-old_host <old (Site A) host name>] or [-primary/secondary]] [[-password <dbo password>] or [-password_file [<file_path>]]]

   • Windows: restore_host_config [-silent] -dr [[-old_host <old (Site A) host name>] or [-primary/secondary]] [[-password <dbo password>] or [-password_file [<file_path>]]]

   • <old (Site A) host name> is the host name of the disaster site. (Multiple distributed environments)

   • If the script cannot detect the old configuration in the template file, the -primary or -secondary flags can be used alternatively (instead of <-old_host>).

   • If the -silent flag is not specified and optional parameters are not defined in the command line, the script asks for the relevant input interactively.

   • The -old_host flag is not required in the following configurations:

     • A single Control-M/EM installation.

     • Control-M/EM High Availability environment.

     • Control-M/EM Distributed environment.

   • The -old_host flag must be used when there are more than one additional environments (distributed) installed on several different computers.

   • The script must be executed on all different installations (primary/secondary/distributed) and always start with the active installation.

   • After you move Control-M/EM to the disaster recovery site and run the restore_host_config utility, you must copy the file <EM_HOME>/ini/fips/db_enc_key.txt from the main site to the disaster recovery site, into the same path.

   Before replication, the hostname value is ORIG_HOST in the original environment and STDBY_HOST in the stand-by environment. After replication, the hostname value in the stand-by host is ORIG_HOST and Control-M/EM cannot function. At recovery time, the hostname value in the stand-by environment must be reset to STDBY_HOST.

Replacing the Local Hostname in the Database and Configuration Files

This procedure describes how to replace the local hostname in the database and configuration files when the Control-M/EM installation host name is modified by the system administrator for technical/maintenance reasons. Due to inconsistencies with the hostname configuration values in the database, Control-M/EM might not function properly.

Begin

1. Stop all Control-M/EM processes in the secondary installation environment and then in the primary and distributed installation environments.

2. From a command line type the following:

   • UNIX/Linux: em restore_host_config -rehost [-silent] [[-old_host <old host name>] or [-rename_remote_main_data]] [-db_host <main installation host name>] [[-password <dbo password>] or [-password_file [<file_path>]]]

   • Windows: restore_host_config -rehost [-silent] [[-old_host <old host name>] or [-rename_remote_main_data]] [-db_host <main installation host name>] [[-password <dbo password>] or [-password_file [<file_path>]]]

   • <old host name> is the original host name of the modified site (If there is more than one Control-M/ EM environment.

   • The -rename_remote_main_data flag updates the main installation parameters, such as Naming Server host data, on a distributed or secondary installation environment's configuration files, after moving the main installation to a different host.

   • If the database server is local to the main installation host (such as a dedicated PostgreSQL) the <main installation host name> parameter must be used when running on distributed or secondary installations.

   • There is no need to specify any optional flag when there is only a single main installation. The script runs and is configured according to the default values.

   • If the database is dedicated to the local installation that runs on the same host (such as PostgreSQL database installed with Control-M/EM or Full Install), execute the utility in two separate phases, as follows:

     1. First execute the utility to update the configurations of PostgreSQL database communication parameters. Include the -reconf_db flag, as described in Reconfiguring the Database Server Connection Data. Provide the machine's new host name through the -host argument or through the interactive prompt.

     2. After the above execution completes successfully, run the utility again with the -rehost flag, as described in the current procedure.

   • If there are additional (secondary/distributed) installations on different computers, and the main (primary) computer hostname is modified, the script must be executed with the -rehost option on all secondary/distributed installations with the additional flag -rename_remote_main_data, to update the primary hostname in the configuration files.

   • If there are additional (secondary/distributed) installation on different computers, and the main (primary) machine host name is modified, and if the database is local to the primary installation (such as dedicated PostgreSQL), you must use the -db_host flag to connect to the database, using the new primary host name.

   • If the hostname of the secondary or of the single distributed installation is modified, you need to use the -rehost option on these installations with no optional flag.

   • If there are multiple distributed installations and any host name in one of these installations is modified,you need to use the -rehost option on the specific installation with the addition of the -old_host flag.

   • If the -silent flag is not specified and optional parameters are not defined in the command line, the script asks for the relevant input interactively.

   • The utility restore_host_config -rename_remote_main_data is not supported in Control-M/EM Distributed with Workload Archiving.

Setting the Interface Name in the Database and Configuration Files for Cloud Computers

This procedure describes how to set the interface name in the database and configuration files when Control-M/EM is running on a cloud environment. Cloud computers often switch published host (interface) name after being recycled. The new interface name value must be updated in configuration files, such as CONFIG_HA.ini and in the database tables such as CONFREG.

Begin

1. Stop all Control-M/EM processes in the secondary installation environment and then in the primary and distributed installation environments.

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

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

   • Windows: restore_host_config –interface_name [-silent] [-name <new interface name>] [[-password <dbo password>] or [-password_file [<file_path>]]]

   • <new interface name> is the new interface name to publish. This parameter cannot be defined on AWS computers.

   • If the -silent flag is not specified and optional parameters are not defined in the command line, the script asks for the relevant input interactively.

   • The -name flag can be specified to define a customized interface (published) host name, if it is not available to the software.

   • The script must be executed with this option on each High Availability or distributed installation where the interface name is modified.

Setting the Profile Name in the Database and Configuration Files for an Alternative/Virtual Host Name

This procedure describes how to set the profile name in the database and configuration files for environments that have a different interface than the local hostname.

This is primarily used for cluster configurations and utilizes the BMC_EM_PROFILE_NAME environment variable. The script updates all hostname configurations in the Control-M/EM database and configuration files with this value.

Begin

1. Stop all Control-M/EM processes in the primary and distributed installation environments.

2. From a command line type the following:

   • UNIX/Linux: em restore_host_config –profile_name [-silent] [-name <new profile name>] [-internal_only [-host_port] [-ctm_name] [-sync_files] [-clients]] [[-password <dbo password>] or [-password_file [<file_path>]]]

   • Windows: restore_host_config –profile_name [-silent] [-name <new profile name>] [-internal_only [-host_port] [-ctm_name] [-sync_files] [-clients]] [[-password <dbo password>] or [-password_file [<file_path>]]]

   • <new profile name> is the new profile name to configure. This parameter cannot be specified if the BMC_EM_PROFILE_NAME environment variable is already defined with the required name.

   • If the -silent flag is not specified and optional parameters are not defined in the command line, the script asks for the relevant input interactively.

   • If the environment is running with a local (dedicated) PostgreSQL database server, that requires modification to the database server host name, define the -reconf_db parameter and then define the -profile_name parameter.

   • If the setting is for the computer's internal communication processes only, then the -internal_only flag must be specified. Otherwise all communication configuration is affected by the new profile name. This might occur if the profile name is not configured with the DNS name of the computer. The following exception flags refer to rare usage cases where the -internal only flag is defined:

   • Use the -host_port flag when the CTL communication parameters, configured by the HostPort system parameter, need to be customized with the new profile name.

   • Use the -ctm_name flag when the Control-M/Server running on the specific host needs to be customized with the new profile name.

   • Use the -sync_files flag when there are distributed Control-M/EM installations on other hosts where the file synchronization needs to be customized with the new profile name.

   • To see specific details on the exception flag, define the -profile_name -internal_only -help flag.

Reconfiguring the Database Server Connection Data

This procedure describes how to reconfigure the database server connection data in the configuration files and the database, when the database server connection parameters are changed, such as moving the database server to a replicated server running on a different computer.

This option modifies the database connection data in the configuration files (such as DBU_params.dat file), enabling Control-M/EM processes to connect to the new server.

The script also updates the data stored in the Control-M/EM database if you executed a data import to the new database storing the old server connection data. The script supports all database server vendor types (PostgreSQL, Oracle, and MSSQL) that can connect to Control-M/EM.

Begin

1. Stop all Control-M/EM processes in the secondary installation environment and then in the primary and distributed installation environments.

2. From a command line type the following:

   • UNIX/Linux: em restore_host_config -reconf_db [-silent] [-host <new db host name>] [-port <new db port number>] [-service <new db service name>] [-dbname <new db schema name>] [-pg_existing_server <y/n>>] [-owner <new db owner name>] [-data_file_location <full path to new data file location>] [-log_file_location <full path to new db log file location>] [[-password <dbo password>] or [-password_file [<file_path>]]] [-always_on <y/n>]

   • Windows: restore_host_config -reconf_db [-silent] [-host <new db host name>] [-port <new db port number>] [-service <new db service name>] [-dbname <new db schema name>] [-pg_existing_server <y/n>] [-owner <new db owner name>] [-data_file_location <full path to new data file location>] [-log_file_location <full path to new db log file location>] [[-password <dbo password>] or [-password_file [<file_path>]]] [-always_on <y/n>]

   • The -pg_existing_server must be used for PostgreSQL databases.

     • The y value defines that the database server cannot be administered by the installation (Existing mode).

     • The n value defines that the database server can be administered by the installation (Dedicated mode).

   • If the -silent flag is not specified and optional parameters are not defined in the command line, the script asks for the relevant input interactively.

   • The script must run on all High Availability and Distributed installations connected to the same database.

   • The -data_file_location option is for Oracle and MSSQL databases.

   • The -log_file_location option is for MSSQL databases only.

   • The -always_on option is for MSSQL databases only.

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

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

This procedure describes how to update a Control-M/Server hostname in Control-M/EM database, after the Control-M/Server hostname is changed.

Begin

1. Stop all Control-M/EM processes in the secondary installation environment and then in the primary and distributed installation environments.

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

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

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

   If the -silent flag is not specified and optional parameters are not defined in the command line, the script asks for the relevant input interactively.

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

This procedure describes how to remove the secondary (inactive) high-availability installation component data in Control-M/EM database.

You might perform this procedure if the secondary installation was uninstalled.

Begin

1. Stop all Control-M/EM processes in the secondary installation environment and then in the primary and distributed installation environments.

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

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

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

   • The -switch_primary_to_secondary flag must be defined if the secondary 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 and optional parameters are not defined in the command line, the script asks for the relevant input interactively.