Oracle^® ZFS Storage Appliance RESTful API Guide, Release OS8.7.x

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/v1/pools/{pool}/projects/{project}

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

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

Table 84  Snapshot and Clone Commands

Request Path /api/storage/v1 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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/<pooll>/projects /<project>/luns/<lun>/automatic /<automatic> Modify the specified LUN automatic snapshot object PUT /pools/<pooll>/projects /<project>/luns/<lun>/automatic /<automatic>?convert=true Modify 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. 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.

List Snapshots

Lists available snapshots on an appliance. Depending on the request URI, the list contains project, filesystem, or LUN snapshots.

Table 85  List Snapshot Command Forms

Command /api/storage/v1/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/gold/projects/default/snapshots
Accept: application/json

Example Response:

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

{
    "snapshots": [{
        "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
        "display_name": "snap-001",
        “display_description": "Daily backup",
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "status": "available",
        "size": 30,
        "created_at": "2012-02-29T03:50:07Z"
    }, {
        "id": "e479997c-650b-40a4-9dfe-77655818b0d2",
        "display_name": "snap-002",
        "display_description": "Weekly backup",
        "volume_id": "76b8950a-8594-4e5b-8dce-0dfa9c696358",
        "status": "available",
        "size": 25,
        "created_at": "2012-03-19T01:52:47Z"
    }]
}

Get Snapshot

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

Example Request:

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

Example Response:

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

{
    "snapshot": {
        "id": "3fbbcccf-d058-4502-8844-6feeffdf4cb5",
        "display_name": "snap-001",
        "display_description": "Daily backup",
        "volume_id": "521752a6-acf6-4b2d-bc7a-119f9148cd8c",
        "status": "available",
        "size": 30,
        "created_at": "2012-02-29T03:50:07Z"
    }
}

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

Example Request:

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

{"name": "initial-backup"}

Example Response:

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

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

Rename Snapshot

Renames an existing snapshot.

• Request URI - Snapshot, the current snapshot name

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

Example Request:

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

{“name”:”old-snapshot”}

Example Response:

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

Clone Snapshot

Makes a new filesystem or LUN from an existing snapshot.

Request URI Clone Filesystem:

PUT /pools/{pool}/projects/{project}/filesystems/{share}/snapshots/{snap}/clone

Clone Volume:

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

Table 86  URI Parameters

Parameter Description 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

Request body contains a JSON object with the following properties.

Table 87  Clone Snapshot Properties

Type Name Description string pool Destination clone pool name string project Destination clone project name string lun Destination LUN name (for LUN snapshot)

Example Request:

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

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

Example Response:

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

{
    "filesystem": {
        "origin": {
            "project": "default",
            "share": "fs01",
            "snapshot": "snap01",
            "pool": "gold",
            "collection": "local"
        },
        "href": "/api/storage/v1/pools/gold/projects/rest/filesystems/snap01clone01",
        "mountpoint": "/export/snap01clone01",
        "compression": "gzip-9",
        "source": {
            "compression": "local",
            ...
        },
        ...
       "canonical_name": "gold/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.

Rollback a filesystem snapshot:

PUT /pools/{pool}/projects/{project}/filesystems/{share}/snapshots/{snap}/rollback

Rollback a LUN Snapshot:

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

Table 88  URI Parameters

Parameter Description 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

Example Request:

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

Example Response:

HTTP/1.1 202 Accepted
Location: /pools/gold/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": "gold/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": "gold"
    }
}

Delete a Snapshot

The DELETE snapshot command deletes a project, filesystem, or LUN snapshot from the system.

Table 89  Delete Snapshot Command Forms

Command DELETE /api/storage/v1/pools/{pool}/projects/{project} Delete a project snapshot with the given pool name, project name, and snapshot name /snapshots/{snapshot_name} Delete a filesystem snapshot with the given pool name, project name, filesystem name, and snapshot name /filesystems/{share_name}/snapshots/{snapshot_name} Delete a filesystem LUN with the given pool name, project name, filesystem name, and snapshot name /luns/ {lun_name}/snapshots/{snapshot_name}

Table 90  URI Parameters

Parameter Description pool Source pool name project Source project name filesystem Source filesystem name lun The LUN name snapshot Source snapshot name

If the snapshot has an NDMP hold on it, then ?confirm=true must be added 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.7.x.

Example

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

If ?confirm=true is not added when an NDMP hold exists on the snapshot, then the command will fail with the following output:

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.

Table 91  List Snapshot Dependents Command Forms

Command /api/storage/v1/pools/{pool}/projects/{project} List Filesystem Dependents /filesystems/{share}/snapshots/{snapshot}/dependents List Volume Dependents lun/{lun}/snapshots/{snapshot}/dependents

Table 92  URI Parameters

Parameter Description pool Name of system storage pool project The project name filesystem The filesystem name lun The LUN name

Example Request:

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

Example Response:

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/gold/projects/rest/filesystems/snap01clone01",
            "share": "snap01clone01"
        },
        {
            "project": "rest",
            "href": "/api/storage/v1/pools/gold/projects/rest/filesystems/snap01clone02",
            "share": "snap01clone02"
        },
        {
            "project": "rest",
            "href": "/api/storage/v1/pools/gold/projects/rest/filesystems/snap01clone03",
            "share": "snap01clone03"
        }
    ]
}