Snapshot Backup Operations

Use snapshot backup operations to manage share snapshot backups on Oracle Cloud Infrastructure Object Storage. To create a snapshot, see Snapshot and Clone Operations.

Snapshots that have the same name on different local systems can be backed up to the same cloud target because each snapshot backup is assigned a unique identifier. The same filesystem snapshot can be used for two cloud backups in two different formats.

You can delete a local snapshot after you have backed up that snapshot to the cloud. However, retain local snapshots that could be parent snapshots for future incremental snapshots. If the local snapshot has a retention hold, the snapshot cannot be deleted until the retention hold is released.

Table 9-3 Snapshot Backup Commands

Request	Append to Path: /api/storage/v2/pools/pool/projects/project Plus one of the following: /filesystems/fs or /luns/lun	Description
GET	/snapshots/snapshot/backups	List all snapshot backups of any format
GET	/snapshots/snapshot/backups/format/backup-id/target-id	List the specified snapshot backup
DELETE	/snapshots/snapshot/backups/format/backup-id/target-id	Delete the specified snapshot backup
POST	/snapshots/snapshot/backups	Create a new snapshot backup

List Snapshot Backups

The following example lists all cloud backups of any format of snapshot snap0 on filesystem f-1.

Example Request:

GET /api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap0/backups HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
User-Agent: curl/7.54.0
Accept: */*

Example Result:

HTTP/1.1 200 OK
Date: Wed, 07 Jan 2020 20:54:47 GMT
Content-Length: 708
X-Zfssa-Storage-Api: 2.0
Content-Type: application/json; charset=utf-8
X-Zfssa-Api-Version: 2.0

{
    "backups": [{
        "finished": "2020-01-07T21:02:14Z",
        "format": "tar",
        "href": "/api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap0/backups/tar/backup-id/target-id",
        "id": "backup-id",
        "status": "completed",
        "target": "target-id",
        "targetName": "oci-ashburn"
    }]
}

The following request lists the specified snapshot backup.

GET /api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap0/backups/format/backup-id/target-id HTTP/1.1

Create a Snapshot Backup

The following example creates a backup of snapshot snap0 in tar format and stores the backup on target oci-phoenix. The backup is created in zfs format if the format is not specified. To view the progress of the snapshot backup, use List Jobs to view the job with the returned job-id.

If snap0 has a parent backup, and that parent backup does not exist in the cloud, then specify require_parent_exists as false. By default, require_parent_exists is true, and the parent backup must exist in the cloud.

If the writelimit property is set for the target, no more than writelimit bytes per second are written to the target. See Create a Target.

When a snapshot backup with the zfs format has a retention hold, that hold is preserved when the cloud backup is later restored.

Example Request:

In the following request, snapshot snap0 either has no parent, or its parent already exists on oci-phoenix in tar format:

POST /api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap0/backups HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*
{
    "target": "oci-phoenix",
    "format": "tar"
}

In the following request, you want to create the backup even though the parent of snapshot snap0 does not exist on the target. The require_parent_exists flag is set to false:

POST /api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap0/backups HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*
{
    "target": "oci-phoenix",
    "format": "tar",
    "require_parent_exists": false
}

Example Result:

{
    "action": "job-id"
}

Create an Incremental Snapshot Backup

To create an incremental snapshot backup, specify true as the value for the incremental property and specify the parent snapshot to use in the comparison. In the following example, snap0 is the parent of snap1.

If snap0 does not exist in the cloud, then specify require_parent_exists as false. By default, require_parent_exists is true, and the parent snapshot must exist in the cloud.
If snap0 does exist in the cloud, then snap0 must exist both on the same local system and on the same cloud target as snap1. In the following example, snap0 must exist in filesystem f-1 on both the local system and the cloud target.
The parent and incremental filesystem snapshots must be the same format: zfs or tar.
When an incremental snapshot backup with the zfs format has a retention hold, that hold is preserved when the cloud backup is later restored.

The following request creates a backup of filesystem f-1 that is the difference between snap0 and the current state of filesystem f-1. The incremental snapshot backup, snap1, is stored on target oci-ashburn. The parent snapshot backup, snap0, already existed on target oci-ashburn. The incremental snapshot backup is in the same format as the parent snapshot backup.

Example Request:

POST /api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap1/backups HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

{
    "target":  "oci-ashburn",
    "incremental": true,
    "parent": "snap0"
}

Example Result:

{
    "action": "job-id"
}

Find the Parents of an Incremental Snapshot Backup

The following example identifies the parents of the specified incremental snapshot backup on the specified target. In this example, the parents of the backup of snapshot snap2 on target oci-ashburn are snapshots snap1 and snap0. The result shows that this appliance has access to both oci-ashburn and oci-phoenix targets. No results are shown for oci-phoenix because results are requested for oci-ashburn.

Example Request:

POST /api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap2/backups?props=true HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

{
    "target": "oci-ashburn"
}

Example Result:

HTTP/1.1 200 OK
Date: Wed, 22 Jan 2020 22:02:17 GMT
Content-Length: 316
X-Zfssa-Storage-Api: 2.0
Content-Type: application/json; charset=utf-8
X-Zfssa-Api-Version: 2.0

{
    "props": [{
        "choices": [
            "oci-ashburn",
            "oci-phoenix"
        ],
        "data_type": "string",
        "label": "Backup target",
        "name": "target"
    },{
        "choices": [
            "zfs",
            "tar"
        ],
        "data_type": "string",
        "label": "format",
        "name": "format"
    },{
        "choices": [
            true,
            false
        ],
        "data_type": "boolean",
        "label": "Incremental",
        "name": "incremental"
    },{
        "choices": [
            "snap1",
            "snap0"
        ],
        "data_type": "string",
        "label": "Parent",
        "name": "parent"
    }]
}

The following example uses GET instead of POST as an alternative way to identify the parents of the specified incremental snapshot backup. In this form, you do not need to specify the target. The results show no parents of snap2 on the oci-phoenix target, which means you cannot create an incremental backup of snap2 on oci-phoenix. You could create a full backup of snap2 on oci-phoenix.

Example Request:

GET /api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap2/targets HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

Example Result:

HTTP/1.1 200 OK
Date: Wed, 07 Jan 2020 22:04:08 GMT
Content-Length: 329
X-Zfssa-Storage-Api: 2.0
Content-Type: application/json; charset=utf-8
X-Zfssa-Api-Version: 2.0

{
    "targets": [{
        "format": "zfs",
        "href": "/api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap2/targets/zfs/target-id1",
        "id": "target-id1",
        "name": "oci-ashburn",
        "parents": [
            "snap0",
            "snap1"
        ]
    },{
        "format": "tar",
        "href": "/api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap2/targets/tar/target-id1",
        "id": "target-id1",
        "name": "oci-ashburn",
        "parents": [
            "snap0",
            "snap1"
        ]
    },{
        "id": "target-id2",
        "name": "oci-phoenix",
        "parents": [],
        "href": "/api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap2/targets/target-id2"
    }]
}

Use the following request to show the parents of a specified snapshot backup:

GET /api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap2/targets/format/target-id1 HTTP/1.1

Delete a Snapshot Backup

The following example removes the specified snapshot backup. To view the progress of the backup removal, use List Jobs to view the job with the returned job-id.

Example Request:

DELETE /api/storage/v2/pools/p1/projects/default/filesystems/f-1/snapshots/snap0/backups/format/backup-id/target-id HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

Example Result:

{
    "action": "job-id"
}