Control-M/EM Upgrade

You can upgrade to Control-M/EM 9.0.22 for UNIX and Windows from version 9.0.20 and higher. Control-M clients must be upgraded after you upgrade Control-M/EM.

Control-M/EM is in Compatibility Mode after an upgrade. Compatibility Mode enables Control-M clients 9.0.19 and higher to be compatible with the upgraded Control-M/EM server but disables the new features. The new features are only available after you upgrade Control-M clients and then turn off Compatibility Mode. After you turn off Compatibility Mode, you cannot turn it back on and all Control-M clients must be upgraded to log in to Control-M.

The following procedures describe Control-M/EM upgrade process:

Upgrading Control-M/EM on UNIX
Upgrading Control-M/EM on Windows
Upgrading Control-M Client on Windows from the Full Installation Package
Upgrading Control-M Client on Windows from the Client Installation Package
Upgrading Control-M Client from the Control-M Welcome Page
Turning off Compatibility Mode

You can also downgrade Control-M/EM to the previous version, as described in Control-M/EM Downgrade.

Control-M/EM SSL Requirements

If Control-M/EM is configured for TCP mode, the Control-M/EM upgrade installs the default PKCS #12 archive file. If the CmsCommMode system parameter value is SSL or AUTO, with at least one Control-M/Server connected via SSL, then you must ensure the following:

You cannot upgrade Control-M/EM if you utilize SSL with a KDB keystore. You must deploy a PKCS #12 keystore before you upgrade to 9.0.22. You can convert a KDB keystore to a PKCS #12 keystore, as described in Converting a KDB to a PKCS #12 Keystore.
The security policy must be configured to the TLS 1.2 protocol before the upgrade.
If you installed Control-M/EM 9.0.20.205, you must disable SSL before you upgrade to 9.0.22.
ManageSSL and Manage_SSL_BYO: If the value of the message digest algorithm is sha1, it is upgraded to sha256. If the value of the certificates key length is 1,024, it is upgraded to 2,048.

For more information about security policy attributes, see Security Policies.

Compatibility Mode

Compatibility Mode allows users with previous versions of Control-M client to connect to the latest version of Control-M/EM server with the upgraded Control-M clients. However, when Compatibility Mode is on, new features are disabled in upgraded Control-M clients. This ensures system integrity during the transition to a higher version. After Compatibility Mode is turned off, the new features are enabled in the upgraded Control-M clients and the older clients are disconnected. Users that did not upgrade their Control-M clients cannot log in.

The following list describes Compatibility Mode guidelines:

Compatibility Mode On:
- You can connect Control-M client 9.0.20 and higher to other 9.0.22 environments.
- You cannot upgrade to 9.0.22 if the Compatibility version is 9.0.19 or lower.
- You cannot deploy the Agent or Application Pack9.0.22 packages.
Compatibility Mode Off:
- You can only connect Control-M client 9.0.22 to other 9.0.22 environments.
- You cannot downgrade Control-M to a version lower than 9.0.21 after you upgrade to Control-M 9.0.22 and turn off Compatibility Mode, since the password encryption method changes.
  
  After you upgrade to Control-M 9.0.22 and before you turn Compatibility Mode off, you can back up passwords with the following command:
  
  em util -U <username> -P <password> -export -type user -file user-exp-before-921.txt

The following table lists the features that are disabled in Control-M clients after you upgrade and Compatibility Mode is on.

Source Version	Disabled Features
9.0.20.xxx	Users Roles API Tokens System Settings IdP Authentication (SAML) Reference Folder SHA512 Encryption Algorithm
9.0.19.xxx	(Control-M Web only) User Views (Control-M Web only) Site Standards XML Validation 85-Character Hostname Limit Centralized Connection Profiles (Control-M Web only) Control-M MFT Enterprise RBA Authorizations 9.0.20.xxx Features

Control-M Client and Control-M/EM Server Compatibility Scenarios

The following table lists the different Control-M client and Control-M/EM server compatibility scenarios after you upgrade Control-M/EM server from the source (compatibility version) to the new target version.

Control-M/EM Server Source Version	Control-M/EM Server Target Version	Client Version	Result
9.0.20.xxx	9.0.21	9.0.20.xxx Compatibility Mode: On	Success
9.0.20.xxx	9.0.21	9.0.20.xxx Compatibility Mode: Off	Fail Reason: If Compatibility Mode is off, the client must be in the same major release as the server target version.
9.0.20.xxx	9.0.21	9.0.21 Compatibility Mode: On	Success

Control-M/EM Server Source Version

Control-M/EM Server Target Version

Client Version

Result

9.0.20.xxx

9.0.21

9.0.20.xxx

Compatibility Mode: On

Success

9.0.20.xxx

9.0.21

9.0.20.xxx

Compatibility Mode: Off

Fail

Reason: If Compatibility Mode is off, the client must be in the same major release as the server target version.

9.0.20.xxx

9.0.21

Compatibility Mode: On

Success

Turning off Compatibility Mode

This procedure describes how to turn off Compatibility Mode, which enables new features in upgraded clients.

After Compatibility Mode is turned off, users that did not upgrade their Control-M clients cannot log in.
After Compatibility Mode is turned off, you cannot turn it back on.

Begin

From the CCM, in the Manage tab, click Compatibility Mode.
Click I have read and understand.
Click Turn Off Compatibility Mode.

Control-M/EM server components are automatically restarted.

Upgrading Control-M/EM on UNIX

This procedure describes how to upgrade from Control-M/EM 9.0.20 and higher (Default and Distributed) to the latest version of Control-M/EM on UNIX. To upgrade multiple instances of Control-M/EM on several hosts with the same configuration, use the automatic installation, as described in this procedure.

The default upgrade is interactive and uses a GUI display. XServer must be running and configured with the DISPLAY environment variable. If you do not have XServer available, BMC recommends that you continue with the console upgrade or perform an automatic upgrade.

Before You Begin

Verify that your operating system and database software is compatible with the new version of Control-M/EM, as described in Control-M/EM UNIX System Requirements.
Verify that you meet the Java requirements, as described in Control-M External Java Installation.
If you upgrade Control-M in a cluster environment, see Control-M/EM UNIX Cluster Configuration.
Verify that the Control-M/EM database server is up.
Download the upgrade package, as described in Obtaining Control-M Installation Files.
Use the is_upgrade_ready utility to verify minimum upgrade requirements, as described in Verifying Upgrade Readiness. This enables you to resolve detected issues even days or weeks before the upgrade.
If your site uses SSL, verify that you meet the requirements, as described in Control-M/EM SSL Requirements.
If you have a Control-M/EM Distributed installation, you must upgrade the default Control-M/EM first and then upgrade the Distributed Control-M/EM. The Workload Archiving server is upgraded automatically during the Control-M/EM Distributed upgrade.
If you upgrade in a Full installation environment, you must do the following:
- Shut down both Control-M/EM and Control-M/Server before you upgrade.
- Upgrade Control-M/EM before you upgrade Control-M/Server.

Begin

Copy the upgrade files from the temporary installation directory to the host where Control-M/EM is installed.
Set your DISPLAY environment variable, as described in Setting Environment Variables in UNIX.
Navigate to the home directory and run the following command:

<source_path>/setup.sh
Do one of the following:
- Interactively Upgrade: Select Control-M/Enterprise Manager and continue with the on-screen instructions until the upgrade is complete.
- Automatically Upgrade: Create a parameter file and then run the automatic install in a non-interactive mode, as follows:
  1. Select Control-M/Enterprise Manager and continue with the on-screen instructions until the Summary window appears.
    
    There is no confirmation to shut down Control-M/EM processes. It is done automatically.
  2. Click Generate and select the location to create the XML parameter file.
  3. Click Yes to quit the upgrade.
    
    A confirmation message appears.
  4. Click Yes.
  5. Copy the automatic upgrade parameters file to a network location that is accessible to all hosts where you want to perform an automatic upgrade.
  6. Run the following command:
    
    <source_path>/setup.sh -silent <xml_path>/<filename.xml>
    
    The upgrade logs are in the following location:
    
    <$HOME>/BMCINSTALL/log/BMC_Control-M_Enterprise_Manager_<date-time>.log
    
    To ensure compatibility between older Control-M client versions, Control-M/EM is now in Compatibility Mode.
    
    Control-M/EM and Control-M clients are configured by default for HTTP. To secure your environment, BMC recommends that you change your configuration to HTTPS, as described in Zone 1 SSL Configuration.

Upgrading Control-M/EM on Windows

This procedure describes how to upgrade from Control-M/EM 9.0.20 (Default and Distributed) and higher to the latest version of Control-M/EM on Windows. If you want to install multiple instances of Control-M/EM on several hosts with the same configuration, use the automatic installation, as described in this procedure.

If Control-M/EM and Control-M/Server are installed on the same Windows host (including cluster), they must be installed on the same drive.

Before You Begin

Ensure that your operating system and database software is compatible with the new version of Control-M/EM, as described in Control-M/EM Windows System Requirements.
Verify that you meet the Java requirements, as described in Control-M External Java Installation.
If you install Control-M on a cluster environment, see Control-M/EM Windows Cluster Configuration.
If MSSQL 2016 and higher is installed on the same host as Control-M/EM, you must shut down the PolyBase service before you upgrade.
Verify that the Control-M/EM database server is up.
Download the upgrade package, as described in Obtaining Control-M Installation Files.
Use the is_upgrade_ready utility to verify minimum upgrade requirements, as described in Verifying Upgrade Readiness. This enables you to resolve detected issues even days or weeks before the upgrade.
If your site uses SSL, verify that you meet the requirements, as described in Control-M/EM SSL Requirements.
If you have a Control-M/EM Distributed installation, you must upgrade the default Control-M/EM first and then upgrade the Distributed Control-M/EM. The Workload Archiving server is upgraded automatically during the Control-M/EM Distributed upgrade.
If you upgrade in a Full installation environment, you must do the following:
- Shut down both Control-M/EM and Control-M/Server before you upgrade.
- Upgrade Control-M/EM before you upgrade Control-M/Server.

Begin

Log in to the host with a user ID that has Administrator permissions.
Copy the upgrade files from the temporary installation directory to the host where Control-M/EM is installed.
From a command prompt window, type the following:

<source_path>\setup.exe.
Do one of the following:
- Interactively Upgrade: Select Control-M/Enterprise Manager and continue with the on-screen instructions until the upgrade is complete.
- Automatically Upgrade: Create a parameter file and then run the automatic install in a non-interactive mode, as follows:
  1. Select Control-M/Enterprise Manager and continue with the on-screen instructions until the Summary window appears.
    
    There is no confirmation to shut down Control-M/EM processes. It is done automatically.
  2. Click Generate and select the location to create the XML parameter file.
  3. Click Yes to quit the upgrade.
    
    A confirmation message appears.
  4. Click Yes.
  5. Copy the automatic upgrade parameters file to a network location that is accessible to all hosts where you want to perform an automatic upgrade.
  6. Log in with a user ID that has Administrator permissions on the current host.
  7. Run the upgrade script, as follows:
    
    <source_path>\Setup_files\components\em\setup.exe -silent <xml_path>\<filename.xml>
    
    The upgrade log is in the following location:
    
    %temp%\BMC_Control-M_Enterprise_Manager_<date-time>.log
    
    To ensure compatibility between older Control-M client versions, Control-M/EM is now in Compatibility Mode.
    
    Control-M/EM and Control-M clients are configured by default for HTTP. To secure your environment, BMC recommends that you change your configuration to HTTPS, as described in Zone 1 SSL Configuration.

Upgrading Control-M Client on Windows from the Full Installation Package

This procedure describes how to upgrade the Control-M client to the latest version on Windows from the Full installation package. If you want to install multiple instances of Control-M client on several hosts with the same configuration, use the automatic installation, as described in this procedure.

Before You Begin

Ensure that your operating system is compatible with the new version of the Control-M client, as described in Control-M/EM Windows System Requirements.
Verify that you meet the Java requirements, as described in Control-M External Java Installation.
Download the upgrade package, as described in Obtaining Control-M Installation Files.

Begin

Log in to the host with a user ID that has Administrator permissions.
Copy the upgrade files from the temporary installation directory to the host where Control-M/EM is installed.
Do one of the following:
- Interactively Upgrade: Select Control-M/Enterprise Manager and continue with the on-screen instructions until the upgrade is complete.
- Automatically Upgrade: Create a parameter file and then run the automatic install in a non-interactive mode, as follows:
  1. Select Control-M/Enterprise Manager and continue with the on-screen instructions until the Summary window appears.
  2. Click Generate and select the location to create the XML parameter file.
  3. Click Yes to quit the upgrade.
    
    A confirmation message appears.
  4. Click Yes.
  5. Copy the automatic upgrade parameters file to a network location that is accessible to all hosts where you want to perform an automatic upgrade.
  6. Run the upgrade script, as follows:
    
    <source_path>\Setup_files\components\em\setup.exe -silent <xml_path>\<filename.xml>
    
    The upgrade log is in the following location:
    
    %temp%\BMC_Control-M_Enterprise_Manager_<date-time>.log

Upgrading Control-M Client on Windows from the Client Installation Package

This procedure describes how to upgrade the Control-M client to the latest version on Windows from the client installation package. If you want to install multiple instances of Control-M client on several hosts with the same configuration, use the automatic installation, as described in this procedure.

Before You Begin

Ensure that your operating system is compatible with the new version of the Control-M client, as described in Control-M/EM Windows System Requirements.
Verify one of the following:
- Java 1.8 (64-bit) or higher is available in your Path Environment Variable.
- The Java path is on a network, which is accessible from all Control-M clients.
  
  java_home_path=/network/java_home_directory
  
  To enable users to upgrade their clients without installing Java, you can place Java 1.8 (64-bit) or higher on a network location that is accessible by all Control-M client hosts and define the path in the following file:
  
  <EM_HOME>/Client_Updates/conf/client_deploy_java.properties
Download the upgrade package, as described in Obtaining Control-M Installation Files.

Begin

Copy the upgrade files from the temporary installation directory to the host where Control-M/EM is installed.
From the same command line, type the following:

<source_path>\setup.exe

If Java is not available, type the following:

setup.bat -BMC_INST_JAVA_HOME <Java installation directory>

The Java installation directory must contain the bin directory and the Release file.
Do one of the following:
- Interactively Upgrade: Follow the on-screen instructions until the upgrade is complete.
- Automatically Upgrade: Create a parameter file and then run the automatic install in a non-interactive mode, as follows:
  1. Follow the on-screen instructions until the Summary window appears.
  2. Click Generate and select the location to create the XML parameter file.
  3. Click Yes to quit the upgrade.
    
    A confirmation message appears.
  4. Click Yes.
  5. Copy the automatic upgrade parameters file to a network location that is accessible to all hosts where you want to perform an automatic upgrade.
  6. Run the upgrade script, as follows:
    
    <source_path>\Setup_files\components\clientem\setup.bat -silent <xml_path>\<filename.xml>
    
    The upgrade log is at the following location:
    
    <installFolder>\BMCINSTALL\log\BMC_Control-M_client_<date-time>.log

Upgrading Control-M Client from the Control-M Welcome Page

This procedure describes how to upgrade the Control-M client on Windows from the Control-M Welcome Page. The Control-M/EM server and port are automatically configured during the installation.

Before You Begin

Ensure that your operating system is compatible with the current version of the Control-M client, as described in Control-M Client and Control-M/EM Server Compatibility Scenarios.
Verify one of the following:
- Java 1.8 (64-bit) or higher is available in your Path Environment Variable.
- The Java path is on a network, which is accessible from all Control-M clients.
  
  java_home_path=/network/java_home_directory
  
  To enable users to upgrade their clients without installing Java, you can place Java 1.8 (64-bit) or higher on a network location that is accessible by all Control-M client hosts and define the path in the following file:
  
  <EM_HOME>/Client_Updates/conf/client_deploy_java.properties
Download the upgrade package, as described in Obtaining Control-M Installation Files.

Begin

Open a new browser window before you download and install.
Go to <Control-M/EM_Host>:<port>/Welcome/ and from the Control-M Client section, click Download.
Run the upgrade and continue with the on-screen instructions until the upgrade is complete.

The upgrade log is in the following location:

<installFolder>\BMCINSTALL\log\BMC_Control-M_client_<date-time>.log

Control-M/EM Downgrade

If you want to downgrade to a Control-M/EM version lower than 9.0.22, you uninstall Control-M/EM and the version will automatically revert to the previous version.

The following procedures describe how to downgrade Control-M/EM:

You cannot downgrade Control-M/EM to version 9.0.20.100 or lower if Control-M/Server is version 9.0.22 or higher and the installation type is Control-M Full Installation. You must downgrade Control-M/Server before you can downgrade Control-M/EM.