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
|
Lists available snapshots on an appliance. Depending on the request URI, the list contains project, filesystem, or LUN snapshots.
|
Example Request:
GET /api/storage/v1/pools/p1/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"
}]
}
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 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"
}
}
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/p1/projects/default/snapshots
Content-Type: application/json
{"name": "initial-backup"}
Example Response:
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"
}
}
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/p1/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/p1/projects/default/snapshot/initial-backup
Makes a new filesystem or LUN from an existing snapshot.
The following URI parameters are used:
Source pool name
Source project name
Source share name for filesystem snapshot
Source share name for LUN 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.
|
Example Request:
PUT /api/storage/v1/pools/p1/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/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"
}
}
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 following URI parameters are used:
Source pool name
Source project name
Source filesystem name for filesystem snapshot
Source LUN name for LUN 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 Response:
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"
}
}
The DELETE snapshot command deletes a project, filesystem, or LUN snapshot from the system.
The following URI parameters are used:
Source pool name
Source project name
Source filesystem name
LUN name
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/projectsnapshot
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.0.
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"}}
Lists dependents for a filesystem or volume. The following URI parameters are used:
System storage pool name
Project name
Filesystem name
LUN name
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 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/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"
}
]
}