API

Recovery mode

In the event of a failure of an instance's operating system, an alternative method of accessing the data on the instance is required. To do this, users can put their instances into and out of recovery mode. The Civo API also provides methods to query the recovery mode status of instances.

Recovery mode provides access to an instance using a special OS for emergencies, which allows users to inspect the boot volume of the instance, and make any modifications to bring it back into normal operations. When an instance is in recovery mode it can only be accessed through the console.

  After putting an instance into recovery mode it MUST be rebooted for changes to take effect. In order to return an instance to full functionality after turning off recovery mode, the instance must likewise be rebooted before being accessible as normal.

Put an instance into recovery mode

Request

An authenticated PUT request to https://api.civo.com/v2/instances/:id/recovery begins the recovery mode process, preparing the instance to be accessible in the recovery operating system after a reboot.

This request requires the instance ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the instance is running.

Response

The response is a JSON object that confirms the request has been received. Once received, the instance can be rebooted and accessed using the console. 
{
  "result": "success"
}

Example of activating recovery mode on an instance

curl -H "Authorization: bearer 12345" -X PUT https://api.civo.com/v2/instances/abc123/recovery?region=lon1
              
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.put(
  'https://api.civo.com/v2/instances/abc123/recovery',
  {
    "region": "lon1"
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.put('/v2/instances/abc123/recovery', {region: "lon1"}, headers)

Put an instance out of recovery mode

Returning the instance back to regular operation requires turning off recovery mode, followed by a reboot of the instance.

Request

An authenticated DELETE request to https://api.civo.com/v2/instances/:id/recovery switches off recovery mode, preparing the instance to be accessible in as normal after a reboot.

This request requires the instance ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the instance is running.

Response

The response is a JSON object that confirms the request has been received. Once received, the instance can be rebooted and accessed using the console. 
{
  "result": "success"
}

Example of deactivating recovery mode on an instance

curl -H "Authorization: bearer 12345" -X DELETE https://api.civo.com/v2/instances/abc123/recovery?region=lon1
              
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.del(
  'https://api.civo.com/v2/instances/abc123/recovery',
  {
    "region": "lon1"
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.delete('/v2/instances/abc123/recovery', {region: "lon1"}, headers)

Get the recovery mode status for an instance

The current recovery mode state of an instance can be queried using the API.

Request

An authenticated GET request to https://api.civo.com/v2/instances/:id/recovery confirms the current recovery mode status of an instance.

This request requires the instance ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the instance is running.

Response

The response is a JSON object that returns the result as a boolean. 
{
  "result": "true"
}

Example of querying the current status of recovery mode on an instance

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/instances/abc123/recovery?region=lon1
              
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/instances/abc123/recovery',
  {
    "region": "lon1"
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.get('/v2/instances/abc123/recovery', {region: "lon1"}, headers)