Use the BeyondTrust API to Check Appliance Health and Establish Failover

The BeyondTrust API includes calls to manage and automate failover. Following the basic flows set forth in Establish Failover for Planned Maintenance and Establish Failover for Unplanned Maintenance , you can automate certain parts of these flows using the BeyondTrust API. This section provides some examples of how you can use the BeyondTrust failover API calls. You will need to modify the examples to fit your environment.


Using the built-in failover in /login and the API failover commands together could result in conflict.

Management > API Configuration
API :: Configuration

To use the BeyondTrust API, ensure that the Enable XML API option is checked on the /login > Management > API Configuration page.

For full instructions on using the BeyondTrust API, see the API Programmer's Guide.

Check Appliance Health

To perform a health check on the Secure Remote Access Appliance, use the API command check_health. (In the API Programmer's Guide, see API Command: check_health for full details.)

You can use the XML responses <last_data_sync_time> and <last_data_sync_status> to make sure data syncs are occurring as expected.

If the XML response for the primary appliance includes <success>1</success>, then the appliance is functioning normally. You should not need to failover.

If the XML response for the primary appliance includes <success>0</success>, then you should take into account the time of the last successful health check. Also consider any <error_message> elements that are returned. You should put in place contingencies so that if the issue can be resolved in a reasonable time, then no action should be taken. However, if it is determined that failover is required, then you can use the API to switch failover roles.

In addition to or alternative to using the API command above, you can use to check the health of an appliance. This returns an HTTP status of 200 if the probe is successful and 500 (Server Error) if not. While you will see a simple human-readable message showing success or failure, no other data is exposed.

Set Failover Roles

To set the failover role on a Secure Remote Access Appliance, use the API command set_failover_role. (In the API Programmer's Guide, see API Command: set_failover_role for full details.)

It is assumed that you will have in place systems for enabling/disabling a shared IP address if your two appliances are on the same network or else automatically performing a DNS swing or NAT swing.

Once the failover roles have successfully been changed, you should receive an XML response of <success>.