Agent operations

This section describes the agent operations that are supported by the Cloud Backup API.

List the agent details

GET /v1.0/{tenant_id}/agent/{machineAgentId}

This operation lists details about the machine and its agent.

Note

If the agent Status is showing as Offline, it is possible that the Cloud Backup agent might be idle and not posting any heartbeats. You can wake up your Cloud Backup agent by using the operation described in Wake up agents. You should wait 10-20 seconds after using this operation to determine the online status of the agent reliably.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request succeeded.
400	Bad request	There were one or more errors in the request.
401	Unauthorized	The supplied token was not authorized to access the resources. Either it is expired or invalid.
403	Forbidden	Access to the requested resource was denied.
404	Not Found	The backend services did not find anything matching the request URI.
500	Instance Fault	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.
503	Service Unavailable	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.
{machineAgentId}	Integer	The unique identifier of the Cloud Backup agent.

This operation does not accept a request body.

Example: List agent details JSON request

GET https://dfw.backup.api.rackspacecloud.com/v1.0/1234/agent/213564
User-Agent: controlpanel.drivesrvr.com
Host: dfw.backup.api.rackspacecloud.com
Content-Type: application/json
Content-Length: 0
X-Auth-Token: 95b1788906f74d279d03001c6a14f3fe

Response

This table shows the body parameters for the response:

Name	Type	Description
AgentVersion	String	Version of the Rackspace Cloud Backup agent.
Architecture	String	Base architecture of the Cloud Server. Valid values are 64- bit or 32-bit.
Flavor	String	RaxCloudServer – for Rackspace Cloud Servers.
BackupVaultSize	String	Size of backup data in MB.
BackupContainer	String	Full public URI for Cloud Files where backups are stored for this agent.
CleanupAllowed	String	Indicates whether a cleanup can be manually triggered on the backup vault. Valid values are true or false.
Datacenter	String	Data center where the Cloud Server is located. Valid values are IAD, ORD, DFW, HKG, LON, or SYD).
IPAddress	String	Public IPv4 address of the Cloud Server.
IsDisabled	String	Indicates if the Rackspace Cloud Backup agent on the server is disabled. Valid values are true or false.
IsEncrypted	String	Indicates if backups are encrypted. Valid values are true or false.
MachineAgentId	String	ID that uniquely identifies a Cloud Backup agent.
MachineName	String	Name of the Cloud Server.
OperatingSystem	String	Operating system of Cloud Server.
OperatingSystemVersion	String	Operating system version of Cloud Server.
PublicKey	String	Public key of the public/private encryption key pair.
Status	String	Status of the Cloud Backup agent. Valid values are Online or Offline.
TimeOfLastSuccessfulBackup	String	Time of last successful backup.
UseServiceNet	String	Indicates if the Cloud Backup agent is using ServiceNet to backup data to Cloud Files. Valid values are true or false.
HostServerId	String	Server ID of the host server where the Cloud Backup agent is running.

Example: List agent details JSON response

{
    "AgentVersion": "1.05.005848",
    "Architecture": "64-bit",
    "Flavor": "RaxCloudServer",
    "BackupVaultSize": "35.3 MB",
    "CleanupAllowed": true,
    "Datacenter": "DFW",
    "IPAddress": "192.168.1.1",
    "IsDisabled": false,
    "IsEncrypted": true,
    "MachineAgentId": 213564,
    "MachineName": "Web Server",
    "OperatingSystem": "Windows Server 2012",
    "OperatingSystemVersion": "",
    "PublicKey": {
        "ModulusHex": "a5261939156948bb7a58dffe5ff89e65f0498f9175f5a 98288810b8975871e99af3b5dd94057b0fc07535f5f97444504fa35169d4 61d0d30cf0192e307727c065168c788771c561a9400fb61975e9e6aa4e23 fe11af69e9412dd23b0cb6684c4c2429bce139e848ab26d0829073351f4a cd36074eafd036a5eb83359d2a698d0",
        "ExponentHex": "09528"
    },
    "Status": "Online",
    "TimeOfLastSuccessfulBackup": "\/Date(1357817400000)\/",
    "UseServiceNet": true,

    "HostServerId" :  "87c3b6e1-fb1a-41f9-91e5-313ae35a5a06"
}

Enable or disable an agent

POST /v1.0/{tenant_id}/agent/enable

This operation enables or disables an agent. Disabling an agent does not delete it or its data. You can re-enable disabled agents later.

Note

Encryption is important for keeping your data confidential. However, encryption is also expensive. It takes significantly longer to backup and restore encrypted data. Consider if the data you are storing must be encrypted. If not, it is best to proceed without encryption. Encryption applies across the board, and once you encrypt a backup server, there is no turning back.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No Content	The request succeeded.
400	Bad request	There were one or more errors in the request.
401	Unauthorized	The supplied token was not authorized to access the resources. Either it is expired or invalid.
403	Forbidden	Access to the requested resource was denied.
500	Instance Fault	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.
503	Service Unavailable	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.

This table shows the body parameters for the request:

Name	Type	Description
MachineAgentId	String (Required)	ID that uniquely identifies a Cloud Backup agent.
Enable	String (Required)	Indicates if agent is enabled (true) or disabled (false).

Example: Enable an agent JSON request

{
    "MachineAgentId": 92384579,
    "Enable": true
}

Example: Disable an agent JSON request

{
    "MachineAgentId": 92384579,
    "Enable": false
}

Response

This operation does not return a response body.

Enable volume encryption

POST /v1.0/{tenant_id}/agent/encrypt

This operation enables volume encryption with AES-256 encryption if it is not already enabled. If you need assistance generating your encrypted key, see Generate your encrypted key in Cloud Backup.

Note

After encryption is turned on, you cannot turn it off. This is a security measure. If anyone ever gained access to your account, they would not be able to access your backups without your passphrase.

If you lose or forget your passphrase, you will not be able to recover your encrypted backups.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request succeeded.
400	Bad request	There were one or more errors in the request.
401	Unauthorized	The supplied token was not authorized to access the resources. Either it is expired or invalid.
403	Forbidden	Access to the requested resource was denied.
500	Instance Fault	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.
503	Service Unavailable	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.

This table shows the body parameters for the request:

Name	Type	Description
MachineAgentId	String (Required)	ID that uniquely identifies a Cloud Backup agent.
EncryptedPasswordHex	String (Required)	Your encrypted password.

Example: Enable volume encryption JSON request

{
    "MachineAgentId" : 869,
    "EncryptedPasswordHex" : "0bff42a526c78076a3d986fa75eecd 83211f166fd7692797cdde2317faee544e3300614fd54b8c0d81f975 3e58cb1ffbd62d3faf0d2bf52e79ce5cd9c6d84b5295e3dea629e71b 0a5e26efda50ff8e05a5475bb7cbd553d238c05655f56ece2df070ce 374ff1e0724827c2300e373241e94c4bc13441561604e3e70b5034eb 58d717864f304c9c73b6d1d46c4276d7ec2f0e2bd9a42a8ab0ba99eb adda84f4cbb5b3611bd319627436246912139c2dde62bd00528b1464 20dceae949d1926ae05fc7df9b474e1ee176f89069fb424b12f8f357 e6e2909ba05152e9f72a68de0046b3e1520838ff5e723af02a96f51a c1e6ef4254226249b872676af76a319cbe"
}

Response

Example: Enable volume encryption response

0cee72c7-015c-493b-b5fe-a896ae444c34

Change the encryption password

POST /v1.0/{tenant_id}/agent/changeencryption

This operation changes the encryption password.

This operation changes the encryption password. If you need assistance generating your encrypted key, see Generate your encrypted key in Cloud Backup.

Note

After you turn on encryption, you cannot turn it off. This is a security measure. If anyone ever gained access to your account, they would not be able to access your backups without your passphrase.

If you lose or forget your passphrase, you will not be able to recover your encrypted backups.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request succeeded.
400	Bad request	There were one or more errors in the request.
401	Unauthorized	The supplied token was not authorized to access the resources. Either it is expired or invalid.
403	Forbidden	Access to the requested resource was denied.
500	Instance Fault	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.
503	Service Unavailable	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.

This table shows the body parameters for the request:

Name	Type	Description
MachineAgentId	String (Required)	ID that uniquely identifies a Cloud Backup agent.
OldEncryptedPasswordHex	String (Required)	Your old encrypted password.
NewEncryptedPasswordHex	String (Required)	Your new encrypted password.

Example: Change encryption password JSON request

{
    "MachineAgentId" : 869,
    "OldEncryptedPasswordHex" : "0bff42a526c78076a3d986fa75eecd 83211f166fd7692797cdde2317faee544e3300614fd54b8c0d81f975 3e58cb1ffbd62d3faf0d2bf52e79ce5cd9c6d84b5295e3dea629e71b 0a5e26efda50ff8e05a5475bb7cbd553d238c05655f56ece2df070ce 374ff1e0724827c2300e373241e94c4bc13441561604e3e70b5034eb 58d717864f304c9c73b6d1d46c4276d7ec2f0e2bd9a42a8ab0ba99eb adda84f4cbb5b3611bd319627436246912139c2dde62bd00528b1464 20dceae949d1926ae05fc7df9b474e1ee176f89069fb424b12f8f357 e6e2909ba05152e9f72a68de0046b3e1520838ff5e723af02a96f51a c1e6ef4254226249b872676af76a319cbe",
    "NewEncryptedPasswordHex" : "0bff42a526c78076a3d986fa75eecd 83211f166fd7692797cdde2317faee544e3300614fd54b8c0d81f975 3e58cb1ffbd62d3faf0d2bf52e79ce5cd9c6d84b5295e3dea629e71b 0a5e26efda50ff8e05a5475bb7cbd553d238c05655f56ece2df070ce 374ff1e0724827c2300e373241e94c4bc13441561604e3e70b5034eb 58d717864f304c9c73b6d1d46c4276d7ec2f0e2bd9a42a8ab0ba99eb adda84f4cbb5b3611bd319627436246912139c2dde62bd00528b1464 20dceae949d1926ae05fc7df9b474e1ee176f89069fb424b12f8f357 e6e2909ba05152e9f72a68de0046b3e1520838ff5e723af02a96f51a c1e6ef4254226249b872676af76a319fgh"
}

Response

Example: Change encryption password response

0cee72c7-015c-493b-b5fe-a896ae444c34

Delete an agent

POST /v1.0/{tenant_id}/agent/delete

This operation immediately permanently deletes an agent and its backup data.

You can delete an agent at any time. If the agent is in the middle of an operation, it is allowed to complete. After it completes, it no longer authenticates.

This table shows the possible response codes for this operation:

Response Code	Name	Description
204	No Content	The request succeeded.
400	Bad Request	There were one or more errors in the request.
401	Unauthorized	The supplied token was not authorized to access the resources. Either it is expired or invalid.
403	Forbidden	Access to the requested resource was denied.
500	Instance Fault	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.
503	Service Unavailable	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.

This table shows the body parameters for the request:

Name	Type	Description
MachineAgentId	String (Required)	ID that uniquely identifies a Cloud Backup agent.

Example: Delete agent JSON request

{
    "MachineAgentId": 92384579
}

Response

This table shows the body parameters for the response:

Name	Type	Description
MachineAgentId	String	ID that uniquely identifies a Cloud Backup agent.

Example: Delete agent JSON response

{
    "MachineAgentId": 92384579
}

Migrate a vault

PUT /v1.0/{tenant_id}/agent/migratevault

This operation migrates a backup vault from one machine agent to another.

To use the migrate vault operation, the two agents should be under the same user and their backups should not be encrypted. The destination machine agent should not have any backups already configured and running.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request succeeded.
403	Forbidden	Access to the requested resource was denied.
500	Instance Fault	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.
503	Service Unavailable	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.

This table shows the body parameters for the request:

Name	Type	Description
SourceMachineAgentId	String (Required)	Agent ID of the source. Backups are migrated from this agent.
DestinationMachineAgentID	String (Required)	Agent ID of the destination. Backups are migrated to this agent.

Example: Migrate vault JSON request

{
    "SourceMachineAgentId": 1,
    "DestinationMachineAgentId": 2
}

Response

This operation does not return a response body.

Update the agent backup behavior

POST /v1.0/{tenant_id}/agent/{machineAgentId}

This operation updates the backup data center, or enables or disables ServiceNet for the Cloud Backup agent, or both.

If ServiceNet is enabled, the Cloud Backup agent talks to Cloud Files over ServiceNet and does not incur any bandwidth charges.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request succeeded.
400	Bad Request	There were one or more errors in the request.
401	Unauthorized	The supplied token was not authorized to access the resources. Either it is expired or invalid.
403	Forbidden	Access to the requested resource was denied.
500	Instance Fault	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.
503	Service Unavailable	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.
{machineAgentId}	Integer	The unique identifier of the Cloud Backup agent.

This table shows the body parameters for the request:

Name	Type	Description
BackupDataCenter	String (Optional)	Specifies the backup data center where this Agent’s backup will reside. You must have VMs in the data center specified by BackupDataCenter or this operation will fail.
UseServiceNet	String (Required)	Enables or disables the ServiceNet for this agent. Valid values are true or false.

Example: Update agent backup behavior JSON request

POST https://dfw.backup.api.rackspacecloud.com/v1.0/1234/agent/213564
User-Agent: controlpanel.drivesrvr.com
Host: dfw.backup.api.rackspacecloud.com
Content-Type: application/json;
Content-Length: 0
X-Auth-Token: 95b1788906f74d279d03001c6a14f3fe

Example: Update agent backup behavior JSON request

{
    "BackupDataCenter" : "DFW",
    "UseServiceNet" : true
}

Response

This table shows the body parameters for the response:

Name	Type	Description
AgentVersion	String	Version of the Rackspace Cloud Backup agent.
Architecture	String	Base architecture of the Cloud Server. Valid values are 64- bit or 32-bit.
Flavor	String	RaxCloudServer – for Rackspace Cloud Servers.
BackupVaultSize	String	Size of backup data in MB.
CleanupAllowed	String	Indicates whether a cleanup can be manually triggered on the backup vault. Valid values are true or false.
Datacenter	String	Data center where the Cloud Server is located. Valid values are IAD, ORD, DFW, HKG, LON, or SYD).
IPAddress	String	Public IPv4 address of the Cloud Server.
IsDisabled	String	Indicates if the Rackspace Cloud Backup agent on the server is disabled. Valid values are true or false.
IsEncrypted	String	Indicates if backups are encrypted. Valid values are true or false.
MachineAgentId	String	ID that uniquely identifies a Cloud Backup agent.
MachineName	String	Name of the Cloud Server.
OperatingSystem	String	Operating system of Cloud Server.
OperatingSystemVersion	String	Operating system version of Cloud Server.
PublicKey	String	Public key of the public/private encryption key pair.
Status	String	Status of the Cloud Backup agent. Valid values are Online or Offline.
TimeOfLastSuccessfulBackup	String	Time of last successful backup.
UseServiceNet	String	Indicates if the Cloud Backup agent is using ServiceNet to backup data to Cloud Files. Valid values are true or false.
UseFailoverUri	String	Indicates if a failover URI should be used. Valid values are true or false.

Example: Update agent backup behavior JSON response

{
    "AgentVersion": "1.05.005848",
    "Architecture": "64-bit",
    "Flavor":"RaxCloudServer",
    "BackupVaultSize": "35.3 MB",
    "CleanupAllowed": true,
    "Datacenter": "DFW",
    "BackupDataCenter": "DFW",
    "IPAddress": "192.168.1.1",
    "IsDisabled": false,
    "IsEncrypted": true,
    "MachineAgentId": 213564,
    "MachineName": "Web Server",
    "OperatingSystem": "Windows Server 2012",
    "OperatingSystemVersion":"",
    "PublicKey": {
         "ModulusHex": "a5261939156948bb7a58dffe5ff89e65f0498f9175f5a 98288810b8975871e99af3b5dd94057b0fc07535f5f97444504fa35169d4 61d0d30cf0192e307727c065168c788771c561a9400fb61975e9e6aa4e23 fe11af69e9412dd23b0cb6684c4c2429bce139e848ab26d0829073351f4a cd36074eafd036a5eb83359d2a698d0",
        "ExponentHex": "09528"
    },
    "Status": "Online",
    "TimeOfLastSuccessfulBackup": "\/Date(1358752980000)\/",
    "UseServiceNet": true,
    "UseFailoverUri": true
}

List the agent details by host server ID

GET /v1.0/{tenant_id}/agent/server/{hostServerId}

This operation lists details about the machine and its agent using the host server ID.

This table shows the possible response codes for this operation:

Response Code	Name	Description
200	OK	The request succeeded.
400	Bad Request	There were one or more errors in the request.
401	Unauthorized	The supplied token was not authorized to access the resources. Either it is expired or invalid.
403	Forbidden	Access to the requested resource was denied.
404	Not Found	The backend services did not find anything matching the request URI.
500	Instance Fault	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.
503	Service Unavailable	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.
{hostServerId}	Integer	The unique identifier of the host server where the Cloud Backup agent is running.

This operation does not accept a request body.

Example: List agent details by host server ID JSON request

GET https://dfw.backup.api.rackspacecloud.com/v1.0/1234/agent/server/87c3b6e1-fb1a-41f9-91e5-313ae35a5a06
User-Agent: controlpanel.drivesrvr.com
Host: dfw.backup.api.rackspacecloud.com
Content-Type: application/json
Content-Length: 0
X-Auth-Token: 95b1788906f74d279d03001c6a14f3fe

Response

This table shows the body parameters for the response:

Name	Type	Description
AgentVersion	String	Version of the Rackspace Cloud Backup agent.
Architecture	String	Base architecture of the Cloud Server. Valid values are 64- bit or 32-bit.
Flavor	String	RaxCloudServer – for Rackspace Cloud Servers.
BackupVaultSize	String	Size of backup data in MB.
CleanupAllowed	String	Indicates whether a cleanup can be manually triggered on the backup vault. Valid values are true or false.
Datacenter	String	Data center where the Cloud Server is located. Valid values are IAD, ORD, DFW, HKG, LON, or SYD).
IPAddress	String	Public IPv4 address of the Cloud Server.
IsDisabled	String	Indicates if the Rackspace Cloud Backup agent on the server is disabled. Valid values are true or false.
IsEncrypted	String	Indicates if backups are encrypted. Valid values are true or false.
MachineAgentId	String	ID that uniquely identifies a Cloud Backup agent.
MachineName	String	Name of the Cloud Server.
OperatingSystem	String	Operating system of Cloud Server.
OperatingSystemVersion	String	Operating system version of Cloud Server.
PublicKey	String	Public key of the public/private encryption key pair.
Status	String	Status of the Cloud Backup agent. Valid values are Online or Offline.
TimeOfLastSuccessfulBackup	String	Time of last successful backup.
UseServiceNet	String	Indicates if the Cloud Backup agent is using ServiceNet to backup data to Cloud Files. Valid values are true or false.
HostServerId	String	Server ID of the host server where the Cloud Backup agent is running.

Example: List agent details by host server ID JSON response

{
    "AgentVersion": "1.05.005848",
    "Architecture": "64-bit",
    "Flavor": "RaxCloudServer",
    "BackupVaultSize": "35.3 MB",
    "BackupContainer": "https://storage101.DC.clouddrive.com/v1/yourAccount/CloudBackup_v2_0_yourUUID",
    "CleanupAllowed": true,
    "Datacenter": "DFW",
    "IPAddress": "192.168.1.1",
    "IsDisabled": false,
    "IsEncrypted": true,
    "MachineAgentId": 213564,
    "MachineName": "Web Server",
    "OperatingSystem": "Windows Server 2012",
    "OperatingSystemVersion": "",
    "PublicKey": {
         "ModulusHex": "a5261939156948bb7a58dffe5ff89e65f0498f9175f5a 98288810b8975871e99af3b5dd94057b0fc07535f5f97444504fa35169d4 61d0d30cf0192e307727c065168c788771c561a9400fb61975e9e6aa4e23 fe11af69e9412dd23b0cb6684c4c2429bce139e848ab26d0829073351f4a cd36074eafd036a5eb83359d2a698d0",
        "ExponentHex": "09528"
    },
    "Status": "Online",
    "TimeOfLastSuccessfulBackup": "/Date(1357817400000)/",
    "UseServiceNet": "true",
    "HostServerId" :  "87c3b6e1-fb1a-41f9-91e5-313ae35a5a06"
}

Change log level

PUT /v1.0/{tenant_id}/agent/logging

This operation changes the current log level for a specified machine agent.

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
403	Forbidden	Access to the requested resource was denied.
500	Instance Fault	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.
503	Service Unavailable	This is a generic server error. The message contains the reason for the error. This error could wrap several error messages.

Request

This table shows the URI parameters for the request:

Name	Type	Description
{tenant_id}	String	The unique identifier of the tenant or account.

This table shows the body parameters for the request:

Name	Type	Description
MachineAgentId	String (Required)	Agent ID of the server we wish to change the log level on.
LoggingLevelId	String (Required)	Desired logging level from 1 (only FATAL) to 6 (ALL or TRACE).

Example: Change logging level request

MachineAgentId=1311839&LoggingLevelId=6

Response

This operation does not return a response body.