1. Oracle ZFS Storage Appliance RESTful API Guide, Release OS8.8.x
  2. RESTful API Storage Service

13 RESTful API Storage Service

The RESTful API Storage service is used to view configuration and manage aspects of storage pools, projects, filesystems and LUNs. It also manages snapshots and replication.

Storage Pool Operations

For Oracle ZFS Storage Appliance, NAS is configured in pools that characterize the same data redundancy characteristics across all LUNs and filesystems, and pool operations are used to obtain the appliance storage configuration.

Table 13-1 Storage Pool Commands

Request Append to Path /api/storage/v{1|2} Description

GET

/pools

List all storage pools

GET

/pools/pool

Get storage pool details

POST

/pools

Configure a new storage pool

PUT

/pools/pool

Add or remove storage from a pool

PUT

/pools/pool/edit

Set pool properties

GET

/import

List properties for all storage pools available for importing

POST

/import/pool?props=true

List properties for specified storage pool for importing

POST

/import/pool

Import a storage pool with a unique name

POST

/import/guid

Import a storage pool without a unique name

POST

/import/new-pool-name guid

Import a storage pool and rename it

PUT

/pools/pool/scrub

Start a data scrub on the specified pool

DELETE

/pools/pool/scrub

Stop any data scrub job on the specified pool

GET

/pools/pool/LBPthreshold

List the logical block provisioning (LBP) threshold limit for the specified pool

PUT

/pools/pool/LBPthreshold

Set the LBP threshold limit for the specified pool

DELETE

/pools/pool

Unconfigure the specified storage pool

List Pools

This command lists the properties of all storage pools on the Oracle ZFS Storage Appliance system. HTTP status 200 (OK) is returned for a successful command. The HTTP body contains a list of JSON objects describing each pool. The names of the properties are shown in the following table.

Note:

The depth query parameter and the match_property-name=value query parameter are not supported.

Table 13-2 Storage Pool Properties

Property Type Description

asn

string

Serial number of the Oracle ZFS Storage Appliance system that owns the pool

name

string

The target pool name

owner

string

Hostname of the system that owns the pool

peer

string

In a clustered system, the partner head of the appliance cluster

profile

string

Data device profile

scrub_schedule

string

Number of days between scheduled pool scrubbing operations, or disable scheduled pool scrubbing. See Pool Scrub for allowed values and more pool scrubbing properties.

state

string

Pool state: online, offline, exported

Example Request:

GET /api/storage/v1/pools HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

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

{
    "pools": [{
        "profile": "mirror3",
        "name": "m1",
        "peer": "peer-hostname",
        "state": "online",
        "owner": "system-hostname",
        "asn": "appliance-serial-number",
        "scrub_schedule": "30 days"
    }, {
        "profile": "raidz1",
        "name": "r1",
        "peer": "peer-hostname",
        "state": "online",
        "owner": "system-hostname",
        "asn": "appliance-serial-number",
        "scrub_schedule": "30 days"
    }]
}

Get Pool

This command returns the properties from a single storage pool, along with storage usage information for the pool. HTTP status 200 (OK) is returned for a successful command.

Example Request:

GET /api/storage/v1/pools/p1 HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

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

{
    "pool": {
        "profile": "raidz1",
        "name": "p1",
        "usage": {
            "available": 57454799311352.0,
            "compression": 1.0,
            "dedupratio": 672791,
            "free": 57454799311352.0,
            "total": 74732430950400.0,
            "usage_child_reservation": 0.0,
            "usage_data": 16011663438848.0,
            "usage_metasize": 0.0,
            "usage_metaused": 0.0,
            "usage_replication": 1693675705344.0,
            "usage_reservation": 0.0,
            "usage_snapshots": 123913627136.0,
            "usage_total": 17829252771328.0,
            "used": 17829252771328.0
        },
        "peer": "00000000-0000-0000-0000-000000000000",
        "state": "online",
        "owner": "admin1",
        "guid": "e32b4cf1a6910baa",
        "asn": "2f4aeeb3-b670-ee53-e0a7-d8e0ae410749"
    }
}

Configure Pool

Configures a pool. For the parameters needed to create a pool, see the CLI configuration storage command. A dry run request to create a pool can be done that returns the available property names and values. This is done by setting the props query parameter properties to true.

Example Request:

POST /api/storage/v1/pools?props=true HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Content-Type: application/json
Accept: application/json

{
    "name": "p1"
}

Example Result:

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

"props": [{
        "choices": ["custom" ],
        "label": "Chassis 0",
        "name": "0",
        "type": "ChooseOne"
    }, {
        "choices": ["custom"],
        "label": "Chassis 1",
        "name": "1",
        "type": "ChooseOne"
    }, {
        "choices": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
        "label": "Chassis 1 data",
        "name": "1-data",
        "type": "ChooseOne"
    }, {
        "choices": ["mirror", "mirror3", "raidz1",
            "raidz2", "raidz3_max", "stripe"],
        "label": "Data Profile",
        "name": "profile",
        "type": "ChooseOne"
    }]
}

Example Request (to create a pool that uses 8 disks from chassis [1]):

POST /api/storage/v1/pools HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Content-Type: application/json
Accept: application/json

{
    "name": "p1",
    "profile": "stripe",
    "1-data": 8
}

Example Result:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "pool": {
        "asn": "314d252e-c42b-e844-dab1-a3bca680b563",
        "errors": [],
        "name": "p1",
        "owner": "zfs-storage",
        "peer": "00000000-0000-0000-0000-000000000000",
        "profile": "stripe",
        "status": "online",
        "usage": {
            "available": 1194000466944.0,
            "dedupratio": 100,
            "total": 1194000908288.0,
            "used": 441344.0
        }
    }
}

Add Storage to a Pool

This command is similar to create or configure a pool. Add storage adds additional storage devices to an existing pool. Send href pool/add with the body containing the desired number of storage devices to add to the pool.

Example Request:

PUT /api/storage/v1/pools/p1/add HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Content-Type: application/json
Accept: application/json

{
    "2-data": 8
}

Example Result:

HTTP/1.1 202 Accepted

Remove Storage from a Pool

This command is similar to add storage to a pool. Remove storage removes cache and log storage devices from an existing pool. Send href pool/remove with the body containing the desired type, chassis number, and number of storage devices to remove from the pool.

Example Request:

PUT /api/storage/v1/pools/p1/remove HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Content-Type: application/json
Accept: application/json

{
    "0-cache" : 2
}

Example Result:

HTTP/1.1 202 Accepted

To display the number of devices that can be removed, set the props query parameter to true.

Example Request:

PUT /api/storage/v1/pools/p1/remove?props=true HTTP/1.1
Host: zfs-storage.example.com
Authorization: Basic Tm8gcGVla2luZyE=
Content-Type: application/json
Accept: application/json

Example Result:

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

{
      "props": [
          {
              "choices": [
                  "0",
                  "1",
                  "2"
              ],
              "type": "ChooseOne",
              "name": "0-cache",
              "label": "Chassis 0 cache"
          },
          {
              "choices": [
                  "0",
                  "1",
                  "2"
              ],
              "type": "ChooseOne",
              "name": "1-log",
              "label": "Chassis 1 log"
          }
      ]
}

Set Pool Properties

This command accesses the route to a specific storage pool so properties can be set. Select the pool to be modified and edit its properties. For CLI properties for unencrypted storage pools, see Configuring Storage in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x. For encrypted pool CLI properties, see Creating an Encrypted Pool (CLI) in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Example Request:

PUT /api/storage/v2/pools/p0/edit HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Content-Type: application/json
Accept: application/json

{
         "keystore": "LOCAL",
          "keyname": "MyKey",
   "scrub_schedule": "45 days"
}

Example Result:

HTTP/1.1 202 Accepted

Import Pool

This command imports a single storage pool. HTTP status 200 (OK) is returned for a successful command. Error code 400 is returned for an invalid argument or if an import operation is already in progress.

To view the available pools and their properties, use the following commands:

  • View All Pools' Properties: Use either the GET import command or use the POST import command with the props query parameter set to true. The properties include the GUID.

  • View an Individual Pool's Properties: Use the POST import command, specify the pool's name at the end of the route, and set the props parameter to true.

Set the appropriate arguments when importing a storage pool:

  • Unique Pool Name: Specify the pool's name.

  • Pool Name Not Unique: Specify the pool's GUID; the pool's name is not necessary.

  • Pool Name Change: Specify both the new pool name and the old GUID. The new name must be 1 to 64 characters in length. The name cannot begin with a period (.) and cannot include spaces. Allowable characters are alphanumeric characters and special characters _ - . :

Example Request to List Properties for All Pools:

GET /api/storage/v2/import HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

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

{
    "pools": [
      {
        "guid": "599033b292ea0da1",
        "name": "p1",
        "state": "online",
        "profile": "raidz1",
        "disks": {
          "data": 4,
          "spare": 0,
          "log": 0,
          "cache": 0,
          "meta": 0
      }
    },
    {
        "guid": "600144c303fb1eb2",
        "name": "p2",
        "state": "online",
        "profile": "raidz1",
        "disks": {
          "data": 2,
          "spare": 0,
          "log": 0,
          "cache": 0,
          "meta": 0
      }
    }
  ]
}

Example Request to Import a Pool with a Unique Pool Name:

POST /api/storage/v2/import HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json

{
    "name": "p1"
}

Example Result:

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

{
    "pool": {
        "name": "p1",
        "state": "online",
        "asn": "0433018a-6810-44ec-b740-8d49fff31118",
        "owner": "owner-name",
        "peer": "peer-hostname",
        "profile": "raidz1",
        "errors": [],
        "encryption": "off",
        "guid": "599033b292ea0da1",
        ...
    }
}

Example Request to Import a Pool without a Unique Pool Name:

POST /api/storage/v2/import HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json

{
    "guid": "711255d414gc2fc3"
}

Example Result:

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

{
    "pool": {
        "name": "p1",
        "state": "online",
        "asn": "0433018a-6810-44ec-b740-8d49fff31118",
        "owner": "owner-name",
        "peer": "peer-hostname",
        "profile": "raidz1",
        "errors": [],
        "encryption": "off",
        "guid": "711255d414gc2fc3",
        ...
    }
}

Example Request to Import a Pool and Rename It:

POST /api/storage/v2/import HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json

{
    "name": "p3",
    "guid": 599033b292ea0da1"
}

Example Result:

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

{
    "pool": {
        "name": "p3",
        "state": "online",
        "asn": "0433018a-6810-44ec-b740-8d49fff31118",
        "owner": "owner-name",
        "peer": "peer-hostname",
        "profile": "raidz1",
        "errors": [],
        "encryption": "off",
        "guid": "599033b292ea0da1",
        ...
    }
}

Pool Scrub

Sending a pool/scrub PUT request starts a pool scrub operation. Sending a pool/scrub DELETE request stops a running scrub operation. For more information about pool scrubbing, see Scrubbing a Storage Pool – Manual (CLI) in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

By default, scheduled storage pool scrubbing is enabled and set to every 30 days. The scrub_schedule property specifies the number of days between scheduled pool scrubbing operations, or disables scheduled pool scrubbing. The default value of scrub_schedule is 30.

  • To disable scheduled scrubbing, for example if you prefer to perform manual scrubbing, set the value of the scrub_schedule property to off.

  • To change the number of days between scheduled scrubbing operations, set the value of the scrub_schedule property to 15, 30, 45, 60, 75, or 90.

For more information about scheduled pool scrubbing, see Scrubbing a Storage Pool – Scheduled (CLI) in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

The scrub object reports on the most recent pool scrub, either scheduled or manual.

  • If the complete property is false, then the scrub is still running. The number of errors found (errors) and number of errors repaired (repaired) are shown.

  • If the complete property is true, then the scrub has finished. Additional information shown includes the time the scrub started (op_start) and the time the scrub ended (last_end). Times are in GMT.

Note that scrub_started and scrub_finished are events of the zfs_pool alert action event category, and you could specify a custom action for those events. See RESTful API Alert Service.

The following example shows a partial pool list after a scrub.

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

{
    "pool": {
        "status": "online",
        "profile": "mirror:log_stripe:cache_stripe",
        "scrub": {
            "errors": 0,
            "op_start": "20190520T16:09:41",
            "complete": true,
            "seq_resilver": 0,
            "type": "everything",
            "examined": 403968,
            "repaired": 0,
            "last_end": "20190520T16:17:59"
        },
        "scrub_schedule": "30 days",
        "name": "p0",
        "peer": "peer-hostname",
        "owner": "system-hostname",
        "asn": "appliance-serial-number"
    }
}

List LBP Threshold

This command lists the logical block provisioning (LBP) threshold limit setting for thin provisioned LUNs within the specified storage pool on the Oracle ZFS Storage Appliance system. When the limit is set to the default value of 0, the LBP threshold is disabled.

Example Request:

GET /api/storage/v1/pools/p1/LBPthreshold HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

{
    "LBPthreshold": {
        "href": "/api/storage/v1/pools/p1/LBPthreshold",
        "limit": 100
    }
}

Set LBP Threshold

This command sets the logical block provisioning (LBP) threshold limit for thin provisioned LUNs within the specified storage pool on the Oracle ZFS Storage Appliance system.

To set the threshold parameter, specify the average storage consumption rate, which must be in the range of 1 to 100. When set to the default value of 0, the LBP threshold is disabled.

When the threshold value is exceeded, an error message is returned, and you can manage the space accordingly.

Example Error Message:

{  "fault": {
    "code": 413,
    "name": "ERR_OVER_LIMIT",
    "message": "input request too large to handle (threshold value out of range)"
  }
}

Example Request:

PUT /api/storage/v1/pools/p1/LBPthreshold?threshold=99 HTTP/1.1
Host: zfs-storage.example.com
Content-Type: application/json
Accept: application/json

Example Result:

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

{
    "LBPthreshold": {
        "href": "/api/storage/v1/pools/p1/LBPthreshold",
        "limit": 99
    }
}

Unconfigure Pool

This command removes a pool from the Oracle ZFS Storage Appliance system.

Request to Delete a Pool:

DELETE /api/storage/v1/pools/p1 HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=

Example Result:

HTTP/1.0 204 No Content
Date: Fri, 02 Aug 2013 22:31:06 GMT
X-Zfssa-Nas-Api: 1.0
Content-Length: 0