Skip to main content

Who is this article for?

Code42 for EnterpriseSee product plans and features
CrashPlan for Small Business 

CrashPlan for Small Business, no.

Code42 for Enterprise, yes.

Link: Product plans and features.

This article applies to versions 6 and 7.

Other available versions:

Cloud | Version 5 | Version 4Link: What version am I on?

Code42 Support

Use the Code42 API to automate push restores

Who is this article for?

Code42 for EnterpriseSee product plans and features
CrashPlan for Small Business 

CrashPlan for Small Business, no.

Code42 for Enterprise, yes.

Link: Product plans and features.

This article applies to versions 6 and 7.

Other available versions:

Cloud | Version 5 | Version 4Link: What version am I on?

Overview

This tutorial explains how to use the Code42 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 Code42 administration console.

Considerations

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

  • Migrating devices to a new OS
  • Moving users to new devices
  • Restoring user data after imaging devices
  • Disaster recovery
  • Any time you need to perform similar restores

To use the API effectively and safely, we recommend you have a good working knowledge of the following:

Before you begin

  • A user with the Push Restore role is required. (the SYSADMIN role can also perform API-based restores.)
  • Test your scripts on a test user and test device before deploying them.
  • 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 creating your own custom script, contact your Customer Success Manager (CSM) to engage the Code42 Professional Services team. 
  • 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.

View PushRestoreJob API documentation

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 can download the script in one of two ways:

  • Use git:
    • From a command line, enter:
      git clone https://github.com/code42/crashplan_api_examples.git
    • This downloads the entire crashplan_api_examples directory, including the pushRestore.sh script.
  • Access the website:
    1. Navigate to our GitHub page.
    2. Click Raw.
    3. Copy the script directly from the browser window.

Step 2: Place the script on test device

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

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

Additionally, a scripted push restore can restore files and folders to any device running the Code42 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 (for example, using Unix/Linux chmod).

Step 3: Modify the script with 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. The following examples have sample values.

  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. CPUSER='jane.smithexample.com'
    • This variable must be set to a username that has the necessary permissions to perform the restore.
  3. sourceComputerGuid=8786789671511137204
    • This variable must be set to either the device name or GUID of the source device.
  4. acceptingComputerGuid=8786789671511137204
    • This variable must be set to either the device name or GUID of the destination device.
    • The destination device is often the same as the source device.
  5. 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.
  6. 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.
  7. restoreDate=20181211
    • This variable sets the date for the restore.
    • Enter the date as YYYYMMDD.
    • If left empty, the date used is the date when the restore script is run. 
  8. 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 pushrestore-<timestamp>.

To restore files to their original locations, use these optional parameters:

  • pushRestoreStrategy: Value may be "ORIGINAL_LOCATION" or "TARGET_DIRECTORY".
  • permitRestoreToDifferentOsVersion: Value may be "true" or "false".
  • existingFiles: Value may be may be "OVERWRITE_ORIGINAL" or "RENAME_ORIGINAL".
  • filePermissions: Value may be may be "CURRENT" or "ORIGINAL".

Step 4: Test the script

Run the script

Run the script while observing the Code42 app. The example below is run on an authority server running Linux by a system administrator who wants 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

Verify the restore with the device's file manager

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

Destination device file manager restore verification

Step 5: Modify the 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.

Step 6: Run the 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 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 the 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 to look for restores that failed.

Restores may fail if:

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

External resources