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
PUT	/pools/pool/projects/project/luns/lun	Move a LUN from one project to another
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
assignednumber	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 assignednumber and initiatorgroups are aligned. For example, the first item in the assignednumber list pertains to the first item in the initiatorgroups list.
fixednumber	boolean	Flag to fix LU number at current value
initiatorgroups	list of strings	The initiator group. If the LUN is presented to multiple initiator groups, the ordering of assignednumber and initiatorgroups are aligned. For example, the first item in the assignednumber list pertains to the first item in the initiatorgroups list.
lunguid	string	STMF GUID
lunumber	number or string	The LU number. Either a number or auto
project	string	The project name (immutable)
source	object	Lists source of properties: local or inherited
sparse	boolean	Flag to enable thin provisioning
status	string	Logical unit status: online or offline
targetgroup	string	The target group
usage	object	Lists LUN usage statistics
volblocksize	number	Volume block size
volsize	number	Volume size
writecache	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:

The depth 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 as 1M. volsize must be a multiple of blocksize 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",
        ...
    }
}

Move LUN

You can use REST to move a LUN share from one project to another project.

Note:

You cannot move an unencrypted LUN to an encrypted project.

The following example request moves the lun1 LUN from the proj1 project to the new-proj project:

PUT /api/storage/v2/pools/p0/projects/proj1/luns/lun1 HTTP/1.1
    Host: zfs-storage.example.com:206
    Content-Type: application/json
    Accept: application/json
    {
        "proj1": "new-proj",
    }

The example result shows a successful return code of 202 and the properties of the moved LUN:

HTTP/1.1 202 Accepted
    Content-Type: application/json
    {
        "fs1": {
            ...
            "href": "/api/storage/v2/pools/p0/projects/new-proj/luns/lun1",
            ...
    }

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