Skip to main content
Code42 Support

Using The Code42 API To Automate Push Restores

Applies to:
  • CrashPlan PROe

Overview

This tutorial explains how to use the Code42 environment's REST-based API to automate restoring a user's files and folders. More specifically, this method automates the device or push restore method, which can also be activated from the administration console.

Considerations

Automating restores allows administrators and help desk staff to more efficiently perform large numbers of restores. This is useful in various scenarios, such as:

  • Large-scale migration of devices to a new OS
  • Moving groups of users to new devices
  • Restoring user data after imaging large numbers of devices
  • Disaster recovery
  • Anytime you need to perform large numbers of similar restores

You should have a good working knowledge of the following to use the API effectively and safely:

Before you begin

  • A user with the Push Restore role is required (the SYSADMIN role is also able to do API-based restores)
  • You should test your scripts on a test user and test device before deploying it on a large scale
  • The example script used in this article is for demonstration purposes only. You can use it as the basis for your own solution, but your solution must be customized for your environment.
    For assistance with creating your own custom script, contact your PRO Services representative.
  • Confirm that you can access the Code42 API Documentation Viewer in order to reference the built-in API documentation.
Using the scripts in this article
Code42 does not guarantee the suitability of the example script for any purpose other than as a way to learn about our API's push restore capabilities. Use of this script without proper analysis, testing, modification for your environment, and validation could result in data loss.

API methods used

The example script in this article uses the following resources of the Code42 API:

  • Computer
  • DataKeyToken
  • PushRestoreJob
  • RestoreRecord
  • Server
  • WebRestoreSession

The available methods, as well as information on usage, syntax, and examples, are available through the API Documentation Viewer.

Example steps

The steps below are for example purposes only.

Step 1: Download the script from GitHub

The example script, pushRestore.sh, is located on GitHub. You may download the script in one of two ways:

Step 2: Place script on test device

A script that performs an automated restore can be run from:

  • An end user's device
  • An enterprise server (either a master server or storage server)
  • A computer, server, or workstation that is not running a CrashPlan app, as long as the device is able to communicate securely with the master server via SSL

Additionally, a scripted push restore can restore files and folders to any device running the CrashPlan app and which is an active device in your Code42 environment. The files and folders do not need to be restored to the original device. This gives administrators powerful flexibility in terms of planning and executing restores.

The pushRestore.sh script will run on any device that supports Bash shell scripting and has the curl utility installed.

To install the pushRestore.sh script:
  1. Copy the script to the device from which you want to run the restore
  2. Change the permissions of the script to allow execution of the script (e.g., using Unix/Linux chmod)

Step 3: Modify script by adding test parameters

Change the values of certain variables in the pushRestore.sh script to match your environment. Before making changes, you should first make a backup copy of the original script.

Test on sample data
Test this script in a separate environment with unimportant data before deploying this script on real users' data. For example, you might set up a virtual machine as a source and destination computer for the test restores.

Set the variables described below to values that test the script accurately for your environment.

  1. MASTER='https://192.0.2.100:4285'
    • This variable must be set to 'https://master-server.example.com:4285', where <master-server> is the IP address or fully qualified domain name (FQDN) of the master server in your Code42 environment
    • You may also use the http protocol on port 4280 (e.g. 'http://<master-server>:4280'), although this is less secure
  2. CPLOGIN='admin:admin'
    • This variable must be set to a username and password that has the necessary permissions to perform the restore
  3. sourceComputer=C02HT6EGF57J
    • This variable must be set to either the device name or GUID of the source device
    • This variable may also be passed to the script as a command-line argument (see below)
  4. destComputer=C02HT6EGF57J
    • This variable must be set to either the device name or GUID of the destination device
    • This variable may also be passed to the script as a command-line argument (see below)
    • The destination device is often the same as the source device
  5. restorePath='/tmp/mjohnson'
    • This variable is set to the pathname of the directory where you want the restored files to be placed
    • By default, the restored data will be placed in a subfolder of this folder named crashplan-restore-<timestamp>
    • This variable may also be passed to the script as a command-line argument (see below)
  6. getDirs=(
    "/Users/mjohnson/Documents/test"
    "/Users/mjohnson/Documents/Scratch Projects"
    )
    • This variable is an array containing a list of the directories (folders) to be restored. It can be empty if you are not restoring any directories
    • This variable may also be passed to the script as a command-line argument (see below)
  7. getFiles=(
    "/Users/mjohnson/Desktop/test.pdf"
    "/Users/mjohnson/Desktop/test2.pdf"
    "/Users/mjohnson/Desktop/test3.pdf"
    )
    • This variable is an array containing a list of the files to be restored. It can be empty if you are not restoring any files.
    • This variable may also be passed to the script as a command-line argument (see below)

Command-line arguments

Some of the parameters of the example script, pushRestore.sh, can be set using command-line arguments:

  • sourceComputer
  • destComputer
  • restorePath
  • getDirs
  • getFiles

The syntax for using the script with command-line arguments:

pushRestore.sh [sourceComputer] [destComputer] [restorePath] [getDirs] [getFiles]

If an argument is omitted (but keeping the two single quotes as placeholders for the missing argument), the script uses the value for the parameter which was defined in the script. If you do not want your script to fall back to a hard-coded value, leave the parameters set to a null value in the script.

Two examples of calling the script with command-line arguments follow.

The first one supplies arguments for all parameters:

pushRestore.sh 'C02HT6EGF57J' 'C02HT6EGF57J' '/home/jjohnson/Desktop/restore' '/Users/jjohnson/Documents' '/Users/jjohnson/Desktop/notes.rtf,/Users/jjohnson/Desktop/presentation.ppt'

The second example omits the sourceComputer and destComputer arguments, as they are hard-coded in the script:

pushRestore.sh '' '' '/home/jjohnson/Desktop/restore' '/Users/jjohnson/Documents' '/Users/jjohnson/Desktop/notes.rtf,/Users/jjohnson/Desktop/presentation.ppt'

Step 4: Test script

Run script

After placing the script on the test device and editing the script for your test environment, run the script while observing the CrashPlan app. The example below is run on a master server running Linux, by a system administrator who wishes to restore a file named PushRestoreTestAPI to a computer with the name Beta, and to a folder named TestPush on the desktop of Beta:

sysadmin@Alpha:~/Desktop/scripts$ ./pushRestore.sh
Setting up Session...
Detected MPC storage source...
Getting up Data Key Token...
Requesting restore from Beta:
            /home/joe/Desktop/PushRestoreTestAPI
...Pushed to /home/joe/Desktop/TestPush on Beta

Request / POST:                     {
            "webRestoreSessionId":"1f259k6fsrztm16b65atia5sj8",
            "sourceGuid":"620201442023571713",
            "targetNodeGuid":"627316733769679105",
            "acceptingGuid":"620201442023571713",
            "restorePath":"/home/joe/Desktop/TestPush",
            "pathSet":[
                {"type":"file", "path":"/home/joe/Desktop/PushRestoreTestAPI","selected":true}
            ],
            "numBytes":1,
            "numFiles":1,
            "showDeleted":true,
            "restoreFullPath":true
        }


Response from Server:     {"metadata":{"timestamp":"2014-03-21T16:02:21.878-05:00","params":{}},"data":{"restoreId":"628622388593950977","sourceId":"620201442023571713","acceptingGuid":"627316733769679105","userId":1,"done":false,"canceled":false,"providerDestination":false}}


Push Restore successfully submitted and accepted.
In progress... may take a few minutes.
Restored files in /home/joe/Desktop/TestPush

View CrashPlan app restore history

If the restore was successul, the CrashPlan app running on the target device will display a Restore Status message. Go to Restore to see the message, which displays the source of the restore, file/folder names, and destination:CrashPlan app Restore Status message

Verify restore using destination device's file manager

On the destination device, verify that the restored files and folders are present:

Destination device file manager restore verification

Step 5: Modify script for live deployment

After you have tested the script, modify it to automate the restores for one or more real users. In the case of the example script, pushRestore.sh, you could modify the script by using a looping construct such as for, while, or until to loop through the push restore methods, while passing each source and target device to the restore methods in the script.

Command-line arguments

Some of the parameters of the example script, pushRestore.sh, can be set using command-line arguments:

  • sourceComputer
  • destComputer
  • restorePath
  • getDirs
  • getFiles

The syntax for using the script with command-line arguments:

pushRestore.sh [sourceComputer] [destComputer] [restorePath] [getDirs] [getFiles]

If an argument is omitted (but keeping the two single quotes as placeholders for the missing argument), the script uses the value for the parameter which was defined in the script. If you do not want your script to fall back to a hard-coded value, leave the parameters set to a null value in the script.

Two examples of calling the script with command-line arguments follow.

The first one supplies arguments for all parameters:

pushRestore.sh 'C02HT6EGF57J' 'C02HT6EGF57J' '/home/jjohnson/Desktop/restore' '/Users/jjohnson/Documents' '/Users/jjohnson/Desktop/notes.rtf,/Users/jjohnson/Desktop/presentation.ppt'

The second example omits the sourceComputer and destComputer arguments, as they are hard-coded in the script:

pushRestore.sh '' '' '/home/jjohnson/Desktop/restore' '/Users/jjohnson/Documents' '/Users/jjohnson/Desktop/notes.rtf,/Users/jjohnson/Desktop/presentation.ppt'

Step 6: Run script

After double-checking your script's arguments or parameters, run the restore script.

Tips for checking your script:
  • Check that you are passing the parameters you want to pass. For example, are your lists of source and destination devices correct? Are any devices left out?
  • Consider redirecting the script's output to a file. This creates a record that the restores were successful and allows you to identify devices that failed to restore as expected.

Step 7: Review results

After the script has run, you can view the script's output directly from the terminal window, or from the file to which you redirected the output, in order to look for restores that failed. Restores may fail if:

  • The target device was not online
  • The master server was not online
  • The username and password combination used to authenticate to the master server was not valid
  • The username used to run the script did not have the necessary permissions and roles.

External resources