Getting started

Use the following information to learn how to authenticate, send API requests, and complete basic operations by using the Rackspace Cloud Backup API.

For more information about Cloud Backup concepts and API operations, see the API reference.

To start using the API and run the examples in this section, you need the following items:

Rackspace Cloud account. If you don’t have one, sign up for a Rackspace Cloud account.
Command-line tool or browser client for communicating with the API service.

Get your credentials

To communicate with Rackspace Cloud services by using the REST API, you need your Rackspace Cloud account username, API key, and account number.

Note

In the API documentation, the account number is referred to as your tenant ID or tenant name.

To get this information, log in to the Rackspace Cloud Control Panel.

Your account username is the username that you use to log in.
To get your account number, click the username menu in the top-right corner of the control panel. The account number is shown at the top of the menu.
To get your API key, follow the instructions in View and reset your API key.

Important

Protect your API key. Do not expose the value in code samples, screen captures, or insecure client-server communications. Also, ensure that the value is not included in source code that is stored in public repositories.

Send API requests to Cloud Backup

This section shows how to send requests by using cURL.

📘
Note: You can also use Rackspace Cloud API services by using the following methods:

If you are developing applications or automation, see OpenStack client applications.

For API development, testing and workflow management in a graphical environment, try interacting with the API by using an application such as Postman or RESTClient for Firefox.

cURL is a command-line tool that you can use to interact with REST interfaces. cURL lets you transmit and receive HTTP requests and responses from the command line or a shell script, which enables you to work with the API directly. cURL is available for Linux distributions, Mac OS® X, and Microsoft Windows®. For information about cURL, see http://curl.haxx.se/.

To run the cURL request examples shown in this guide on Mac OS® X or another Linux-based operating system, copy each example directly to the command line or a script.

📘
Note :If you are using Microsoft Windows, you need to adjust the cURL examples to run them. See Convert cURL examples to run on Windows.

🚧
The cURL examples in this guide are provided for reference only. Because the use of cURL has environmental dependencies, copying and pasting the examples might not work in your environment.

The following example shows a cURL command for sending an authentication request to the Identity service.

Example: cURL command for sending a JSON request

$ curl <https://identity.api.rackspacecloud.com/v2.0/tokens>  
 -X POST  
 -d '{"auth":{"RAX-KSKEY:apiKeyCredentials":{"username":"yourUserName","apiKey":"$apiKey"}}}'  
 -H "Content-type: application/json" | python -m json.tool

In this example, $apiKey is an environment variable that stores your API key value. Environment variables make it easier to reference account information in API requests, to reuse the same cURL commands with different credentials, and to keep sensitive information like your API key from being exposed when you send requests to Rackspace Cloud API services. For details about creating environment variables, see Configure environment variables.

📘
Note :The cURL request examples use a backslash (\) as a line-continuation symbol, which allows the command to continue across multiple lines.

The cURL examples in this guide use the following command-line options.

Option	Description
-d	Sends the specified data in a POST request to the HTTP server. Use this option to send a JSON request body to the server.
-H	Specifies an extra HTTP header in the request. You can specify any number of extra headers. Precede each header with the `-H` option. Common headers in Rackspace API requests are as follows: `Content-Type`: Required for operations with a request body. Specifies the format of the request body. Following is the syntax for the header where format is `json`: Content-Type: application/json `X-Auth-Token`: Required. Specifies the authentication token. `X-Auth-Project-Id`: Optional. Specifies the project ID, which can be your account number or another value. `Accept`: Optional. Specifies the format of the response body. Following is the syntax for the header where the format is `json`, which is the default: Accept: application/json
-i	Includes the HTTP header in the output.
-s	Specifies silent or quiet mode, which makes cURL mute. No progress or error messages are shown. If your cURL command is not generating any output, try replacing the `-s` option with `-i`.
-T	Transfers the specified local file to the remote URL.
-X	Specifies the request method to use when communicating with the HTTP server. The specified method is used instead of the default method, which is GET.

For commands that return a response, you can use json.tool to pretty-print the output. Append the following command to the cURL call:

| python -m json.tool

To use json.tool, import the JSON module. For information about json.tool, see JSON encoder and decoder.

If you run a Python version earlier than 2.6, import the simplejson module and use simplejson.tool. For information about simplejson.tool, see simplejson encoder and decoder.

If you do not want to pretty-print JSON output, omit this code.

📘
Note :If your request includes the -i option to show header output, do not try to pretty-print the output. Header information is not in JSON format, and the API service returns an error if you specify json.tool.

Convert cURL examples to run on Windows

The cURL examples in the Rackspace API documentation use syntax supported on Mac OS® X, Linux, and UNIX systems. Microsoft Windows does not support the same format. However, you can run the examples on Windows after making the following changes:

Replace all the line-continuation backslash characters (\) with a caret (^), and remove any trailing spaces after the ^.
If an example includes JSON data, export the data to a text file. When you run the cURL command, use the @filename syntax to import the JSON data. Save the JSON data files in a directory, and run cURL commands from that directory.

The following example shows the cURL format for Linux and UNIX systems:

$ curl <https://identity.api.rackspacecloud.com/v2.0/tokens>  
      -X POST  
      -d '{"auth":{"RAX-KSKEY:apiKeyCredentials":{"username":"yourUserName","apiKey":"$apiKey"}}}'  
      -H "Content-type: application/json"

The following example shows the same request with the changes made for Windows systems:

$ curl <https://identity.api.rackspacecloud.com/v2.0/tokens>  ^  
       -X POST ^  
       -d @credentials.txt  ^  
       -H "Content-type: application/json"

Authenticate to the Rackspace Cloud

Whether you use cURL, a REST client, or a command-line client (CLI) to send requests to the Rackspace Cloud Backup API, you need an authentication token to include in the X-Auth-Token header of each request. You get a token by submitting an authentication request with valid account credentials to the following Identity API service endpoint:

https://identity.api.rackspacecloud.com/v2.0

With a valid token, you can send API requests to any of the API service endpoints that you are authorized to use. The authentication response includes a token expiration date. When a token expires, you can send another authentication request to get a new one.

📘
Note :For more information about authentication tokens, see the following topics in the Identity API documentation:

Authentication token operations
The examples in this API guide show how to authenticate by using username and API key credentials, which is a more secure way to communicate with API services. The authentication token operations reference in the Identity API documentation describes other types of credentials that you can use for authentication.
Manage authentication tokens

Follow these steps to authenticate to the Rackspace Cloud by using cURL.

Send an authentication request
Review the authentication response
Configure environment variables

🚧
The cURL examples in this guide are provided for reference only. Because the use of cURL has environmental dependencies, copying and pasting the examples might not work in your environment.

Send an authentication request

From a command prompt, send a POST tokens request to the Rackspace Cloud Identity service. Include your username and API key, as shown in the following example.

$ curl <https://identity.api.rackspacecloud.com/v2.0/tokens>  
 -X POST  
 -d '{"auth":{"RAX-KSKEY:apiKeyCredentials":{"username":"yourUserName","apiKey":"$apiKey"}}}'  
 -H "Content-type: application/json" | python -m json.tool

Review the authentication response

If your credentials are valid, the Identity service returns an authentication response that includes the following information:

An authentication token
A service catalog with information about the services that you can access
User information and role assignments

📘
Note :For detailed information about the authentication response, see the Annotated authentication request and response in the Rackspace Cloud API documentation.

In the following example, the ellipsis (…) represents other service endpoints, which are not shown. The values shown in this and other examples vary because the information returned is specific to your account.

Example: Authentication response

{  
        "access": {  
                "token": {  
                        "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",  
                        "expires": "2014-11-24T22:05:39.115Z",  
                        "tenant": {  
                                "id": "110011",  
                                "name": "110011"  
                        },  
                        "RAX-AUTH:authenticatedBy": \[  
                                "APIKEY"  
                        \]  
                 },  
                "serviceCatalog": \[  
                        {  
                                "name": "cloudDatabases",  
                                "endpoints": \[  
                                        {  
                                        "publicURL": "<https://syd.databases.api.rackspacecloud.com/v1.0/110011">,  
                                        "region": "SYD",  
                                        "tenantId": "110011"  
                                        },  
                                        {  
                                                "publicURL": "<https://dfw.databases.api.rackspacecloud.com/v1.0/110011">,  
                                                "region": "DFW",  
                                                "tenantId": "110011"  
                                        },  
                                        {  
                                                "publicURL": "<https://ord.databases.api.rackspacecloud.com/v1.0/110011">,  
                                                "region": "ORD",  
                                                "tenantId": "110011"  
                                        },  
                                        {  
                                                "publicURL": "<https://iad.databases.api.rackspacecloud.com/v1.0/110011">,  
                                                "region": "IAD",  
                                                "tenantId": "110011"  
                                        },  
                                        {  
                                                "publicURL": "<https://hkg.databases.api.rackspacecloud.com/v1.0/110011">,  
                                                "region": "HKG",  
                                                "tenantId": "110011"  
                                        }  
                                \],  
                                "type": "rax:database"  
                        },

                    ...

                    {
                            "name": "cloudDNS",
                            "endpoints": \[
                                    {
                                            "publicURL": "https://dns.api.rackspacecloud.com/v1.0/110011",
                                            "tenantId": "110011"
                                    }
                            \],
                            "type": "rax:dns"
                    },
                    {
                            "name": "rackCDN",
                            "endpoints": \[
                                    {
                                            "internalURL": "https://global.cdn.api.rackspacecloud.com/v1.0/110011",
                                            "publicURL": "https://global.cdn.api.rackspacecloud.com/v1.0/110011",
                                            "tenantId": "110011"
                                    }
                            \],

                            "type": "rax:cdn"
                    }
            \],
            "user": {
                    "id": "123456",
                    "roles": \[
                            {
                                    "description": "A Role that allows a user access to keystone Service methods",
                                    "id": "6",
                                    "name": "compute:default",
                                    "tenantId": "110011"
                            },
                            {
                                    "description": "User Admin Role.",
                                    "id": "3",
                                    "name": "identity:user-admin"
                            }
                    \],
                    "name": "jsmith",
                    "RAX-AUTH:defaultRegion": "ORD"
            }
    }

}

If the request was successful, it returns the following values that you need to include when you make service requests to the Rackspace product API:

token ID

The token ID value is required to confirm your identity each time you access the service. Include it in the X-Auth-Token header for each API request.

The expires attribute indicates the date and time that the token will expire, unless it is revoked before the expiration. To get a new token, submit another authentication request. For more information, see Manage authentication tokens.

tenant ID

The tenant ID provides your account number. For most Rackspace Cloud service APIs, the tenant ID is appended to the API endpoint in the service catalog automatically. For Rackspace Cloud services, the tenant ID has the same value as the tenant name.

endpoint

The API endpoint provides the URL that you use to access the API service. For guidance on choosing an endpoint, see Service access.

If the request failed, review the response message and the following error message descriptions to determine next steps.

If you see the following error message, review the authentication request for syntax or coding errors. If you are using cURL, see Using cURL.
400 Invalid request body: unable to parse Auth data. Please review XML or
JSON formatting
If you see the following error message, verify the authentication credentials submitted in the authentication request. If necessary, contact your Rackspace Cloud Administrator or Rackspace Support to get valid credentials.
401 Unable to authenticate user with credentials provided.

📘
Note :For additional information about authentication errors, see the see the Identity API Reference documentation.

Configure environment variables

To make it easier to include the token ID, tenant ID, endpoint, and other values in API requests, use the export command to create environment variables that can be substituted for the actual values. For example, you can create an ENDPOINT variable to store the URL for accessing an API service. To reference the value in an API request, prefix the variable name with a $, for example $ENDPOINT.

📘
Note :The environment variables created with the export command are valid only for the current terminal session. If you start a new session, run the export commands again.

To reuse the variables across sessions, update the configuration file for your shell environment to include the export statements. For details about using and managing environment variables on different systems, see the environment variables wiki.

Create environment variables

In the token section of the authentication response, copy the token id and tenant id values from the token object. The following example shows example values only.

{
"access": {
"token": {
"id": "AA2345631l1NVdD6D1OCauKA0e9fioquZqVlS-hpbCqQ5Yx1zLOREGf4efBh10CfB5AvjC1yld4ZNJUouE7DA0QB0n5nRbdDsYADA-ORICIqHNqOVS_kYmedqDh75c_PLe123456789101",
"expires": "2015-11-18T18:35:45.013Z",
"tenant": {
"id": "123456",
"name": "123456"
},
"RAX-AUTH:authenticatedBy": [
"APIKEY"
]
},
Export the token ID to an environment variable that can be supplied in the X-Auth-Token header required in each API request.
```
$ export AUTH_TOKEN="token-id"
```
Replace token-id with the authentication token id value returned in the authentication response.
Export the tenant ID to an environment variable that can be supplied in requests that require you to specify a tenant ID or tenant name.
```
$ export TENANT_ID="tenant-id"
```
Replace tenant-id with the authentication token id value returned in the authentication response.

In the service catalog section of the authentication response, copy the publicURL value for the Rackspace Cloud Backup API, version, and region that you want to access.

This example shows the endpoints available for the Rackspace Cloud Backup API.

{  
        "endpoints": \[  
            {  
                "publicURL": "<https://backup.api.rackspacecloud.com/v1.0/123456">,  
                "tenantId": "123456"  
            },  
            {  
                "publicURL": "<https://iad.backup.api.rackspacecloud.com/v1.0/123456">,  
                "region": "IAD",  
                "tenantId": "123456"  
            },  
            {  
                "publicURL": "<https://hkg.backup.api.rackspacecloud.com/v1.0/123456">,  
                "region": "HKG",  
                "tenantId": "123456"  
            },  
            {  
                "publicURL": "<https://syd.backup.api.rackspacecloud.com/v1.0/123456">,  
                "region": "SYD",  
                "tenantId": "123456"  
            },  
            {  
                "publicURL": "<https://dfw.backup.api.rackspacecloud.com/v1.0/123456">,  
                "region": "DFW",  
                "tenantId": "123456"  
            },  
            {  
                "publicURL": "<https://ord.backup.api.rackspacecloud.com/v1.0/123456">,  
                "region": "ORD",  
                "tenantId": "123456"  
            }  
        \],  
        "name": "cloudBackup",  
        "type": "rax:backup"  
    }

📘
Note :For some services, the publicURL value for the API consists of the endpoint URL with the tenant ID for your account appended after the final /.

Export the URL to an environment variable, as shown in the following example:
```
$ export API_ENDPOINT="publicURL"
```
Replace publicURL with the publicURL value listed in the service catalog.

Cloud Backup concepts

To use the Rackspace Cloud Backup API effectively, you should understand several key concepts.

Agent

An agent is an executable that sits on your cloud server that knows how to perform backups and restores. Agent installation currently supports Windows and Unix or Linux platforms.

Backup

A group of folders, files, or both stored on Cloud Backup for a particular server and configuration.

Backup configuration

Backup configuration defines what needs to be backed up and when it needs to be backed up. The backup configuration includes a schedule for the backup, files to back up, and notifications.

Restore

Restore is a process of bringing your system back to a previously saved state, usually by using a backup as the checkpoint.

Restore configuration

A restore configuration defines what the restore checkpoint is and the where the backup should be restored.

Server setup

Because Cloud Backup is a file-level backup product, you must configure a separate backup for each cloud server and that a backup does not automatically apply to an entire environment. You must select the files and folders you want to back up from your cloud server. This setup requirement applies to Rackspace Cloud Servers, including the Performance Cloud Servers offering.

Create and manage backups

You can use the simple examples in the following sections for basic Cloud Backup requests that you will commonly use. You can get agent information, create backups, manage configurations, and work with restores by using Cloud Backup API operations. Example requests are provided in cURL, followed by the response.

Before running the examples, review the Cloud Backup concepts.

To start using the API and run the examples in this section, you need the following items:

Rackspace Cloud account. If you don’t have one, sign up for a Rackspace Cloud account.
Username and password to access the account
API key to access Rackspace Cloud services
Account number
Command-line tool or browser client for communicating with the API service.
Configured environment variables

Note

These examples use the $API_ENDPOINT, $AUTH_TOKEN, and $TENANT_ID environment variables to specify the API endpoint, authentication token, and project ID values for accessing the service. Make sure you configure these variables before running the code samples.

For more information about all Cloud Files operations, see the API reference.

Listing all agents for the user

The agent is an important component of Cloud Backup. You must install the agent on all servers that you want to back up. Documentation about installing agents is available from the link on Rackspace Control Panel under the Backup tab or at Install the agent on Linux. After the agent is installed on one or many servers, you can use the Cloud Backup API to configure your backups.

Note

If your account has the Managed Operations level of support, the Cloud Backup agent might already be installed on your server. If your cloud servers are listed under the Systems tab in the Backup section of the Cloud Control Panel, then the Cloud Backup agent is already installed. If it is not, Rackspace can install it for you. Check with your account manager.

Assuming that you initially know nothing about the environment, in order to do anything with the backups, you need to list the agents. After you list them, you can choose the one you want to work with. MachineAgentId is what you need to work with the agent in other requests.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) indicates that the request succeeded.

Example: cURL list all agents for the user request

curl -s -X GET $API_ENDPOINT/v1.0/$TENANT_ID/user/agents
-H "X-Auth-Token: $AUTH_TOKEN" | python -m json.tool

Example: List all agents for the user response

[
{
"AgentVersion": "1.10.006176",
"Architecture": "64-bit",
"BackupContainer": "https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS\_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/z\_DO\_NOT\_DELETE\_CloudBackup\_v2\_0\_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"BackupDatacenter": "DFW",
"BackupVaultSize": null,
"CleanupAllowed": true,
"Datacenter": "DFW",
"Flavor": "RaxCloudServer",
"HostServerId": "79aa4aa1-cd86-4416-a6c4-6942b7083130",
"IPAddress": "162.209.73.233",
"IsDisabled": false,
"IsEncrypted": false,
"MachineAgentId": 202743,
"MachineName": "web2",
"OperatingSystem": "Windows Server 2008 R2",
"OperatingSystemVersion": "6.1",
"PublicKey": {
"ExponentHex": 10001,
"ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C66268 0DD8A1BD83956051F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 5E15F3E55397B975B1896CFC66EBB5DD7D83587467A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D1218 867388632EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E02963471679D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD"
},
"Status": "Unknown",
"TimeOfLastSuccessfulBackup": null,
"UseFailoverUri": false,
"UseServiceNet": true
}
]

Listing agent details

To check whether the agent is online, list the agent’s details and check its status. If the agent is not online, Cloud Backup cannot run the backup job. Use MachineAgentId from List all agents for the user for yourMachineAgentID.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request succeeded.

Example: cURL list agent details request

curl -s -X GET $API_ENDPOINT/v1.0/$TENANT_ID/agent/yourMachineAgentID
-H "X-Auth-Token: $AUTH_TOKEN" | python -m json.tool

Example: List agent details response

{
"AgentVersion": "1.10.006176",
"Architecture": "64-bit",
"BackupContainer": "https://storage101.dfw1.clouddrive.com/v1/MossoCloudFS\_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/z\_DO\_NOT\_DELETE\_CloudBackup\_v2\_0\_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"BackupDatacenter": "DFW",
"BackupVaultSize": "35.3 KB",
"CleanupAllowed": true,
"Datacenter": "DFW",
"Flavor": "RaxCloudServer",
"HostServerId": "79aa4aa1-cd86-4416-a6c4-6942b7083130",
"IPAddress": "162.209.73.233",
"IsDisabled": false,
"IsEncrypted": false,
"MachineAgentId": 202743,
"MachineName": "web2",
"OperatingSystem": "Windows Server 2008 R2",
"OperatingSystemVersion": "6.1",
"PublicKey": {
"ExponentHex": 10001,
"ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C66268 0DD8A1BD83956051F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 5E15F3E55397B975B1896CFC66EBB5DD7D83587467A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D1218 867388632EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E02963471679D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD"
},
"Status": "Online",
"TimeOfLastSuccessfulBackup": null,
"UseFailoverUri": false,
"UseServiceNet": true
}

Creating a backup configuration

Create a backup configuration in which you define the following basic items:

The name of the backup
What you want to back up
When you want to back up
How often you want to back up

Look carefully at the Inclusions and Exclusions sections. Note that each exclusion must be within a folder that is included. If you like, you can programmatically create many configuration files like this with small changes for each server that you create.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request succeeded.

Example: cURL create a backup configuration request

curl -s -X POST $API_ENDPOINT/v1.0/$TENANT_ID/backup-configuration
-H "X-Auth-Token: $AUTH_TOKEN"
-H "Content-Type: application/json"
-d '{
"MachineAgentId": 202743,
"BackupConfigurationName": "Weekly Website Backup",
"IsActive": true,
"VersionRetention": 30,
"MissedBackupActionId": 1,
"Frequency": "Weekly",
"StartTimeHour": 7,
"StartTimeMinute": 30,
"StartTimeAmPm": "PM",
"DayOfWeekId": 5,
"HourInterval": null,
"TimeZoneId": "Eastern Standard Time",
"NotifyRecipients": "[email protected]",
"NotifySuccess": true,
"NotifyFailure": true,
"Inclusions": [
{
"FilePath": "C:\\backup_up_file.txt",
"FileItemType": "File"
},
{
"FilePath": "C:\\backed_up_folder",
"FileItemType": "Folder"
}
],
"Exclusions": [
{
"FilePath": "C:\\backed_up_folder\\excluded_file.txt",
"FileItemType": "File"
}
]
}' | python -m json.tool

Example: Create a backup configuration response

{
"BackupConfigurationId": 174084,
"BackupConfigurationName": "Weekly Website Backup",
"BackupConfigurationScheduleId": 173131,
"BackupPostscript": "",
"BackupPrescript": "",
"Datacenter": "DFW",
"DayOfWeekId": 5,
"EncryptionKey": {
"ExponentHex": 10001,
"ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C66268 0DD8A1BD83956051F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 5E15F3E55397B975B1896CFC66EBB5DD7D83587467A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D1218 867388632EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E02963471679D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD"
},
"Exclusions": [
{
"FileId": 657293,
"FileItemType": "File",
"FilePath": "C:\\backed_up_folder\\excluded_file.txt",
"FilePathEncoded": null,
"Filter": "Exclude",
"ParentId": 174084
}
],
"Flavor": "RaxCloudServer",
"Frequency": "Weekly",
"HourInterval": null,
"Inclusions": [
{
"FileId": 657291,
"FileItemType": "File",
"FilePath": "C:\\backup_up_file.txt",
"FilePathEncoded": null,
"Filter": "Include",
"ParentId": 174084
},
{
"FileId": 657292,
"FileItemType": "Folder",
"FilePath": "C:\\backed_up_folder",
"FilePathEncoded": null,
"Filter": "Include",
"ParentId": 174084
}
],
"IsActive": true,
"IsDeleted": false,
"IsEncrypted": false,
"LastRunBackupReportId": null,
"LastRunTime": null,
"MachineAgentId": 202743,
"MachineName": "web2",
"MissedBackupActionId": 1,
"NextScheduledRunTime": "/Date(1406935800000)/",
"NotifyFailure": true,
"NotifyRecipients": "[email protected]",
"NotifySuccess": true,
"StartTimeAmPm": "PM",
"StartTimeHour": 11,
"StartTimeMinute": 30,
"TimeZoneId": "Eastern Standard Time",
"VersionRetention": 30
}

Listing all backup configurations for an agent

To verify that your backup configuration exists, you can list all of the backup configurations for your agent. The output is similar to that in Create a backup configuration.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request succeeded.

Example: cURL list all backup configurations for an agent request

curl -s -X GET $API_ENDPOINT/v1.0/$TENANT_ID/backup-configuration/system/youMachineAgentID
-H "X-Auth-Token: $AUTH_TOKEN" | python -m json.tool

Example: List all backup configurations for an agent response

[
{
"BackupConfigurationId": 174084,
"BackupConfigurationName": "Weekly Website Backup",
"BackupConfigurationScheduleId": 173131,
"BackupPostscript": "",
"BackupPrescript": "",
"Datacenter": "DFW",
"DayOfWeekId": 5,
"EncryptionKey": {
"ExponentHex": 10001,
"ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C66268 0DD8A1BD83956051F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 5E15F3E55397B975B1896CFC66EBB5DD7D83587467A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D1218 867388632EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E02963471679D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD"
},
"Exclusions": [
{
"FileId": 657293,
"FileItemType": "File",
"FilePath": "C:\\backed_up_folder\\excluded_file.txt",
"FilePathEncoded": null,
"Filter": "Exclude",
"ParentId": 174084
}
],
"Flavor": "RaxCloudServer",
"Frequency": "Weekly",
"HourInterval": null,
"Inclusions": [
{
"FileId": 657291,
"FileItemType": "File",
"FilePath": "C:\\backup_up_file.txt",
"FilePathEncoded": null,
"Filter": "Include",
"ParentId": 174084
},
{
"FileId": 657292,
"FileItemType": "Folder",
"FilePath": "C:\\backed_up_folder",
"FilePathEncoded": null,
"Filter": "Include",
"ParentId": 174084
}
],
"IsActive": true,
"IsDeleted": false,
"IsEncrypted": false,
"LastRunBackupReportId": null,
"LastRunTime": null,
"MachineAgentId": 202743,
"MachineName": "web2",
"MissedBackupActionId": 1,
"NextScheduledRunTime": "/Date(1406935800000)/",
"NotifyFailure": true,
"NotifyRecipients": "[email protected]",
"NotifySuccess": true,
"StartTimeAmPm": "PM",
"StartTimeHour": 11,
"StartTimeMinute": 30,
"TimeZoneId": "Eastern Standard Time",
"VersionRetention": 30
}
]

Updating a backup configuration

To schedule the backup for one hour later, for example, you can update the backup configuration that you created earlier. Specify the BackupConfigurationId value in the URI. Send the same JSON content that you used in Create a backup configuration but make the following changes:

Add v2 to BackupConfigurationName.
Change StartTimeHour to 8.

The HTTP request must include a header to specify the authentication token.

This operation does not return a response body. An HTTP status code of 200 (OK) in the response indicates that the request succeeded.

Example: cURL update a backup configuration request

curl -i -X PUT $API_ENDPOINT/v1.0/$TENANT_ID/backup-configuration/yourBackupConfigurationID
-H "X-Auth-Token: $AUTH_TOKEN"
-H "Content-Type: application/json"
-d '{
"MachineAgentId": 202743,
"BackupConfigurationName": "Weekly Website Backup v2",
"IsActive": true,
"VersionRetention": 30,
"MissedBackupActionId": 1,
"Frequency": "Weekly",
"StartTimeHour": 8,
"StartTimeMinute": 30,
"StartTimeAmPm": "PM",
"DayOfWeekId": 5,
"HourInterval": null,
"TimeZoneId": "Eastern Standard Time",
"NotifyRecipients": "[email protected]",
"NotifySuccess": true,
"NotifyFailure": true,
"Inclusions": [
{
"FilePath": "C:\\backup_up_file.txt",
"FileItemType": "File"
},
{
"FilePath": "C:\\backed_up_folder",
"FileItemType": "Folder"
}
],
"Exclusions": [
{
"FilePath": "C:\\backed_up_folder\\excluded_file.txt",
"FileItemType": "File"
}
]
}' | python -m json.tool

You can verify that the configuration is updated by using the following cURL request, specifying the same BackupConfigurationId that you used in the update request.

Example: cURL list a backup configuration request

curl -s -X GET $API_ENDPOINT/v1.0/$TENANT_ID/backup-configuration/yourBackupConfigurationID
-H "X-Auth-Token: $AUTH_TOKEN" | python -m

Starting a backup manually

If you do not do anything, Cloud Backup runs the backup at the scheduled time.

If you want to run the backup once to ensure that it works, you can start the backup manually. Use the BackupConfigurationId to indicate the backup configuration that you want to run. You can run the backup job as many time as you like. A backup is created each time you run the job.

The HTTP request must include a header to specify the authentication token.

This operation does not return a response body. An HTTP status code of 200 (OK) in the response indicates that the request succeeded.

Example: cURL start a backup manually request

curl -i -X POST $API_ENDPOINT/v1.0/$TENANT_ID/backup/action-requested
-H "X-Auth-Token: $AUTH_TOKEN"
-H "Content-Type: application/json"
-d '{ "Action" : "StartManual",
"Id": yourBackupConfigurationId
}'

The response comes from the server. The number at the end of the response is the ID of the job.

Example: Start a backup manually response

HTTP/1.1 200 OK
...
Date: Thu, 31 Jul 2014 16:54:38 GMT

368785

When the backup is done, you receive an email about the status, as shown in the following example. Receiving the email is based on the NotifyRecipients, NotifySuccess, and NotifyFailure parameters that you specify when you create your backup configuration (see Create a backup configuration).

Example: Start a backup manually email

Rackspace Cloud Backup
Backed Up: Weekly Website Backup v2 on web2
Status: Completed
Started: 31 Jul 2014 16:54 UTC
Completed: 31 Jul 2014 16:54 UTC
Source: web02
Files Searched: 2 (4 KB)
Errors Encountered: 0

Checking backup status

You can verify whether your backup jobs ran properly, and if they did not, what errors occurred.

The HTTP request must include a header to specify the authentication token.

The following example output shows "CurrentState": "Queued". Other valid values for CurrentState are as follows:

Completed
CompletedWithErrors
Failed
InProgress
Missed
Preparing
Skipped
StartRequested
StartScheduled
Stopped
StopRequested

An HTTP status code of 200 (OK) in the response indicates that the request succeeded.

Example: cURL check backup status request

curl -s -X GET $API_ENDPOINT/v1.0/$TENANT_ID/backup/yourBackupID
-H "X-Auth-Token: $AUTH_TOKEN"
-H "Content-Type: application/json | python -m json.tool

Example: Check backup status response

{
"BackupId": 368785,
"BackupConfigurationId": 174084,
"CurrentState": "Queued",
"BackupConfigurationName": "Weekly Website Backup v2",
"MachineAgentId": 202743,
"MachineName": "web2",
"StateChangeTime": "/Date(1406935800000)/",
"IsEncrypted": false,
"EncryptionKey": {
"ExponentHex": 10001,
"ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C66268 0DD8A1BD83956051F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 5E15F3E55397B975B1896CFC66EBB5DD7D83587467A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D1218 867388632EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E02963471679D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD"
}
}

Listing activity for an agent

You can display all the activities for an agent to find out whether your backups ran successfully or failed. This operation is useful if you do not set email notifications when you create your backup configuration and want to create a report about the state of previous backups. The operation lists all in-progress and completed activity for an agent. Activity types are Backup, Cleanup, and Restore.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request succeeded.

Example: cURL list activity for an agent request

curl -s -X GET $API_ENDPOINT/v1.0/$TENANT_ID/system/activity/yourAgentID /
-H "X-Auth-Token: $AUTH_TOKEN"
-H "Content-Type: application/json" | python -m json.tool

Example: List activity for an agent response

[
{
"CurrentState": "Completed",
"DestinationDatacenter": "",
"DestinationMachineAgentId": 0,
"DestinationMachineName": "",
"DisplayName": "Cleanup",
"ID": 317083,
"IsBackupConfigurationDeleted": false,
"ParentId": 0,
"SourceDatacenter": "DFW",
"SourceMachineAgentId": 202743,
"SourceMachineName": "web2",
"TimeOfActivity": "/Date(1375816993000)/",
"Type": "Cleanup"
},
{
"CurrentState": "Completed",
"DestinationDatacenter": "",
"DestinationMachineAgentId": 0,
"DestinationMachineName": "",
"DisplayName": "Web2",
"ID": 5000325,
"IsBackupConfigurationDeleted": true,
"ParentId": 54020,
"SourceDatacenter": "DFW",
"SourceMachineAgentId": 202743,
"SourceMachineName": "web2",
"TimeOfActivity": "/Date(1375816984000)/",
"Type": "Backup"
}
]

Creating a restore configuration

Now that you have a backup, you can restore it to a different location on your server. You can also restore it to a different server, or to the same folder on the same server. You must set the BackupMachineId, DestinationMachineId, and DestinationPath values properly. BackupId identifies the backup that you want to use to restore.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request succeeded.

Example: cURL create a restore configuration request

curl -s -X PUT $API_ENDPOINT/v1.0/$TENANT_ID/restore /
-H "X-Auth-Token: $AUTH_TOKEN"
-H "Content-Type: application/json"
-d '{ "BackupId": 368785,
"BackupMachineId": 157512,
"DestinationMachineId": 157512,
"DestinationPath": "C:\\FolderPathForRestore\",
"OverwriteFiles": false }' | python -m json.tool

Example: Create a restore configuration response

{
"RestoreId": 1394,
"BackupId": 368785,
"DestinationMachineId": 157512,
"OverwriteFiles": false,
"BackupConfigurationId": 174084,
"BackupConfigurationName": "Weekly Website Backup v2",
"BackupRestorePoint": "\Date(1357151359000)\",
"BackupMachineId": 157512,
"BackupMachineName": "TestWindows1",
"BackupFlavor": "RaxCloudServer",
"DestinationMachineName": "TestWindows2",
"DestinationPath": "C:\\FolderPathForRestore\",
"IsEncrypted": false,
"EncryptedPassword": null,
"PublicKey": {
"ExponentHex": 10001,
"ModulusHex": "C6054E90E32D2B25E16F3A560E1B4DC580B1E4AB74E0C66268 0DD8A1BD83956051F6A526B16C55225D1BE6E0B1265F4085FB2F61B61337F5D32198E5CAFFEA CD50E90517A329146E43B20194C082A9C890060AD07A542FBC035B2A96F9F212C6D94887BECB 5E15F3E55397B975B1896CFC66EBB5DD7D83587467A0E7F669ADB925A7BE4C1ECED1BC9E92DB 768CE76FDC86CCDD04BDF469679FE3261AA66C22AC6263E540B79780AAF09CFC798CDC4D1218 867388632EA4BD1BF511E4881E07C5387DDDBE741E615ACA0C32A738F5B952F1C17051EC3BAF 9F64C629515EA2AF93E6BB450A8B1B3E02963471679D5670AF93CFEA649172EDA7AC5E071E2D 3AF0BD"
},
"RestoreStateId": 0
}

Starting a restore operation manually

You can manually run a restore operation that is based on a restore configuration. Use the RestoreId that was returned in Create a restore configuration. The following example is for an unencrypted restore operation. For an encrypted restore operation, you add the EncryptedPassword parameter with its value.

The HTTP request must include a header to specify the authentication token.

This operation does not return a response body. An HTTP status code of 204 (No Content) in the response indicates that the request succeeded.

Example: cURL start a restore manually request

curl -s -X POST $API_ENDPOINT/v1.0/$TENANT_ID/restore/action-requested
-H "X-Auth-Token: $AUTH_TOKEN"
-H "Content-Type: application/json"
-d '{"Action": "StartManual",
"Id": 1394 }'

When the restore is complete, you receive an email about the status, as shown in the following example. Receiving the email is based on the NotifyRecipients, NotifySuccess, and NotifyFailure parameters that you specify when you create your backup configuration (see Create a backup configuration).

Example: Start a restore manually email

Rackspace Cloud Backup
Status: Completed
Started: 01 Aug 2014 14:40 UTC
Completed: 01 Aug 2014 14:40 UTC
Destination: C:\\FolderPathForRestore\
Files Restored: 2 (4 KB)
Errors Encountered: 0

Getting a restore report

You can request a restore report that provides information about the restore operation and tells you if the operation ran successfully.

The HTTP request must include a header to specify the authentication token.

An HTTP status code of 200 (OK) in the response indicates that the request succeeded.

Example: cURL get a restore report request

curl -s -X GET $API_ENDPOINT/v1.0/$TENANT_ID/restore/report/yourRestoreID
-H "X-Auth-Token: $AUTH_TOKEN"
-H "Content-Type: application/json" | python -m json.tool

Example: Get a restore report response

{
"BackupConfigurationId": 174084,
"BackupConfigurationName": "Weekly Website Backup v2",
"BackupReportId": 2437160,
"CompletedTime": "/Date(1357151359000)/",
"Diagnostics": "No errors",
"Duration": "00:00:00",
"ErrorList": [],
"NumBytesRestored": "4 MB",
"NumErrors": "0",
"NumFilesRestored": "2",
"OriginatingComputerName": "web02",
"Reason": "Success",
"RestoreDestination": "TestWindows2",
"RestoreDestinationMachineId": 157512,
"RestorePoint": "/Date(1357151359000)/",
"StartTime": "/Date(1363790404000)/",
"State": "Completed"
}

Cloud Backup reports success. You can also check the folder listings on your server.

Deleting a backup configuration

You can delete the backup configuration file and verify that it was removed.

Note

Similarly, you can also delete a restore configuration by using the operation to delete a restore configuration.

The HTTP request must include a header to specify the authentication token.

This operation does not return a response body. An HTTP status code of 200 (OK) in the response indicates that the request succeeded.

Example: cURL delete a backup configuration request

curl -i -X DELETE $API_ENDPOINT/v1.0/$TENANT_ID/backup-configuration/yourBackupConfigurationID
-H "X-Auth-Token: $AUTH_TOKEN"

To verify that the backup configuration is deleted, list the backup configuration details to see IsDeleted: True.

Example: cURL list backup configuration details request

curl -s -X GET $API_ENDPOINT/v1.0/$TENANT_ID/backup-configuration/yourBackupConfigurationID
-H "X-Auth-Token: $AUTH_TOKEN" | python -m json.tool

Example: List backup configuration details response

{
"BackupConfigurationId": 174084,
"BackupConfigurationName": "Weekly Website Backup v2",
.....
"IsDeleted": true,
....
}

Getting started

Get your credentials

Send API requests to Cloud Backup

📘
Note: You can also use Rackspace Cloud API services by using the following methods:

📘
Note :If you are using Microsoft Windows, you need to adjust the cURL examples to run them. See Convert cURL examples to run on Windows.

🚧
The cURL examples in this guide are provided for reference only. Because the use of cURL has environmental dependencies, copying and pasting the examples might not work in your environment.

📘
Note :The cURL request examples use a backslash (`\`) as a line-continuation symbol, which allows the command to continue across multiple lines.

📘
Note :If your request includes the `-i` option to show header output, do not try to pretty-print the output. Header information is not in JSON format, and the API service returns an error if you specify json.tool.

Convert cURL examples to run on Windows

Authenticate to the Rackspace Cloud

📘
Note :For more information about authentication tokens, see the following topics in the Identity API documentation:

🚧
The cURL examples in this guide are provided for reference only. Because the use of cURL has environmental dependencies, copying and pasting the examples might not work in your environment.

Send an authentication request

Review the authentication response

📘
Note :For detailed information about the authentication response, see the Annotated authentication request and response in the Rackspace Cloud API documentation.

📘
Note :For additional information about authentication errors, see the see the Identity API Reference documentation.

Configure environment variables

📘
Note :The environment variables created with the `export` command are valid only for the current terminal session. If you start a new session, run the export commands again.

📘
Note :For some services, the `publicURL` value for the API consists of the endpoint URL with the tenant ID for your account appended after the final `/`.

Cloud Backup concepts

Agent

Backup

Backup configuration

Restore

Restore configuration

Server setup

Create and manage backups

Listing all agents for the user

Listing agent details

Creating a backup configuration

Listing all backup configurations for an agent

Updating a backup configuration

Starting a backup manually

Checking backup status

Listing activity for an agent

Creating a restore configuration

Starting a restore operation manually

Getting a restore report

Deleting a backup configuration

Get your credentials

Send API requests to Cloud Backup

📘Note: You can also use Rackspace Cloud API services by using the following methods:

📘Note :If you are using Microsoft Windows, you need to adjust the cURL examples to run them. See Convert cURL examples to run on Windows.

🚧The cURL examples in this guide are provided for reference only. Because the use of cURL has environmental dependencies, copying and pasting the examples might not work in your environment.

📘Note :The cURL request examples use a backslash (\) as a line-continuation symbol, which allows the command to continue across multiple lines.

📘Note :If your request includes the -i option to show header output, do not try to pretty-print the output. Header information is not in JSON format, and the API service returns an error if you specify json.tool.

Convert cURL examples to run on Windows

Authenticate to the Rackspace Cloud

📘Note :For more information about authentication tokens, see the following topics in the Identity API documentation:

🚧The cURL examples in this guide are provided for reference only. Because the use of cURL has environmental dependencies, copying and pasting the examples might not work in your environment.

Send an authentication request

Review the authentication response

📘Note :For detailed information about the authentication response, see the Annotated authentication request and response in the Rackspace Cloud API documentation.

📘Note :For additional information about authentication errors, see the see the Identity API Reference documentation.

Configure environment variables

📘Note :The environment variables created with the export command are valid only for the current terminal session. If you start a new session, run the export commands again.

📘Note :For some services, the publicURL value for the API consists of the endpoint URL with the tenant ID for your account appended after the final /.

Cloud Backup concepts

Agent

Backup

Backup configuration

Restore

Restore configuration

Server setup

Create and manage backups

Listing all agents for the user

Listing agent details

Creating a backup configuration

Listing all backup configurations for an agent

Updating a backup configuration

Starting a backup manually

Checking backup status

Listing activity for an agent

Creating a restore configuration

Starting a restore operation manually

Getting a restore report

Deleting a backup configuration

📘
Note: You can also use Rackspace Cloud API services by using the following methods:

📘
Note :If you are using Microsoft Windows, you need to adjust the cURL examples to run them. See Convert cURL examples to run on Windows.

🚧
The cURL examples in this guide are provided for reference only. Because the use of cURL has environmental dependencies, copying and pasting the examples might not work in your environment.

📘
Note :The cURL request examples use a backslash (`\`) as a line-continuation symbol, which allows the command to continue across multiple lines.

📘
Note :If your request includes the `-i` option to show header output, do not try to pretty-print the output. Header information is not in JSON format, and the API service returns an error if you specify json.tool.

📘
Note :For more information about authentication tokens, see the following topics in the Identity API documentation:

🚧
The cURL examples in this guide are provided for reference only. Because the use of cURL has environmental dependencies, copying and pasting the examples might not work in your environment.

📘
Note :For detailed information about the authentication response, see the Annotated authentication request and response in the Rackspace Cloud API documentation.

📘
Note :For additional information about authentication errors, see the see the Identity API Reference documentation.

📘
Note :The environment variables created with the `export` command are valid only for the current terminal session. If you start a new session, run the export commands again.

📘
Note :For some services, the `publicURL` value for the API consists of the endpoint URL with the tenant ID for your account appended after the final `/`.