Object Store Operations
Object store operations list and manage object store shares. All commands are scoped to a given storage pool or project.
service_uri/pools/pool/project/project
Table 13-9 Object Store Commands
| Request | Append to Path /api/storage/v{1|2} | Description |
|---|---|---|
|
GET |
/objectstores |
List all object stores |
|
GET |
/pools/pool/projects/project/objectstores |
List specified object stores |
|
GET |
/pools/pool/projects/project/objectstores?snaps=true |
List all object stores, including snapshots |
|
GET |
/pools/pool/projects/project/objectstores/objectstore |
Get object store details |
|
POST |
/pools/pool/projects/project/objectstores |
Create an object store |
|
PUT |
/pools/pool/projects/project/objectstores/objectstore |
Modify an object store |
|
PUT |
/pools/pool/projects/project/objectstores/objectstore |
Move an object store from one project to another |
|
DELETE |
/pools/pool/projects/project/objectstores/objectstore |
Destroy an object store |
|
GET |
/pools/pool/projects/project/objectstores/objectstore/usage/groups |
Get object store group usage |
|
GET |
/pools/pool/projects/project/objectstores/objectstore/usage/groups/group |
Get object store group usage for the specified group |
|
POST |
/pools/pool/projects/project/objectstores/objectstore/usage/groups |
Create an object store group quota |
|
PUT |
/pools/pool/projects/project/objectstores/objectstore/usage/groups/name |
Modify an object store group quota |
|
GET |
/pools/pool/projects/project/objectstores/objectstore/usage/users |
Get object store usage for the specified user |
|
GET |
/pools/pool/projects/project/objectstores/objectstore/usage/users/user |
Get object store user usage |
|
POST |
/pools/pool/projects/project/objectstores/objectstore/usage/users |
Create an object store user quota |
|
PUT |
/pools/pool/projects/project/objectstores/objectstore/usage/name |
Modify an object store user quota |
Each object store contains properties from the project and has the following objectstore-specific properties.
Table 13-10 Object Store Properties
| Property | Type | Description |
|---|---|---|
|
|
integer |
Bucket count of the object store. |
|
|
string |
Case sensitivity setting: |
|
|
string |
The group name. |
|
|
string |
Normalization setting. |
|
|
string |
The object store root directory permissions. |
|
|
string |
The project name. |
|
|
boolean |
Flag to include snapshots in the quota. |
|
|
boolean |
Flag to include snapshots in the reservation. |
|
|
string |
Mode for the Swift protocol. |
|
|
string |
Mode for the OCI protocol. |
|
|
string |
Mode for the S3 protocol. |
|
|
object |
Project inheritance properties. |
|
|
object |
File system usage information. |
|
|
string |
The user name that owns the share. |
|
|
boolean |
Flag to reject non-UTF-8. |
List Object Stores
The list object stores command shows all object stores in a given pool or project.
Note:
Thedepth query parameter and the match_property-name=value
query parameter are not supported.
Request parameters: filter – A simple string match filter that requires a property within the project to contain the same filter string within its value.
The list object stores command uses the following URI parameters:
- pool - Storage pool name
- project - Project name
Example request:
GET /api/storage/v1/pools/p1/projects/proj-01/objectstores HTTP/1.1 Host: zfs-storage.example.com:215 Accept: application/json
Successful request returns HTTP status 200 (OK) along with an array of object store properties in JSON format.
Example Result:
HTTP/1.1 200 OK
Content-Type: application/json
{
"objectstores": [{
"name": "objectstore-01",
"project": "proj-01",
"pool": "p1",
...
}, {
"name": "objectstore-02",
"project": "proj-01",
"pool": "p1",
...
}]
}
A list of all object stores across all pools and projects is also supported. In that case, the URI would be /api/storage/v{1|2}/objectstores.
Example Request to get all object stores with the "abcd" string as part of its properties:
GET /api/storage/v1/objectstores?filter=abcd HTTP/1.1 Host: zfs-storage.example.com:215 Accept: application/json
Get Object Store
The get object store command returns the properties of a single object store in a given pool or project.
The get object stores command uses the following URI parameters:
- pool - Storage pool name
- project - Project name
- objectstore - Object store name
Example request to list object store named os-1:
GET /api/storage/v1/pools/p1/projects/proj-1/objectstores/os-1 HTTP/1.1 Host: zfs-storage.example.com:215 Accept: application/json
Successful get request returns HTTP status 200 (OK) along with the object store properties in JSON format.
Example Result:
HTTP/1.1 200 OK
Content-Type: application/json
{
"objectstore": {
"aclinherit": "restricted",
"aclmode": "discard",
"atime": true,
"canonical_name": "p1/local/proj-1/os-1",
"checksum": "fletcher4",
"compression": "off",
"copies": 1,
"creation": "20260127T18:16:53",
"dedup": false,
"effectivereadlimit": -1,
"effectivewritelimit": -1,
"encryption": "off",
"exported": true,
"keychangedate": "",
"rekeydate": "",
"keystatus": "none",
"id": "850b65d3-c6b4-d2e7-0000-000000000000",
"logbias": "latency",
"maxblocksize": 1048576,
"mountpoint": "/export/os-1",
"nodestroy": false,
"pool": "p1",
"quota": 0,
"readlimit": -1,
"readonly": false,
"recordsize": 131072,
"reservation": 0,
"rstchown": true,
"secondarycache": "all",
"snapdir": "hidden",
"snaplabel": "",
"snapret_enabled": false,
"vscan": false,
"writelimit": -1,
"space_available": 590698149888,
"space_data": 64512,
"space_unused_res": 0,
"space_snapshots": 0,
"space_total": 64512,
"space_unused_res_shares": 0,
"compressratio": 100.0,
"source": {
"aclinherit": "inherited",
"aclmode": "inherited",
"atime": "inherited",
"checksum": "inherited",
"compression": "inherited",
"copies": "inherited",
"dedup": "inherited",
"exported": "inherited",
"keychangedate": "inherited",
"rekeydate": "inherited",
"logbias": "inherited",
"maxblocksize": "inherited",
"mountpoint": "inherited",
"nbmand": "inherited",
"readonly": "inherited",
"recordsize": "inherited",
"reservation": "inherited",
"rstchown": "inherited",
"secondarycache": "inherited",
"sharedav": "local",
"shareftp": "local",
"sharenfs": "local",
"shareobjectstore": "local",
"shares3": "local",
"shareoci": "local",
"sharesftp": "local",
"sharesmb": "local",
"sharetftp": "local",
"snapdir": "inherited",
"snapret_enabled": "inherited",
"vscan": "inherited"
},
"casesensitivity": "sensitive",
"normalization": "none",
"root_group": "other",
"name": "s3share",
"root_permissions": "777",
"project": "default",
"quota_snap": true,
"reservation_snap": true,
"root_user": "nobody",
"utf8only": true,
"unicode": "5.0.0",
"bucketcount": 1,
"root_acl": [
"owner@:rwxpDaARWcCo:allow",
"group@:rwxpDaARWc:allow",
"everyone@:rwxpDaARWc:allow"
],
"shareoci": "rw",
"href":
"/api/storage/v1/pools/p1/projects/proj-1/objectstores/os-1"
}
}A list of all object stores across all pools and projects is also supported. In that case, the URI would be /api/storage/v{1|2}/objectstores.
Example Request to get all object stores with the "abcd" string as part of its properties:
GET /api/storage/v1/objectstores?filter=abcd HTTP/1.1 Host: zfs-storage.example.com:215 Accept: application/json
Create an Object Store
The create object store command creates an object store with a given name residing in the given storage pool or project. The new object store with default properties is returned.
The following URI parameters are used:
-
pool- Storage pool name -
project- Project name -
objectstore- Object store name
Request Parameters:
-
name– The object store name must be supplied to create a new object store. -
protocol- The desired protocol must be supplied to create a new object store. -
mode- The desired protocol mode must be supplied to create a new object store. -
Object store properties – Any of the properties listed in object store properties or project properties can be set as initial values.
Example Request (to create an object store named objectstore-01 and owned by the user admin1):
POST /api/storage/v1/pools/p1/projects/proj-01/objectstores
HTTP/1.1
Host: zfs-storage.example.com:215
Content-Type: application/json
Accept: application/json
{
"name": "objectstore-01",
"root_user": "admin1",
"protocol": "oci",
"mode": "rw"
}
Successful creation returns HTTP status 201 (Created) with the Location header containing the URI of the new object store. The body contains all object store properties in JSON format.
Example Result:
HTTP/1.1 201 Created
Content-Type: application/json
Location:
http://zfs-storage.example.com:215/api/storage/v1/pools/p1/projects/proj-01/objectstores/objectstore-01
{
"objectstore": {
"name": "objectstore-01",
"pool": "p1",
"collection": "local",
"project": "proj-01",
"root_user": "admin1",
"shareoci": "rw",
"bucketcount": 0,
...
}
}Modify Object Store
The modify object store command changes the attributes of an existing object store. Successful response returns HTTP status 202 (Accepted) and lists all object store properties.
The following URI parameters are used:
- pool - Storage pool name
- project - Project name
- objectstore - Object store name
Request parameters: object store properties – any of the object store or project properties can be modified.
Example Request (to change an object store name from objectstore-01 to new-name and change the owner to nobody):
PUT
/api/storage/v1/pools/p1/projects/proj-01/objectstores/objectstore-01 HTTP/1.1
Host: zfs-storage.example.com:215
Content-Type: application/json
Accept: application/json
{
"name": "new-name",
"root_user": "nobody"
}Example Result:
HTTP/1.1 202 Accepted
Content-Type: application/json
Location:
http://zfs-storage.example.com:215/pools/p1/projects/proj-01/objectstores/objectstore-01
{
"objectstore": {
"name": "new-name",
"pool": "p1",
"collection": "local",
"project": "proj-01",
"root_user": "nobody"
...
}
}Move Object Store
You can use REST to move an object store share from one project to another project.
Note:
You cannot move an unencrypted filesystem to an encrypted project.The following example request moves the os1 object store from the proj1 project to the new-proj project:
PUT /api/storage/v2/pools/p0/projects/proj1/objectstores/os1
HTTP/1.1
Host: zfs-storage.example.com:212
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 object store:
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"os1": {
...
"href":
"/api/storage/v2/pools/p0/projects/new-proj/objectstores/os1",
...
}Delete Object Store
The delete object store command removes a single object store in a given pool or project.
The following URI parameters are used:
- pool - Storage pool name
- project - Project name
- objectstore - Object store 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 /api/storage/v1/pools/p1/projects/proj-01/objectstores/objectsto re-01 HTTP/1.1 Host: zfs-storage.example.com:215 Accept: application/json
Successful delete returns HTTP status 204 (No Content).
Example Result:
HTTP/1.1 204 No-Content