Navigation
This version of the documentation is archived and no longer supported. To learn how to upgrade your version of MongoDB Ops Manager, refer to the upgrade documentation.
You were redirected from a different version of the documentation. Click here to go back.

Restore Jobs

Overview

The restoreJobs resource allows you to manage restore jobs. A restore job is essentially a request to retrieve one of your existing snapshots, or a snapshot for a recent specific point-in-time, in order to restore a mongod to a previous state. To initiate a restore job, you must issue the request from an IP address on your user account’s whitelist.

Endpoints

Get All Restore Jobs for a Cluster

Get all restore jobs for a cluster. CLUSTER-ID must be the ID of either a replica set or a sharded cluster.

GET /api/public/v1.0/groups/GROUP-ID/clusters/CLUSTER-ID/restoreJobs

Using the batchId query parameter, you can retrieve all restore jobs in the specified batch. When creating a restore job for a sharded cluster, Ops Manager creates a separate job for each shard, plus another for the config server. Each of those jobs will be part of a batch. A restore job for a replica set, however, will not be part of a batch.

GET /api/public/v1.0/groups/GROUP-ID/clusters/CLUSTER-ID/restoreJobs?batchId=BATCH-ID

Get a Single Restore Job for a Cluster

GET /api/public/v1.0/groups/GROUP-ID/clusters/CLUSTER-ID/restoreJobs/JOB-ID

Get All Restore Jobs for a Legacy Mirrored Config Server

Get all restore jobs for a legacy mirrored config server (a config server that is not a replica set). HOST-ID is the ID of the config server. To get restore jobs for a config server that is a replica set, use CLUSTER-ID.

GET /api/public/v1.0/groups/GROUP-ID/hosts/HOST-ID/restoreJobs

Note

For information on running a config server as a replica set, see Create the Config Server Replica Set in the MongoDB manual.

Get a Single Restore Job for a Legacy Mirrored Config Server

Get a single restore job for a legacy mirrored config server (a config server that is not a replica set). HOST-ID is the ID of the config server. To get a single restore job for a config server that is a replica set, you must instead query for the restore job using CLUSTER-ID.

GET /api/public/v1.0/groups/GROUP-ID/hosts/HOST-ID/restoreJobs/JOB-ID

Create a Restore Job for a Cluster

Create a restore job for the specified CLUSTER-ID. You can create a restore job for either an existing snapshot or a custom snapshot. A custom snapshot is created from a specific point-in-time for a replica set or from a checkpoint for a sharded cluster.

POST /api/public/v1.0/groups/GROUP-ID/clusters/CLUSTER-ID/restoreJobs

The response body includes an array of restore jobs. When requesting a restore of a replica set, the array will contain a single element. For a sharded cluster, the array will contain one element for each shard, plus one for the config server. Each element will also include the batchId representing the batch to which the jobs belong.

The Create Restore Jobs examples describe each restore job type.

Create a Restore Job for a Legacy Mirrored Config Server

Create a restore job for a legacy mirrored config server (a config server that is not a replica set). HOST-ID is the ID of a config server that is not a replica set.

POST /api/public/v1.0/groups/GROUP-ID/hosts/HOST-ID/restoreJobs

Sample Entity

The following is one example of a return document. The fields in a return document depend on the type of restore and other factors:

{
  "id" : "53bd7f13e4b0a7304e226998",
  "groupId" : "525ec8394f5e625c80c7404a",
  "clusterId" : "53bc556ce4b049c88baec825",
  "snapshotId" : "53bd439ae4b0774946a16490",
  "created" : "2014-07-09T17:42:43Z",
  "timestamp" : {
    "date" : "2014-07-09T09:24:37Z",
    "increment" : 1
  },
  "statusName" : "FINISHED",
  "pointInTime" : false,
  "delivery" : {
    "methodName" : "HTTP",
    "url" : "https://api-backup.mongodb.com/backup/restore/v2/pull/ae6bc7a8bfdd5a99a0c118c73845dc75/53bd7f13e4b0a7304e226998/2292652411027442213/525ec8394f5e625c80c7404a-rs0-1404897877.tar.gz",
    "expires" : "2014-07-09T18:42:43Z",
    "expirationHours": 4,
    "maxDownloads": 1,
    "statusName" : "READY"
  },
  "encryptionEnabled": true
  "masterKeyUUID" : "1234-3456-4567-abcd-def0"
  "hashes" : [
    {
      "typeName": "SHA1",
      "fileName": "filename.0",
      "hash": "5h1DziNbqx9yY2VGJUz5RFnNco0="
    }
  ],
  "links" : [ ... ]
}

Entity Fields

Name Type Description
groupId string ID of the group that owns the restore job.
clusterId string ID of the cluster represented by the restore job.
snapshotId string ID of the snapshot to restore.
batchId string ID of the batch to which this restore job belongs. Only present for a restore of a sharded cluster.
hostId string ID of the config server to which this restore job belongs. Only present for a restore of a legacy mirrored config server.
created timestamp When the restore job was requested.
timestamp BSON timestamp Timestamp of the latest oplog entry in the restored snapshot.
statusName string

Current status of the job. Possible values are:

  • FINISHED
  • IN_PROGRESS
  • BROKEN
  • KILLED
pointInTime boolean Is this job for a point-in-time restore?
delivery object Additional details about how the restored snapshot data will be delivered.
delivery.methodName string

How the data will be delivered. Possible values are:

  • HTTP
  • SCP
delivery.url string The URL from which the restored snapshot data can be downloaded. Only present if delivery.methodName is HTTP.
delivery.expires timestamp Date after which the URL will no longer be available. Only present if delivery.methodName is HTTP.
delivery.expirationHours number The number of hours the download URL will be valid once the restore job is complete. Only present if delivery.methodName is HTTP.
delivery.maxDownloads number

The number of times the download URL can be used. This must be 1 or greater. For replica sets, the value of deliver.maxDownloads should match the number of data-bearing nodes in the destination cluster. For example, a restore job for a replica set with three nodes should set the value to 3 to ensure that each member is able to use the download URL. The default is 1, which means that the download URL is invalid after it is used once. In our example, the default value would allow only one member of a three node replica set to download the restore job.

Only present if delivery.methodName is HTTP.

delivery.statusName string

Current status of the downloadable file. Possible values are:

  • NOT_STARTED
  • IN_PROGRESS
  • READY
  • FAILED
  • INTERRUPTED
  • EXPIRED
  • MAX_DOWNLOADS_EXCEEDED
delivery.formatName string

Format in which data from an SCP restore should be written to the destination. Only present if delivery.methodName is SCP. Possible values are:

  • ARCHIVE
  • INDIVIDUAL
delivery.hostname string Hostname of the server to which the data should be written for an SCP restore. Only present if delivery.methodName is SCP.
delivery.port number Port to use for SCP. Only present if delivery.methodName is SCP.
username string Username to use for SCP. Only present if delivery.methodName is SCP.
password string Password to use for SCP. If delivery.methodName is SCP, then you must include this field when creating the restore job. However, it will never be exposed when a restore job entity is returned.
passwordTypeName string

Type of authentication to use for SCP. Only present if delivery.methodName is SCP. Possible values are:

  • PASSWORD
  • SSH_KEY
targetDirectory string Target directory to which the data should be written for an SCP restore. Only present if delivery.methodName is SCP.
hashes object array If the corresponding delivery.url has been downloaded, each document in this array is a mapping of a restore file to a hashed checksum. This array is present only after the file is downloaded. Note that for an HTTP restore, this array will only contain a single object representing the hash of the .tar.gz file.
encryptionEnabled boolean Indicates whether the restored snapshot data is encrypted.
masterKeyUUID string The KMIP master key ID used to encrypt the snapshot data. This field is present only if encryptionEnabled is true for the snapshot.
hashes.typeName string

The hashing algorithm used to compute the hash value. Possible values are:

  • SHA1
hashes.fileName string The name of the file that has been hashed.
hashes.hash string The hash of the file.

Examples

Get All Restore Jobs

Request

curl -i -u "username:apiKey" --digest "https://<ops-manager-host>/api/public/v1.0/groups/525ec8394f5e625c80c7404a/clusters/53bc556ce4b049c88baec825/restoreJobs"

Response

HTTP/1.1 200 OK

{
  "totalCount" : 2,
  "results" : [ {
    "id" : "53bd7f38e4b0a7304e226b3f",
    "groupId" : "525ec8394f5e625c80c7404a",
    "clusterId" : "53bc556ce4b049c88baec825",
    "snapshotId" : "53bd4356e4b0774946a16455",
    "created" : "2014-07-09T17:43:20Z",
    "timestamp" : {
      "date" : "2014-07-08T21:24:37Z",
      "increment" : 1
    },
    "statusName" : "FINISHED",
    "pointInTime" : false,
    "delivery" : {
      "methodName" : "HTTP",
      "url" : "https://api-backup.mongodb.com/backup/restore/v2/pull/ae6bc7a8bfdd5a99a0c118c73845dc75/53bd7f38e4b0a7304e226b3f/8924913772648127956/525ec8394f5e625c80c7404a-rs0-1404854677.tar.gz",
      "expires" : "2014-07-09T18:43:21Z",
      "expirationHours": 1,
      "maxDownloads": 1,
      "statusName" : "READY"
    },
    "links" : [ ... ]
  }, {
    "id" : "53bd7f13e4b0a7304e226998",
    "groupId" : "525ec8394f5e625c80c7404a",
    "clusterId" : "53bc556ce4b049c88baec825",
    "snapshotId" : "53bd439ae4b0774946a16490",
    "created" : "2014-07-09T17:42:43Z",
    "timestamp" : {
      "date" : "2014-07-09T09:24:37Z",
      "increment" : 1
    },
    "statusName" : "FINISHED",
    "pointInTime" : false,
    "delivery" : {
      "methodName" : "HTTP",
      "url" : "https://api-backup.mongodb.com/backup/restore/v2/pull/ae6bc7a8bfdd5a99a0c118c73845dc75/53bd7f13e4b0a7304e226998/2292652411027442213/525ec8394f5e625c80c7404a-rs0-1404897877.tar.gz",
      "expires" : "2014-07-09T18:42:43Z",
      "expirationHours": 1,
      "maxDownloads": 1,
      "statusName" : "READY"
    },
    "links" : [ ... ]
  } ],
  "links": [ ... ]
}

Get a Single Restore Job

Request

curl -i -u "username:apiKey" --digest "https://<ops-manager-host>/api/public/v1.0/groups/525ec8394f5e625c80c7404a/clusters/53bc556ce4b049c88baec825/restoreJobs/53bd7f13e4b0a7304e226998"

Response

HTTP/1.1 200 OK

{
  "id" : "53bd7f13e4b0a7304e226998",
  "groupId" : "525ec8394f5e625c80c7404a",
  "clusterId" : "53bc556ce4b049c88baec825",
  "snapshotId" : "53bd439ae4b0774946a16490",
  "created" : "2014-07-09T17:42:43Z",
  "timestamp" : {
    "date" : "2014-07-09T09:24:37Z",
    "increment" : 1
  },
  "statusName" : "FINISHED",
  "pointInTime" : false,
  "delivery" : {
    "methodName" : "HTTP",
    "url" : "https://api-backup.mongodb.com/backup/restore/v2/pull/ae6bc7a8bfdd5a99a0c118c73845dc75/53bd7f13e4b0a7304e226998/2292652411027442213/525ec8394f5e625c80c7404a-rs0-1404897877.tar.gz",
    "expires" : "2014-07-09T18:42:43Z",
    "expirationHours": 1,
    "maxDownloads": 1,
    "statusName" : "READY"
  },
  "links" : [ ... ]
}

Get a Restore Job for a Legacy Mirrored Config Server

Get a restore job for a legacy mirrored config server (a config server that is not a replica set).

Request

curl -i -u "username:apiKey" --digest "https://<ops-manager-host>/api/public/v1.0/groups/525ec8394f5e625c80c7404a/hosts/dafc9b422fa3b4795116e9115862cdd2/restoreJobs"

Response

HTTP/1.1 200 OK

{
  "created" : "2015-06-19T20:08:59Z",
  "delivery" : {
    "expires" : "2015-06-19T21:08:59Z",
    "methodName" : "HTTP",
    "statusName" : "READY",
    "url" : "https://api-backup.mongodb.com/backup/restore/v2/pull/fa16fef25e5753a9ff3a278d6e02f571/558476dbe4b08b5fb379a698/-6653753052034930159/config-0db2ee9eadfbed225a60057abcd4352b-1434744240-558476dbe4b08b5fb379a698.tar.gz",
    "expirationHours": 4,
    "maxDownloads": 2
  },
  "groupId" : "558452c9e4b06adf8b239d92",
  "hostId" : "0db2ee9eadfbed225a60057abcd4352b",
  "id" : "558476dbe4b08b5fb379a698",
  "links" : [ ... ],
  "pointInTime" : false,
  "snapshotId" : "558475dce4b082d419ce05f3",
  "statusName" : "FINISHED",
  "timestamp" : {
    "date" : "2015-06-19T20:04:00Z",
    "increment" : 1
  }
}

Create Restore Jobs

Create a Restore Job for an Existing Snapshot via HTTPS

Request

curl -i -u "username:apiKey" -H "Content-Type: application/json" --digest -X POST "https://<ops-manager-host>/api/public/v1.0/groups/525ec8394f5e625c80c7404a/clusters/53bc556ce4b049c88baec825/restoreJobs" --data '
{
  "snapshotId": "53bd439ae4b0774946a16490"
}'

Response

HTTP/1.1 200 OK

{
  "totalCount" : 1,
  "results" : [ {
    "id" : "53bd9f9be4b0a7304e23a8c6",
    "groupId" : "525ec8394f5e625c80c7404a",
    "clusterId" : "53bc556ce4b049c88baec825",
    "snapshotId" : "53bd439ae4b0774946a16490",
    "created" : "2014-07-09T20:01:31Z",
    "timestamp" : {
      "date" : "2014-07-09T09:24:37Z",
      "increment" : 1
    },
    "statusName" : "IN_PROGRESS",
    "pointInTime" : false,
    "links" : [ ... ]
  } ]
}

Create a Restore Job for an Existing Snapshot via SCP

Request

curl -i -u "username:apiKey" -H "Content-Type: application/json" --digest -X POST "https://<ops-manager-host>/api/public/v1.0/groups/525ec8394f5e625c80c7404a/clusters/53bc556ce4b049c88baec825/restoreJobs" --data '
{
  "snapshotId": "53bd439ae4b0774946a16490",
  "delivery": {
    "methodName": "SCP",
    "formatName": "ARCHIVE",
    "hostname": "dbserver.example.com",
    "port": 22,
    "username": "admin",
    "password": "secret",
    "passwordTypeName": "PASSWORD",
    "targetDirectory": "/data/backup"
  }
}'

Response

HTTP/1.1 200 OK

{
  "totalCount" : 1,
  "results" : [ {
    "id" : "53bd9f9be4b0a7304e23a8c6",
    "groupId" : "525ec8394f5e625c80c7404a",
    "clusterId" : "53bc556ce4b049c88baec825",
    "snapshotId" : "53bd439ae4b0774946a16490",
    "created" : "2014-07-09T20:01:31Z",
    "timestamp" : {
      "date" : "2014-07-09T09:24:37Z",
      "increment" : 1
    },
    "statusName" : "IN_PROGRESS",
    "pointInTime" : false,
    "delivery": {
      "methodName": "SCP",
      "formatName": "ARCHIVE",
      "hostname": "dbserver.example.com",
      "port": 22,
      "username": "admin",
      "password": "secret",
      "passwordTypeName": "PASSWORD",
      "targetDirectory": "/data/backup"
    },
    "links" : [ ... ]
  } ]
}

Create a Point-In-Time Restore Job for a Replica Set

Request

curl -i -u "username:apiKey" -H "Content-Type: application/json" --digest -X POST "https://<ops-manager-host>/api/public/v1.0/groups/525ec8394f5e625c80c7404a/clusters/53bc556ce4b049c88baec825/restoreJobs" --data '
{
  "timestamp": {
    "date": "2014-07-09T09:20:00Z",
    "increment": 0
  }
}'

Response

HTTP/1.1 200 OK

{
  "totalCount" : 1,
  "results" : [ {
    "id" : "53bda0dfe4b0a7304e23b54a",
    "groupId" : "525ec8394f5e625c80c7404a",
    "clusterId" : "53bc556ce4b049c88baec825",
    "created" : "2014-07-09T20:06:55Z",
    "timestamp" : {
      "date" : "2014-07-09T09:20:00Z",
      "increment" : 0
    },
    "statusName" : "IN_PROGRESS",
    "pointInTime" : true,
    "links" : [ ... ]
  } ]
}

Create a Checkpoint Restore Job for a Sharded Cluster

Request

curl -i -u "username:apiKey" -H "Content-Type: application/json" --digest -X POST "https://<ops-manager-host>/api/public/v1.0/groups/525ec8394f5e625c80c7404a/clusters/53ba256ce4e049c88baec825/restoreJobs" --data '
{
  checkpointId: "a74718cba2847387cd7"
}'

Response

HTTP/1.1 200 OK

Create a Restore Job for a Legacy Mirrored Config Server

Create a restore job for a legacy mirrored config server (a config server that is not a replica set).

Request

curl -i -u "username:apiKey" -H "Content-Type: application/json" --digest -X POST "https://<ops-manager-host>/api/public/v1.0/groups/525ec8394f5e625c80c7404a/hosts/dafc9b422fa3b4795116e9115862cdd2/restoreJobs" --data '
{
  "snapshotId": "558476dbe4b08b5fb379a698"
}'

Response

HTTP/1.1 200 OK