LUN Operations
All LUN or volume operations are scoped to a given pool or project. The following LUN commands are available.
Table 13-7 Volume Commands
Request | Append to Path /api/storage/v{1|2} | Description |
---|---|---|
GET |
/luns |
List all LUNs |
GET |
/pools/pool/projects/project/luns |
List LUNs |
GET |
/pools/pool/projects/project/luns?snaps=true |
List all LUNs, including snapshots |
GET |
/pools/pool/projects/project/luns/lun |
Get LUN details |
POST |
/pools/pool/projects/project/luns |
Create a LUN |
PUT |
/pools/pool/projects/project/luns/lun |
Modify a LUN |
DELETE |
/pools/pool/projects/project/luns/lun |
Destroy a LUN |
The following table lists the LUN properties. Volumes can also inherit or override project properties.
Table 13-8 Volume Properties
Property | Type | Description |
---|---|---|
|
number or list of numbers |
The assigned LU number. If presented to multiple initiator groups, the type is a list of numbers. If presented to multiple initiator groups, the ordering of |
|
boolean |
Flag to fix LU number at current value |
|
list of strings |
The initiator group. If the LUN is presented to multiple initiator groups, the ordering of |
|
string |
STMF GUID |
|
number or string |
The LU number. Either a number or |
|
string |
The project name (immutable) |
|
object |
Lists source of properties: |
|
boolean |
Flag to enable thin provisioning |
|
string |
Logical unit status: |
|
string |
The target group |
|
object |
Lists LUN usage statistics |
|
number |
Volume block size |
|
number |
Volume size |
|
boolean |
Flag to enable write cache |
Some properties can be inherited from the project. The source object lists each of these properties and identifies whether the property is local to the LUN or is inherited from the project. By default these properties are inherited by the project. Once set, they are local to the LUN. The source object is immutable. To change the source back to inherited, the properties can be unset.
Example JSON request to unset compression:
{"unset": ["compression"]}
List LUNs
The list LUNs command returns a list of LUNs available in a given pool or project.
Note:
Thedepth
query parameter and the match_property-name=value
query parameter are not supported.
The following URI parameters are used:
- pool - Storage pool name
- project - Project name
- filesystem - Filesystem name
Example request to list LUNs within project proj-01
:
GET /api/storage/v1/pools/p1/projects/proj-01/luns HTTP/1.1 Host: zfs-storage.example.com:215 Accept: application/json
Successful get
returns HTTP status 200 (OK) along with the LUN properties in JSON format.
Example Result:
HTTP/1.1 200 OK Content-Type: application/json { "luns": [{ "id": "fa4ac6fb-0bcc-d2e3-0000-000000000000", "name": "vol-01" ... }, { "id": "690ae407-7c4d-b5d2-0000-000000000000", "name": "vol-01", .... }] }
Get LUN
The get LUN command returns the properties of a single LUN in a given pool or project.
The following URI parameters are used:
- pool - Storage pool name
- project - Project name
- lun - LUN name
Example Request (to get a LUN named "vol-01"):
GET /api/storage/v1/pools/p1/projects/proj-01/lun/vol-01 HTTP/1.1 Host: zfs-storage.example.com:215 Accept: application/json
Successful get
returns HTTP status 200 (OK) along with the LUN properties in JSON format.
Example Result:
HTTP/1.1 200 OK Content-Type: application/json { "lun": { "logbias": "latency", "creation": "20130423T21:31:17", "nodestroy": false, "dedup": false, "rrsrc_actions": [], "id": "e3045406-319b-cf7a-0000-000000000000", "writecache": false, "compression": "off", "copies": 1, "stmfguid": "600144F0D8E0AE4100005176FDA60001", "source": { "compression": "default", "checksum": "inherited", "logbias": "default", "dedup": "default", "copies": "default", "exported": "inherited", "rrsrc_actions": "inherited", "secondarycache": "default" }, "canonical_name": "p1/local/default/disk1", "snaplabel": "", "usage": { "available": 881469214720.0, "loading": false, "snapshots": 0.0, "compressratio": 100.0, "total": 1073758208.0, "data": 1073758208.0 }, "secondarycache": "all", "collection": "local", "exported": true, "volsize": 1073741824.0, "pool": "p1", "volblocksize": 8192, "checksum": "fletcher4", "project": "default", "sparse": false } }
Create a New LUN
This command creates a new LUN. You must supply a size or a cloning source for the new LUN.
The following URI parameters are used:
- pool - Storage pool name
- project - Project name
Request Parameters:
name
– The LUN name must be supplied to create a new LUN.volsize
- Size of the new LUN (mandatory), either as an exact number of bytes, or using units, such as1M
.volsize
must be a multiple ofblocksize
and it must be at least 1M (1048576).- Volume properties – Any of the properties listed in LUN properties or project properties can be set as initial values.
Example Request:
POST /api/storage/v1/pools/p1/projects/proj-01/luns HTTP/1.1 Host: zfs-storage.example.com:215 Accept: application/json { name : "vol-001", // Volume name (required) volsize : "1M", // New Volume size (required) blocksize : 8192, // New Volume block size sparse : true, // New Volume sparse data flag initiatorgroup : 'default', // Initiator group name targetgroup : 'default', // Target group name lunumber : 'auto', // Volume LU number status : 'online', // Initial Status ('online', 'offline') fixednumber : false, "source": { "snapshot_id" : "76b8950a-8594-4e5b-8dce-0dfa9c696358", "snapshot": "/pool-001/local/proj-001/snap-001" } }
Successful creation returns HTTP status 201 (Created) with the Location header containing the URI of the new LUN. The body contains all of the LUN properties in JSON format.
Example Result:
HTTP/1.1 201 Created Content-Type: application/json Location: http://zfs-storage.example.com:215/pools/p1/projects/proj-01/luns/vol-001 { "lun": { "name": "vol-001", ... } }
Modify LUN
The modify LUN command changes the attributes of an existing LUN.
The following URI parameters are used:
- pool - Storage pool name
- project - Project name
- lun - LUN name
Request parameters: volume properties – Any of the LUN or project properties can be modified.
Example request to change a LUN name from vol-01
to new-name
:
POST /api/storage/v1/pools/p1/projects/proj-01/luns/vol-01 HTTP/1.1 Host: zfs-storage.example.com:215 Content-Type: application/json Accept: application/json { "name": "new-name" }
Successful response returns HTTP status 202 (Accepted) and lists all LUN properties.
Example Result:
HTTP/1.1 201 Created Content-Type: application/json Location: /api/storage/v1/pools/p1/projects/proj-01/luns/new-name { "lun": { "name": "new-name", "pool": "p1", "collection": "local", "project": "proj-01", ... } }
Delete LUN
The delete LUN command removes a single LUN in a given pool or project.
The following URI parameters are used:
- pool - Storage pool name
- project - Project name
- lun - LUN name
To monitor the amount of space to be reclaimed in the storage pool, enter the GET command for pools/pool. Note the amount of space for property async_destroy_reclaim_space. When the operation has completed, 0 (zero) is displayed.
Example Request:
DELETE /pools/p1/projects/proj-01/luns/lun-01 HTTP/1.1 Host: zfs-storage.example.com:215 Accept: application/json
Successful get
returns HTTP status 204 (No Content).
Example Result:
HTTP/1.1 204 No-Content