High Availability Configuration

The following API commands enable you to configure a High Availability environment for the 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 set up for this 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::replicateDatabase command.

For more information, see High Availability.

CLI Syntax

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

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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

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

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

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

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 Syntax

Copy 
ctm config server::fallback <server>

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

If annotation is enabled for the High availability category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

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

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

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

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 Syntax

Copy 
ctm config server::setasprimary <server>

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

If annotation is enabled for the High availability category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

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

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

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

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 Syntax

Copy 
ctm config server:highavailabilitystatus::get <server>

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

REST API Syntax

cURL:

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

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

To determine the correct AuthHeader value—"Authentication: 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 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::replicateDatabase

The config server::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 Syntax

Copy 
ctm config server::replicateDatabase <server>

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

If annotation is enabled for the High availability category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

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

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

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

config server::databaseActivateSync

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

For more information, see High Availability.

CLI Syntax

Copy 
ctm config server::databaseActivateSync <server>

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

If annotation is enabled for the High availability category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

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

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

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

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 version 9.0.20.200 or later.

CLI Syntax

Copy 
ctm config em::failover

If annotation is enabled for the High Availability category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

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

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

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

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 version 9.0.20.200 or later.

CLI Syntax

Copy 
ctm config em::fallback

If annotation is enabled for the High availability category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

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

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

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

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 version 9.0.20.200 or later.

CLI Syntax

Copy 
ctm config em::setasprimary

If annotation is enabled for the High availability category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

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

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

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

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 version 9.0.20.200 or later.

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 Syntax

Copy 
ctm config em:highavailabilitystatus::get

REST API Syntax

cURL:

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

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

To determine the correct AuthHeader value—"Authentication: 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.

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"
}

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"
}