High Availability Configuration

The following API commands enable you to configure a High Availability environment for Control-M/Server and Control-M/EM:

config server::failover

The config server::failover command enables you to perform a manual failover of a Control-M/Server to a secondary host, provided that High Availability (HA) is configured for this Control-M/Server.

Before you perform a failover, use the config server:highavailabilitystatus::get command to ensure that the database on the secondary host is in sync with the primary host. If necessary, run the config server:database::replicateDatabase command.

For more information, see High Availability.

  • CLI

  • REST

ctm config server::failover <server> <async_option>

The following example shows the REST API syntax for the config server::failover command in cURL.

Copy 
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X PUT "$endpoint/config/server/$server/failover?async=true"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

The following table describes the config server::failover command parameters.

Parameter

Description

server

Defines the name of the Control-M/Server.

async_option

Determines whether to perform the failover asynchronously (in the background).

Valid Values:

  • true (recommended)

  • false

Default: false

If annotation is enabled for the High Availability category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config server::fallback

The config server::fallback command enables you to perform a manual fallback of a Control-M/Server from the secondary host back to the primary host.

For more information, see High Availability.

  • CLI

  • REST

ctm config server::fallback <server>

The following example shows the REST API syntax for the config server::fallback command in cURL.

Copy 
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X PUT "$endpoint/config/server/$server/fallback"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Where server is the name of the Control-M/Server.

If annotation is enabled for the High availability category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config server::setasprimary

The config server::setasprimary command enables you to set a secondary Server as the primary Control-M/Server.

Use this command only after performing a successful manual failover on the server that functioned as the primary server until now. You must have High Availability (HA) set up for these servers.

For more information, see High Availability.

  • CLI

  • REST

ctm config server::setasprimary <server>

The following example shows the REST API syntax for the config server::setasprimary command in cURL.

Copy 
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X PUT "$endpoint/config/server/$server/setasprimary"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Where server is the name of the Control-M/Server.

If annotation is enabled for the High availability category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config server:highavailabilitystatus::get

The config server:highavailabilitystatus::get command retrieves High Availability status information for a specific Control-M/Server.

You can use this command to keep track of the progress of High Availability actions that you initiate—failover or fallback.

Failover and fallback processes may take some time, and you might want to run the config server:highavailabilitystatus::get command several times as they progress.

For more information, see High Availability.

  • CLI

  • REST

ctm config server:highavailabilitystatus::get <server>

The following example shows the REST API syntax for the config server:highavailabilitystatus::get command in cURL.

Copy 
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET "$endpoint/config/server/$server/highavailabilitystatus"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Where server is the name of the Control-M/Server.

Response

The response identifies the primary host and the secondary host and determines which of the two is currently the active host. In addition, the response provides progress information for the process and the steps within it and provides the following statuses:

  • Status of the Connection to the Active Host: This is often accompanied by a status message with more details.

  • High Availability Status: Whether running on the primary host, running on the secondary host, or in the process of moving from one to the other.

  • Overall process status and status of each step within the process.

The following response was returned after a failover process completed.

Copy 
{
  "activeHost": "host1",
  "status": "Warning",
  "statusMessage": "The replication process was not started",
  "highAvailabilityStatus": "Moved To Secondary",
  "primaryHost": "host1",
  "secondaryHost": "host2",
  "progressInformation": {
    "processName": "Manual_Fail_Over",
    "processTitle": "Failover progress",
    "processStatus": "OK",
    "processStartTime": "2024-02-05T22:16:50Z",
    "processEndTime": "2024-02-05T22:17:40Z",
    "processMessage": "",
    "processSteps": [
      {
        "stepName": "Validations",
        "stepTitle": "Verifying failover requirements",
        "stepStatus": "OK",
        "stepStartTime": "2024-02-05T22:16:50Z",
        "stepEndTime": "2024-02-05T22:16:50Z",
        "stepMessage": ""
      },
      {
        "stepName": "Shutting_Down_Active_Control-M_Server",
        "stepTitle": "Shutting down Control-M/Server on primary",
        "stepStatus": "OK",
        "stepStartTime": "2024-02-05T22:16:50Z",
        "stepEndTime": "2024-02-05T22:17:13Z",
        "stepMessage": ""
      },
      {
        "stepName": "Shutdown_Active_PGSQL_Database",
        "stepTitle": "Shutting down PGSQL Server on primary",
        "stepStatus": "OK",
        "stepStartTime": "2024-02-05T22:17:13Z",
        "stepEndTime": "2024-02-05T22:17:19Z",
        "stepMessage": ""
      },
      {
        "stepName": "Switch_Control_To_Other_PGSQL",
        "stepTitle": "Enabling read/write on PGSQL Server on secondary",
        "stepStatus": "OK",
        "stepStartTime": "2024-02-05T22:17:19Z",
        "stepEndTime": "2024-02-05T22:17:25Z",
        "stepMessage": ""
      },
      {
        "stepName": "Switch_Control_To_Other_Control-M_Server",
        "stepTitle": "Switching control to secondary host",
        "stepStatus": "OK",
        "stepStartTime": "2024-02-05T22:17:25Z",
        "stepEndTime": "2024-02-05T22:17:25Z",
        "stepMessage": ""
      },
      {
        "stepName": "Non_Active_Take_Control",
        "stepTitle": "Secondary host took control",
        "stepStatus": "OK",
        "stepStartTime": "2024-02-05T22:17:25Z",
        "stepEndTime": "2024-02-05T22:17:26Z",
        "stepMessage": ""
      },
      {
        "stepName": "Configuring_PGSQL_Server_As_Active",
        "stepTitle": "Configuring PGSQL Server on secondary as active server",
        "stepStatus": "OK",
        "stepStartTime": "2024-02-05T22:17:26Z",
        "stepEndTime": "2024-02-05T22:17:34Z",
        "stepMessage": ""
      },
      {
        "stepName": "Starting_Control-M_Server_server",
        "stepTitle": "Starting Control-M/Server on secondary, based on desired state",
        "stepStatus": "OK",
        "stepStartTime": "2024-02-05T22:17:34Z",
        "stepEndTime": "2024-02-05T22:17:39Z",
        "stepMessage": ""
      }
    ]
  }
}

config server:database::replicateDatabase

The config server:database::replicateDatabase command triggers database replication on a specific Control-M/Server. You might need to run this command after you install a secondary, perform failover or fallback, or after a communication malfunction occurred between the primary and secondary database servers.

For more information, see High Availability.

  • CLI

  • REST

ctm config server:database::replicateDatabase <server>

The following example shows the REST API syntax for the config server:database::replicateDatabase command in cURL.

Copy 
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X PUT "$endpoint/config/server/$server/database/replicate"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Where server is the name of the Control-M/Server.

If annotation is enabled for the High availability category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config server:database::databaseActivateSync

The config server:database::databaseActivateSync command turns on sync mode for database replication on a specific Control-M/Server.

For more information, see High Availability.

  • CLI

  • REST

ctm config server:database::databaseActivateSync <server>

The following example shows the REST API syntax for the config server:database::databaseActivateSync command in cURL.

Copy 
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X PUT "$endpoint/config/server/$server/database/sync"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Where server is the name of the Control-M/Server.

If annotation is enabled for the High availability category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config em::failover

The config em::failover command enables you to perform a manual failover of Control-M/EM to a secondary host, provided that High Availability (HA) is set up.

For more information, see High Availability.

This command requires Control-M/EM 9.0.20.200 or higher.

  • CLI

  • REST

ctm config em::failover

The following example shows the REST API syntax for the config em::failover command in cURL.

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/em/failover"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

If annotation is enabled for the High Availability category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config em::fallback

The config em::fallback command enables you to perform a manual fallback from the secondary Control-M/EM host back to the primary Control-M/EM host.

For more information, see High Availability.

This command requires Control-M/EM 9.0.20.200 or higher.

  • CLI

  • REST

ctm config em::fallback

The following example shows the REST API syntax for the config em::fallback command in cURL.

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/em/fallback"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

If annotation is enabled for the High availability category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config em::setasprimary

The config em::setasprimary command enables you to set a secondary Control-M/EM host as the primary Control-M/EM.

Use this command only after performing a successful manual failover on the Control-M/EM host that functioned as the primary host until now. You must have High Availability (HA) set up for these machines.

For more information, see High Availability.

This command requires Control-M/EM 9.0.20.200 or higher.

  • CLI

  • REST

ctm config em::setasprimary

The following example shows the REST API syntax for the config em::setasprimary command in cURL.

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/config/em/setasprimary"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

If annotation is enabled for the High availability category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config em:highavailabilitystatus::get

The config em:highavailabilitystatus::get command retrieves High Availability status information from your current environment.

You can use this command to keep track of the progress of High Availability actions that you initiate—failover or fallback.

This command requires Control-M/EM 9.0.20.200 or higher.

Failover and fallback processes may take some time, and you might want to run the config em:highavailabilitystatus::get command several times as they progress.

During these processes, one of the Control-M/EM hosts is brought down, and the connection to that host is no longer available. At that point, you can use the environment set command to switch environments and then continue running the config em:highavailabilitystatus::get command to retrieve information from the newly active host.

For more information, see High Availability.

  • CLI

  • REST

ctm config em:highavailabilitystatus::get

The following example shows the REST API syntax for the config em:highavailabilitystatus::get command in cURL.

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET "$endpoint/config/em/highavailabilitystatus"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

Response

The response identifies the primary host and the secondary host and determines which of the two is currently the active host. In addition, the response provides the following statuses:

  • Status of the connection to the host associated with the current environment. This is often accompanied by a status message with more details.

  • High Availability Status: Whether running on the primary host, running on the secondary host, or in the process of moving from one to the other

  • Overall process status and status of each step within the process.

The following response was returned after a failover process was initiated. The connection to the host in this environment is no longer available.

Copy 
{
   "activeHost": "host1",
   "status": "Error",
   "statusMessage": "Manual failover started. The primary machine is not available.",
   "highAvailabilityStatus": "During Failover",
   "primaryHost": "host1",
   "secondaryHost": "host2",
   "progressInformation": {
      "processName": "FailOver",
      "processTitle": "Failover process",
      "processStatus": "Executing",
      "processStartTime": "2025-01-28T10:20:40Z GMT+00:00",
      "processEndTime": "",
      "processMessage": "",
      "processSteps": [
          {
             "stepName": "Validation",
             "stepTitle": "Verifying failover requirements",
             "stepStatus": "OK",
             "stepStartTime": "2025-01-28T10:20:40Z GMT+00:00",
             "stepEndTime": "2025-01-28T10:20:41Z GMT+00:00",
             "stepMessage": ""
          },
          {
             "stepName": "ShuttingDown",
             "stepTitle": "Shutting down Control-M/EM on primary",
             "stepStatus": "OK",
             "stepStartTime": "2025-01-28T10:20:41Z GMT+00:00",
             "stepEndTime": "2025-01-28T10:22:11Z GMT+00:00",
             "stepMessage": ""
          },
          {
             "stepName": "SwitchControl",
             "stepTitle": "Switching control to secondary host",
             "stepStatus": "Executing",
             "stepStartTime": "2025-01-28T10:22:11Z GMT+00:00",
             "stepEndTime": "",
             "stepMessage": ""
          },
          {
             "stepName": "TakeControl",
             "stepTitle": "Secondary Control-M/EM took control",
             "stepStatus": "Not Started",
             "stepStartTime": "",
             "stepEndTime": "",
             "stepMessage": ""
          },
          {
             "stepName": "StartingComponents",
             "stepTitle": "Starting Control-M/EM on secondary",
             "stepStatus": "Not Started",
             "stepStartTime": "",
             "stepEndTime": "",
             "stepMessage": ""
          }
       ]
    }
}

After using the environment set command to switch environments, the following response was returned from the newly active host:

Copy 
{
   "activeHost": "host2",
   "status": "Warning",
   "statusMessage": "Running on secondary",
   "highAvailabilityStatus": "Moved to secondary",
   "primaryHost": "host1",
   "secondaryHost": "host2",
   "progressInformation": {
      "processName": "FailOver",
      "processTitle": "Failover process",
      "processStatus": "OK",
      "processStartTime": "2025-01-26T09:12:19Z GMT+00:00",
      "processEndTime": "2025-01-26T09:15:46Z GMT+00:00",
      "processMessage": "",
      "processSteps": [
          {
              "stepName": "Validation",
              "stepTitle": "Verifying failover requirements",
              "stepStatus": "OK",
              "stepStartTime": "2025-01-26T09:12:19Z GMT+00:00",
              "stepEndTime": "2025-01-26T09:12:20Z GMT+00:00",
              "stepMessage": ""
          },
          {
              "stepName": "ShuttingDown",
              "stepTitle": "Shutting down Control-M/EM on primary",
              "stepStatus": "OK",
              "stepStartTime": "2025-01-26T09:12:20Z GMT+00:00",
              "stepEndTime": "2025-01-26T09:13:58Z GMT+00:00",
              "stepMessage": ""
          },
          {
              "stepName": "SwitchControl",
              "stepTitle": "Switching control to secondary host",
              "stepStatus": "OK",
              "stepStartTime": "2025-01-26T09:13:58Z GMT+00:00",
              "stepEndTime": "2025-01-26T09:14:17Z GMT+00:00",
              "stepMessage": ""
          },
          {
              "stepName": "TakeControl",
              "stepTitle": "Secondary Control-M/EM took control",
              "stepStatus": "OK",
              "stepStartTime": "2025-01-26T09:14:17Z GMT+00:00",
              "stepEndTime": "2025-01-26T09:14:27Z GMT+00:00",
              "stepMessage": ""
          },
          {
              "stepName": "StartingComponents",
              "stepTitle": "Starting Control-M/EM on secondary",
              "stepStatus": "OK",
              "stepStartTime": "2025-01-26T09:14:28Z GMT+00:00",
              "stepEndTime": "2025-01-26T09:15:46Z GMT+00:00",
              "stepMessage": ""
          }
      ]
   }
}