Snapshot and Clone Operations

All snapshot operations are scoped to a given pool or project. Snapshot operations can also be scoped to the filesystem or LUN level.

• The URI for all project-based snapshot operations begins with: /api/storage/v{1|2}/pools/pool/projects/project

• The URI for all filesystem-based snapshot operations begins with: /api/storage/v{1|2}/pools/pool/projects/project/filesystems/filesystem

• The URI for all LUN-based snapshot operations begins with: /api/storage/v{1|2}/pools/pool/projects/project/luns/lun

To back up a snapshot to the cloud, or restore a snapshot backup to Oracle ZFS Storage Appliance as a new share, see RESTful API Cloud Service.

Table 13-9 Snapshot and Clone Commands

Request	Append to Path /api/storage/v{1|2}	Description
GET	/snapshots	List all local snapshots
GET	/pools/pool/projects?snaps=true	List all projects, including snapshots
GET	/pools/pool/projects/project/filesystems?snaps=true	List all filesystems, including snapshots
GET	/pools/pool/projects/project/luns?snaps=true	List all LUNs, including snapshots
GET	/pools/pool/projects/project/snapshots	List all snapshots for a project
GET	/pools/pool/projects/project/filesystems/filesystem/snapshots	List all snapshots for a filesystem
GET	/pools/pool/projects/project/luns/lun/snapshots	List all snapshots for a LUN
GET	/pools/pool/projects/project/snapshots/snapshot	Get project snapshot details
GET	/pools/pool/projects/project/filesystems/filesystem/snapshots/snapshot	Get filesystem snapshot details
GET	/pools/pool/projects/project/luns/lun/snapshots/snapshot	Get LUN snapshot details
POST	/pools/pool/projects/project/snapshots	Create a project snapshot
POST	/pools/pool/projects/project/filesystems/filesystem/snapshots	Create a filesystem snapshot
POST	/pools/pool/projects/project/luns/lun/snapshots	Create a LUN snapshot
PUT	/pools/pool/projects/project/snapshots/snapshot	Modify a project snapshot
PUT	/pools/pool/projects/project/filesystems/filesystem/snapshots/snapshot	Modify a filesystem snapshot
PUT	/pools/pool/projects/project/luns/lun/snapshots/snapshot	Modify a LUN snapshot
PUT	/pools/pool/projects/project/filesystems/filesystem/snapshots/snapshot/clone	Clone a filesystem snapshot
PUT	/pools/pool/projects/project/luns/lun/snapshots/snapshot/clone	Clone a LUN snapshot
PUT	/pools/pool/projects/project/filesystems/filesystem/snapshots/snapshot/rollback	Rollback data to the given filesystem snapshot
PUT	/pools/pool/projects/project/lun/lun/snapshots/snapshot/rollback	Rollback data to the given LUN snapshot
DELETE	/pools/pool/projects/project/snapshots/snapshot	Destroy a project snapshot
DELETE	/pools/pool/projects/project/filesystems/filesystem/snapshots/snapshot	Destroy a filesystem snapshot
DELETE	/pools/pool/projects/project/luns/lun/snapshots/snapshot	Destroy a LUN snapshot
GET	/pools/pool/projects/project/snapshots/snapshot/dependents	List project snapshot dependents
GET	/pools/pool/projects/project/filesystems/filesystem/snapshots/snapshot/dependents	List filesystem snapshot dependents
GET	/pools/pool/projects/project/lun/lun/snapshots/snapshot/dependents	List LUN snapshot dependents
POST	/pools/pool/projects/project/automatic	Create a new project automatic snapshot object
POST	/pools/pool/projects/project/automatic?convert=true	Create a new project automatic snapshot object. Optionally, set a retention hold. Existing auto-generated snapshots that do not fit new schedules are converted to manual snapshots. Excluding the convert property causes existing auto-generated snapshots to be destroyed. If the snapshots have a retention hold, the convert property setting does not change the retention hold nor can the snapshots be converted to manual snapshots.
GET	/pools/pool/projects/project/automatic/automatic	Get the specified project automatic snapshot properties
GET	/pools/pool/projects/project/automatic	List all project automatic snapshot objects
PUT	/pools/pool/projects/project/automatic/automatic	Modify the specified project automatic snapshot object
PUT	/pools/pool/projects/project/automatic/automatic?convert=true	Modify the specified project automatic snapshot schedule object. Optionally, modify the retention hold setting. Existing auto-generated snapshots that do not fit new schedules are converted to manual snapshots. Excluding the convert property causes existing auto-generated snapshots to be destroyed. If the snapshots have a retention hold, the convert property setting does not change the retention hold nor can the snapshots be converted to manual snapshots.
DELETE	/pools/pool/projects/project/automatic/automatic	Destroy the specified automatic object
DELETE	/pools/pool/projects/project/automatic/automatic?convert=true	Destroy the specified automatic snapshot schedule object. Existing auto-generated snapshots that do not fit new schedules are converted to manual snapshots. Excluding the convert property causes existing auto-generated snapshots to be destroyed. If the snapshots have a retention hold, the convert property setting does not change the retention hold nor can the snapshots be converted to manual snapshots.
POST	/pools/pool/projects/project/filesystems/filesystem/automatic	Create a new filesystem automatic snapshot object
POST	/pools/pool/projects/project/filesystems/filesystem/automatic?convert=true	Create a new filesystem automatic snapshot object. Optionally, set a retention hold. Existing auto-generated snapshots that do not fit new schedules are converted to manual snapshots. Excluding the convert property causes existing auto-generated snapshots to be destroyed. If the snapshots have a retention hold, the convert property setting does not change the retention hold nor can the snapshots be converted to manual snapshots.
GET	/pools/pool/projects/project/filesystems/filesystem/automatic/automatic	Get the specified filesystem automatic snapshot properties
GET	/pools/pool/projects/project/filesystems/filesystem/automatic	List all filesystem automatic snapshot objects
PUT	/pools/pool/projects/project/filesystems/filesystem/automatic/automatic	Modify the specified filesystem automatic snapshot object
PUT	/pools/pool/projects/project/filesystems/filesystem/automatic/automatic?convert=true	Modify the specified filesystem automatic snapshot schedule object. Optionally, modify the retention hold setting. Existing auto-generated snapshots that do not fit new schedules are converted to manual snapshots. Excluding the convert property causes existing auto-generated snapshots to be destroyed. If the snapshots have a retention hold, the convert property setting does not change the retention hold nor can the snapshots be converted to manual snapshots.
DELETE	/pools/pool/projects/project/filesystems/filesystem/automatic/automatic	Destroy the specified automatic snapshot schedule object
DELETE	/pools/pool/projects/project/filesystems/filesystem/automatic/automatic?convert=true	Destroy the specified filesystem automatic snapshot schedule object. Existing auto-generated snapshots that do not fit new schedules are converted to manual snapshots. Excluding the convert property causes existing auto-generated snapshots to be destroyed. If the snapshots have a retention hold, the convert property setting does not change the retention hold nor can the snapshots be converted to manual snapshots.
POST	/pools/pool/projects/project/luns/lun/automatic	Create a new LUN automatic snapshot
POST	/pools/pool/projects/project/luns/lun/automatic?convert=true	Create a new LUN automatic snapshot schedule. Optionally, set a retention hold. Existing auto-generated snapshots that do not fit new schedules are converted to manual snapshots. Excluding the convert property causes existing auto-generated snapshots to be destroyed. If the snapshots have a retention hold, the convert property setting does not change the retention hold nor can the snapshots be converted to manual snapshots.
GET	/pools/pool/projects/project/luns/lun/automatic/automatic	Get the specified LUN automatic snapshot properties
GET	/pools/pool/projects/project/luns/lun/automatic	List all LUN automatic snapshot objects
PUT	/pools/pool/projects/project/luns/lun/automatic/automatic	Modify the specified LUN automatic snapshot object
PUT	/pools/pool/projects/project/luns/lun/automatic/automatic?convert=true	Modify the specified LUN automatic snapshot schedule object. Optionally, modify the retention hold setting. Existing auto-generated snapshots that do not fit new schedules are converted to manual snapshots. Excluding the convert property causes existing auto-generated snapshots to be destroyed. If the snapshots have a retention hold, the convert property setting does not change the retention hold nor can the snapshots be converted to manual snapshots.
DELETE	/pools/pool/projects/project/luns/lun/automatic/automatic	Destroy the specified LUN automatic object
DELETE	/pools/pool/projects/project/luns/lun/automatic/automatic?convert=true	Destroy the specified LUN automatic snapshot schedule object. Existing auto-generated snapshots that do not fit new schedules are converted to manual snapshots. Excluding the convert property causes existing auto-generated snapshots to be destroyed. If the snapshots have a retention hold, the convert property setting does not change the retention hold nor can the snapshots be converted to manual snapshots.

List Snapshots

Lists available snapshots on an Oracle ZFS Storage Appliance system. Depending on the request URI, the list contains project, filesystem, or LUN snapshots.

Table 13-10 List Snapshot Command Forms

Command	Append to Path /api/storage/v{1|2}/pools/pool/projects/project
List project snapshots	/snapshots
List filesystem snapshots	/filesystems/share/snapshots
List LUN snapshots	/lun/share/snapshots

Example Request:

GET /api/storage/v1/pools/p1/projects/default/snapshots
Accept: application/json

Example Result:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "snapshots": [{
        "canonical_name": "p1/local/default@snap-001",
        "collection": "local",
        "creation": "20211104T11:00:00",
        "href": "/api/storage/v1/pools/p1/projects/default/snapshots/snap-001",
        "id": "1bc742f1-6a56-bf7c-0000-000000000000",
        "isauto": false,
        "name": "snap-001",
        "numclones": 0,
        "pool": "p1",
        "project": "default",
        "retentionpolicy": "off",
        "shadowsnap": false,
        "space_data": 31744,
        "space_unique": 0,
        "type": "snapshot"
    }, {

        "canonical_name": "p1/local/default@snap-002",
        "collection": "local",
        "creation": "20211104T11:00:07",
        "href": "/api/storage/v1/pools/p1/projects/default/snapshots/snap-002",
        "id": "24927817-ac89-5071-0000-000000000000",
        "isauto": false,
        "name": "snap-002",
        "numclones": 0,
        "pool": "p1",
        "project": "default",
        "retentionpolicy": "unlocked",
        "shadowsnap": false,
        "space_data": 31744,
        "space_unique": 0,
        "type": "snapshot"
    }]
}

Get Snapshot

View all information about a single snapshot. Returns HTTP status 200 (OK) on success.

Example Request:

GET /api/storage/v1/pools/p1/projects/default/snapshots/snap-001
Accept: application/json

Example Result:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "snapshot": {
        "canonical_name": "p1/local/default@snap-001",
        "collection": "local",
        "creation": "20211104T11:00:00",
        "href": "/api/storage/v1/pools/p1/projects/default/snapshots/snap-001",
        "id": "1bc742f1-6a56-bf7c-0000-000000000000",
        "isauto": false,
        "name": "snap-001",
        "numclones": 0,
        "pool": "p1",
        "project": "default",
        "retentionpolicy": "off",
        "shadowsnap": false,
        "space_data": 31744,
        "space_unique": 0,
        "type": "snapshot"
    }
}

Create Snapshot

The create snapshot command creates snapshots for projects, filesystems, or LUNs.

• Create Project Snapshot – POST /pools/pool/projects/project/snapshots

• Create Filesystem Snapshot – POST /pools/pool/projects/project/filesystems/share/snapshots

• Create Volume Snapshot – POST /pools/pool/projects/project/luns/lun/snapshots

Optionally, you can set a retention policy:

• If the snapshot is a project snapshot, the retention settings also apply to all of its shares.

• For a manual snapshot object, you can set the retention policy property to off or unlocked.

• For an automatic snapshot schedule object, you can set the retentionpolicy property to off or locked. If locked, set the corresponding retentionhold value, which must be the same or less than the keep value.

• When creating a new automatic snapshot schedule object and setting the convert property to true, existing auto-generated snapshots that do not fit new schedules are converted to manual snapshots. Excluding the convert property or setting it to false causes existing auto-generated snapshots to be destroyed. If the snapshots have a retention hold, the convert property setting does not change the retention hold nor can the snapshots be converted to manual snapshots.

To use the snapshot retention hold feature, apply deferred update "Support for Snapshot Retention." For information about deferred updates, see Deferred Updates in Oracle ZFS Storage Appliance Customer Service Manual, Release OS8.8.x. To understand the required user role authorizations, see Taking a Snapshot (CLI) in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x and Scheduling Snapshots (CLI) in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Example Request:

Route retention can be used instead of route retentionpolicy. Both are the same.

POST /api/storage/v1/pools/p1/projects/default/snapshots
Content-Type: application/json

{
    "name": "initial-backup", 
    "retentionpolicy": "unlocked"
}

Example Result:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /pools/p1/projects/default/snapshot/initial-backup

{
    "snapshot": {
        "name": "initial-backup",
        "numclones": 0,
        "creation": "20130610T21:00:49",
        "collection": "local",
        "project": "default",
        "canonical_name": "zfs-storage-1/local/default@initial-backup",
        "usage": {
            "unique": 0.0,
            "loading": false,
            "data": 145408.0
        },
        "type": "snapshot",
        "id": "a26abd24-e22b-62b2-0000-000000000000",
        "pool": "p1",
        "retention": "unlocked"
    }
}

Rename Snapshot

Renames an existing snapshot.

• Request URI – Snapshot, the current snapshot name

• Request Body – JSON object with name parameter containing new snapshot name

Optionally, you can modify the retention policy setting while in this same path:

• If the snapshot is a project snapshot, the retention settings also apply to all of its shares.

• For a manual snapshot object, you can modify the retention policy property to off or unlocked, as appropriate.

• If automatic snapshots containing a retention hold have been generated with this schedule, the retentionhold property must be set to a higher value to prevent early lock removal, but not higher than the keep property. If no automatic snapshots have been generated with this schedule, the retention hold can be set to a lower value.

To use the snapshot retention hold feature, apply deferred update "Support for Snapshot Retention." For information about deferred updates, see Deferred Updates in Oracle ZFS Storage Appliance Customer Service Manual, Release OS8.8.x. To understand the required user role authorizations, see Renaming a Snapshot (CLI) in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x and Editing a Snapshot Retention Policy (CLI) in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Example Request:

PUT /api/storage/v1/pools/p1/projects/default/snapshots/initial-snapshot
Content-Type: application/json
Accept: application/json

{
    "name": "old-snapshot"
}

Example Result:

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /pools/p1/projects/default/snapshot/initial-backup

Clone Snapshot

Makes a new filesystem or LUN from an existing snapshot.

The following URI parameters are used:

• pool - Source pool name
• project - Source project name
• filesystem - Source share name for filesystem snapshot
• lun - Source share name for LUN snapshot
• snapshot - Source snapshot name

Clone a filesystem:

PUT /pools/pool/projects/project/filesystems/share/snapshots/snapshot/clone

Clone a volume:

PUT /pools/pool/projects/project/luns/lun/snapshots/snapshot/clone

Request body contains a JSON object with the following properties.

The clone will have the same retention hold setting as the original snapshot. To apply or remove a retention hold for the clone, make a snapshot of the clone and specify a new retention hold setting. To use the snapshot retention hold feature, apply deferred update "Support for Snapshot Retention." For information about deferred updates, see Deferred Updates in Oracle ZFS Storage Appliance Customer Service Manual, Release OS8.8.x.

Table 13-11 Clone Snapshot Properties

Property	Type	Description
pool	string	Destination clone pool name
project	string	Destination clone project name
lun	string	Destination LUN name for LUN snapshot

Example Request:

PUT /api/storage/v1/pools/p1/projects/default/filesystems/fs01/snapshots/snap01/clone

{
    "project":"rest", 
    "share":"snap01clone01", 
    "compression": "gzip-9"
}

Example Result:

HTTP/1.1 201 Created
Content-Length: 2035
X-Zfssa-Storage-Api: 1.0
Location: /api/storage/v1/pools/p1/projects/rest/filesystem/snap01clone01
Content-Type: application/json; charset=utf-8

{
    "filesystem": {
        "origin": {
            "project": "default",
            "share": "fs01",
            "snapshot": "snap01",
            "pool": "p1",
            "collection": "local"
        },
        "href": "/api/storage/v1/pools/p1/projects/rest/filesystems/snap01clone01",
        "mountpoint": "/export/snap01clone01",
        "compression": "gzip-9",
        "source": {
            "compression": "local",
            ...
        },
        ...
       "canonical_name": "zfs-storage-1/local/rest/snap01clone01"
   }
} 

Rollback Snapshot

The rollback snapshot causes the source file system or LUN to be modified back to its state when the snapshot was taken. Successful response returns HTTP status 202 (Accepted), as well as the snapshot properties in JSON format.

The rollback is not allowed if the rollback would remove recent snapshots with a retention hold.

The following URI parameters are used:

• pool - Source pool name
• project - Source project name
• filesystem - Source filesystem name for filesystem snapshot
• lun - Source LUN name for LUN snapshot
• snapshot - Source snapshot name

Rollback a filesystem snapshot:

PUT /pools/pool/projects/project/filesystems/filesystem/snapshots/snapshot/rollback

Rollback a LUN snapshot:

PUT /pools/pool/projects/project/luns/lun/snapshots/snapshot/rollback

Example Request:

PUT /api/storage/v1/pools/p1/projects/default/filesystems/fs-01/snapshots/initial-backup/rollback

Example Result:

HTTP/1.1 202 Accepted
Location: /pools/p1/projects/default/filesystems/fs-01/snapshot/fs-01-initial-clone
Content-Type: application/json

{
    "snapshot": {
        "name": "fs-01-initial-clone",
        "numclones": 0,
        "creation": "20130610T21:00:49",
        "filesystem": "fs-01",
        "collection": "local",
        "project": "default",
        "canonical_name": "zfs-storage-1/local/default/
               fs-01@fs-01-initial-clone",
        "usage": {
            "unique": 0.0,
            "loading": false,
            "data": 31744.0
        },
        "type": "snapshot",
        "id": "5c9bda07-21c1-2238-0000-000000000000",
        "pool": "p1"
    }
}

Delete a Snapshot

The DELETE snapshot command deletes a project, filesystem, or LUN snapshot from the Oracle ZFS Storage Appliance system.

The following URI parameters are used:

• pool - Source pool name
• project - Source project name
• filesystem - Source filesystem name
• lun - LUN name
• snapshot - Source snapshot name

Delete a project snapshot:

DELETE /api/storage/v1/pools/pool/projects/project/snapshots/snapshot

Delete a filesystem snapshot:

DELETE /api/storage/v1/pools/pool/projects/project/filesystems/filesystem/snapshots/snapshot

Delete a filesystem LUN:

DELETE /api/storage/v1/pools/pool/projects/project snapshot

If the snapshot has an NDMP hold on it, add ?confirm=true to the DELETE command. Note, however, that this could adversely affect NDMP operations. For more information, see NDMP Configuration in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Before a manual snapshot with a retention hold can be deleted, the hold type must be off. To modify a manual snapshot from unlocked to off, use the PUT operation.

An error message might warn that existing automatic snapshots could be destroyed. If the snapshot or its children are actively changing, an error message indicates that the snapshot schedule cannot be removed. Also, if the schedule contains locked automatic snapshots, the schedule cannot be removed until the retention holds expire. If the automatic snapshot schedule has a retention hold but no snapshots have been generated, the schedule can be removed. If the snapshot is a project snapshot, the schedule will also be removed from its shares.

To use the snapshot retention hold feature, apply deferred update "Support for Snapshot Retention." For information about deferred updates, see Deferred Updates in Oracle ZFS Storage Appliance Customer Service Manual, Release OS8.8.x. To understand the required user role authorizations, see Removing a Snapshot Schedule (CLI) in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Example Request:

DELETE /pools/p1/projects/default/filesystems/fs-01/snapshots/initial-backup?confirm=true

Example result if ?confirm=true is not added:

If ?confirm=true is not added when an NDMP hold exists on the snapshot, then the command will fail with the following output (lines are artificially broken for readability):

HTTP/1.1 409 Conflict

{"fault": {"message": "request requires confirm=true to complete (confirmation
needed for scripted command (scripted commands must be prefixed with \"confirm\"
to automatically confirm or \"deny\" to automatically deny) (encountered while
attempting to run command \"confirm destroy snap\"))", "code": 409, "name": 
"ERR_CONFIRM_REQUIRED"}}

List Snapshot Dependents

Lists dependents for a filesystem or volume. The following URI parameters are used:

• pool - System storage pool name
• project - Project name
• filesystem - Filesystem name
• lun - LUN name
• snapshot - Snapshot name

List filesystem dependents:

GET /api/storage/v1/pools/pool/projects/project/filesystems/filesystem/snapshots/snapshot/dependents

List volume dependents:

GET /api/storage/v1/pools/pool/projects/project/lun/lun/snapshots/snapshot/dependents

Example Request:

GET /api/storage/v1/pools/p1/projects/default/filesystems/fs01/snapshots/snap01/dependents
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Storage-Api: 1.0
Content-Type: application/json; charset=utf-8
X-Zfssa-Api-Version: 1.0

{
    "dependents": [
        {
            "project": "rest",
            "href": "/api/storage/v1/pools/p1/projects/rest/filesystems/snap01clone01",
            "share": "snap01clone01"
        },
        {
            "project": "rest",
            "href": "/api/storage/v1/pools/p1/projects/rest/filesystems/snap01clone02",
            "share": "snap01clone02"
        },
        {
            "project": "rest",
            "href": "/api/storage/v1/pools/p1/projects/rest/filesystems/snap01clone03",
            "share": "snap01clone03"
        }
    ]
}