Agent Deployment

The Agent Deployment tool enables you to automatically upgrade multiple Agents from a single point of access. The Agent upgrade includes Application Integrator and Automation API CLI.

From the CCM, you can copy Agent installation packages to multiple Agents. You can then upgrade the Agents to version 9.0.21 or higher on UNIX and Windows, and to version 7.0.01 or higher on AS400.

  • You cannot use Agent Deployment on a Network Load Balancer that represents an Agent or a group of Agents.

  • BMC recommends that you deploy Agents in groups. You can simultaneously upgrade or downgrade five Agents by default, or you can change this limit, as described in the DEPLOYMENTS_THREADS parameter in Deployment Parameters.

  • (Windows only) You cannot simultaneously upgrade multiple Agents on the same computer.

  • (Windows only) Deployment might fail when the Agent is executing a very high load of jobs. The following message appears:

    --------------------------------------------Pay Attention--------------------------------------------

    Installation with no downtime cannot be executed at this moment.

    1. Check communication between Control-M/Agent and Control-M/Server.

    2. Run the ctmagcfg utility. In Advanced parameters, verify that the Logical Agent Name value matches the Control-M/Agent Name defined in the Control-M/Server and rerun the installation again.

    3. To install with downtime, shut down the Control-M/Agent processes and rerun the installation again.

    You must run the upgrade when the Agent is executing less jobs or during downtime.

The following procedures describe how to set up the Agent installation packages, and upgrade and downgrade Agents:

For a description of configurable deployment parameters, see Deployment Parameters and Agent Deployment Parameters.

Copying Agent Installation Packages

This procedure describes how to copy the Agent installation packages for each platform and save them to the Control-M/EM repository or a network location. This enables you to upgrade multiple Agents from different platforms and versions to the latest version and fix pack.

Begin

  1. Download the Agent installation packages via EPD, as described in Obtaining Control-M Installation Files.

    You must download the required package for each platform that you want to upgrade. Do not rename the installation package.

  2. Do one of the following to save the installation packages:

    • Control-M/EM Host: Copy the installation package to the $EM_HOME/AUTO_DEPLOY directory on the computer where the CMS is installed.

      /home/one900a/ctm_em/AUTO_DEPLOY

    • Network Location: Define the CentralDeployLocation system parameter, as described in , and the CTM_AUTO_DEPLOY_PACKAGE_LOCATION_WINDOWS and CTM_AUTO_DEPLOY_PACKAGE_LOCATION_UNIX system parameters, as described in Deployment Parameters.

Upgrading Agents

This procedure describes how to transfer installation packages to existing Agents and upgrade them to the current base version or fix pack on UNIX, Windows, or AS400.

  • (Windows only) You cannot simultaneously upgrade more than one Agent on the same computer.

  • (Windows only) An upgrade does not begin until all jobs have ended, unless you select Force Upgrade in a Retry on Control-M/Agent 9.0.00 or lower.

Before You Begin

  • Review Upgrade Requirements and Considerations.

  • Copy the Agent installation packages to the Control-M/EM repository or a network location, as described in Copying Agent Installation Packages.

  • Verify that Control-M/EM 9.0.21 or higher is installed.

  • Verify that Control-M/Agent 9.0.00.300 or higher is installed.

  • Verify that Control-M/Server 9.0.19 or higher is installed.

  • Install the additional Control-M/Server patches described in 000393589.

  • Turn off Compatibility Mode, as described in Turning off Compatibility Mode.

  • If Application Pack is installed, verify that all Application Integrator jobs have completed, since this procedure also upgrades Application Pack, which includes Application Integrator.

  • Verify that you have Full access to the Configuration and Operation categories in Admin Management in the Configuration domain, as described in Role Authorizations.

  • (Windows only) If the Control-M/Agent Windows service is set to Log on as > This account, you must upgrade with this user account.

Begin

  1. From the Manage tab in the CCM, select Deployment.

    The Deployment window appears.

  2. Click New Activity, click Agent, and then click Upgrade.

    The Upgrade Control-M/Agents Activity window appears.

  3. Do the following:

    1. In the Activity Name field, type a new name for this deployment activity.

    2. (Optional) In the Description field, describe the purpose of this activity.

    3. (Optional) In the E-Mail Notification field, type one or more email addresses where notifications about this activity are sent.

      You must also define the email server parameters, as described in Agent Deployment.

  4. Select one of the following actions:

    • Send Agent Deploy to Control-M/Agent(s): Transfers the Agent installation package to specific Agents. After the package is transferred, you can manually start the upgrade process at any time from the Agent Deployment window or upgrade with the CLI, as described in ccmcli.

    • Send and Install Agent Deploy to Control-M/Agent(s): Transfers the Agent installation package to specific Agents and starts the upgrade process.

    • Use Network Location to Update Control-M/Agent(s): (Control-M/Server 9.0.21 and higher only) Upgrades the selected Agents directly from a network location. This option improves performance because it avoids the transfer of installation packages from the Control-M/Server to the Agents and saves Agent disk space.

      If you select this option, you must do the following:

      1. Define the Control-M/EM system parameter CentralDeployLocation with the installation package network location.

      2. Define the following Control-M/Server system parameters with the installation package network location:

        • CTM_AUTO_DEPLOY_PACKAGE_LOCATION_WINDOWS

        • CTM_AUTO_DEPLOY_PACKAGE_LOCATION_UNIX

      • The Agent installation package is deleted after it successfully upgrades. If the upgrade fails or you only perform a transfer, the installation package remains on the Agent for 30 days. To change this limit, redefine the Agent system parameter AD_RETAIN_PACKAGES, as described in Configuring Agent System Parameters.

      • The Agent installation package remains on the Control-M/Server computer for 30 days. To change this limit, redefine the Control-M/Server system parameter AD_RETAIN_PACKAGES, as described in Deployment Parameters.

  5. Click Next.

  6. From the Upgrade Agents to Version drop-down list, select the version or fix pack that you want to upgrade to, and then select the Agents to upgrade.

    The list of versions depends on the Agent installation packages in your repository. For more information, see Copying Agent Installation Packages.

  7. In the Set Java Home Directory Location for the Selected Agents field, type the path that points to the external Java installation for all selected Agents.

    If the path is incorrect and the deploy fails, you can update the path in the Properties pane.

    Only one Java home directory can be defined for this deployment activity. If you need to deploy Agents to platforms with different Java paths, leave this field empty. To view the OS type for each Agent, see the Operating System column in the Components table.

    For more information, see Control-M External Java Installation.

  8. Click Transfer, Upgrade or Send, depending on the action you selected.

    The transfer process starts and progress messages appear in the right pane of the deployment activity.

    To view and troubleshoot the internal upgrade stages, click Log from the Agent Deployment window.

    If you selected Transfer, you can upgrade the Agents any time after the transfer completes. A job executes on the Agents to verify that the upgrades succeeded.

Rolling Back Agents

This procedure describes how to roll multiple Agents back to their original version, prior to the upgrade, if there is a problem with the upgrade. You can only roll back Agents that were upgraded with the Agent Deployment tool.

This procedure must be done within a defined period, based on the AD_GA_RETAIN_DAYS system parameter, as described in Agent Deployment Parameters.

Before You Begin

  • Verify that all jobs on the selected Agents have ended. Jobs that are still running during the rollback might fail.

  • Verify that you have Full access to the Configuration and Operation categories in Admin Management in the Configuration domain, as described in Role Authorizations.

  • (Windows only) If the Control-M/Agent Windows service is set to Log on as > This account, you must upgrade with this user account.

Begin

  1. From the Manage tab in the CCM, select Deployment.

    The Deployment window appears.

  2. Click New Activity, click Agent, and then click Rollback.

    The Rollback Control-M/Agents Activity window appears.

  3. Do the following:

    1. In the Activity Name field, accept the default or type a new name for this rollback activity.

    2. (Optional) In the Description field, describe the purpose of this activity.

    3. (Optional) In the E-Mail Notification Address field, type one or more email addresses where notifications about this activity are sent.

      You must also define the email server parameters, as described in Agent Deployment.

      Any configuration changes that you might have made after the upgrade will be lost when you roll back to the previous version, including updating the primary or secondary Control-M/Server or the communication port.

  4. Click Next.

  5. From the Rollback Agents from Version drop-down list, select the version or fix pack to roll back from, and then select the Agents to roll back.

  6. Click Rollback.

    The rollback process begins immediately and Agent is rolled back to the previous version. To view and troubleshoot the internal stages of the rollback, click Log from the Agent Deployment window.

  7. (Optional) To re-enable Application Integrator, which stops working after a rollback, you must you must uninstall and then reinstall Application Pack.