Project Operations

All project operations can be scoped to a given pool. Commands that operate across all projects append /projects to the URI, and commands that operate on a single project append /projects/project.

Table 13-3 Project Commands

Request	Append to Path /api/storage/v{1\|2}	Description
GET	/projects	List all projects
GET	/pools/pool/projects	List projects
GET	/pools/pool/projects?snaps=true	List all projects, including snapshots
GET	/pools/pool/projects/project	Get project details
POST	/pools/pool/projects	Create a project
PUT	/pools/pool/projects/project	Modify a project
DELETE	/pools/pool/projects/project	Destroy a project
GET	/pools/pool/projects/project/usage/groups	Get project group usage
GET	/pools/pool/projects/project/usage/groups/group	Get project usage for the specified group
GET	/pools/pool/projects/project/usage/users	Get project user usage
GET	/pools/pool/projects/project/usage/users/user	Get project usage for the specified user

The following table shows the list of editable properties within a project resource.

Table 13-4 Project Properties

Property	Type	Description
`aclinherit`	string	ACL inheritance behavior ("discard", "noallow", "restricted", "passthrough", "passthrough-x", "passthrough-mode-preserve")
`aclmode`	string	ACL behavior on mode change ("discard", "mask", "passthrough")
`atime`	boolean	Update access time on read flag
`canonical_name`	string	Canonical name
`checksum`	string	Block checksum ("fletcher2", "fletcher4", "sha256")
`compression`	string	Data compression setting ("off", "lzjb", "gzip-2", "gzip", "gzip-9")
`copies`	number	Number of additional replication copies
`creation`	datetime	Date and time of project (or LUN, filesystem) creation
`dedup`	boolean	Data deduplication flag
`default_group`	string	Project default filesystem group: "other"
`default_permissions`	string	Project default filesystem permissions "700"
`default_sparse`	boolean	Project default LUN sparse data flag
`default_user`	string	Project default filesystem user: "nobody"
`default_volblocksize`	number	Project default LUN blocksize: 8192
`default_volsize`	number	Project default LUN Size
`exported`	boolean	Exported flag
`logbias`	string	Synchronous write bias ("latency", "throughput")
`mountpoint`	string	Share mountpoint default "/export/proj-01"
`name`	string	Project name
`nbmand`	boolean	Non-blocking mandatory locking flag
`nodestroy`	boolean	Prevent destruction flag
`quota`	number	Project quota size in bytes
`origin`	string	Clone origin
`pool`	string	Pool names
`readonly`	boolean	Data is read only if set to true
`recordsize`	string	Database record size "128k"
`reservation`	number	Data reservation size
`retention_policy`	string	File retention: File retention policy ("disabled", "mandatory", "privileged")
`retention_policy_changeacl`	boolean	File retention: Determines if a retained file's ACL/permissions can be changed ("off", "on")
`retention_policy_onexpiry`	string	File retention: Determines behavior when file retention expires ("off", "delete", "hold")
`retention_period_deletegrace`	number	File retention: Number of seconds/hours/days/years that automatic file deletion is delayed when `retention_policy_onexpiry` is set to "delete." Default value: 0 days.
`retention_period_default`	number	File retention: Default amount of time for which a file is retained if it is automatically retained, or retained manually without first changing the file's access time attribute. Must be set if `retention_policy` is not "disabled."
`retention_period_min`	number	File retention: Minimum amount of time for file retention. Must be set if `retention_policy` is not "disabled."
`retention_period_max`	number	File retention: Maximum amount of time for file retention. Must be set if `retention_policy` is not "disabled."
`retention_period_grace`	number	File retention: Amount of time a file must remain unmodified before it is automatically retained at the default file retention period value
`retention_status_expiry`	string	File retention: Expiration date and time for a file
`retention_status_files`	string	File retention: File status for expiration date, time, and if expired
`rstchown`	boolean	Restrict ownership change flag
`secondarycache`	string	Secondary cache usage ("all", "metadata", "none")
`sharedav`	string	HTTP share ("off", "rw", "ro")
`shareftp`	string	FTP share ("off", "rw", "ro")
`sharenfs`	string	NFS share ("off", "on", "ro", "rw")
`sharesftp`	string	SFTP share ("off", "rw", "ro")
`sharesmb`	string	SMB/CIFS share ("off", "rw", "ro")
`sharetftp`	string	TFTP share ("off", "rw", "ro")
`snapdir`	string	.zfs/snapshot visibility ("hidden", "visible")
`snaplabel`	string	Scheduled snapshot label
`vscan`	boolean	Virus scan flag

List Projects

This command lists all of the projects in a given pool. The request takes a single URI parameter, which is the storage pool name. Each returned project contains the list of modifiable properties listed above as well as the pool name, creation time, loading state, replication actions, and data usage.

Note:

The depth 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.

Example Request:

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

On a successful get, an HTTP code 200 (OK) is returned along with an array of project properties in JSON format.

Example Result:

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

{
    "projects": [{
        "name": "proj-01",
        ...
    }, {
        "name": "proj-02",
        ...
    }
}

A list of all projects across all pools is also supported; the URI would contain only the /projects path.

Example Request to get all projects with backup as part of its properties:

GET /projects?filter=backup HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json

Get Project Properties

This command lists the properties for a single project in a given pool. A successful get returns HTTP Code 200 (OK) along with the project properties in JSON format.

Example Request to list the project named proj-01 in the zfs-storage-1 pool:

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

Example Result:

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

{
    "project": {
        "default_volblocksize": 8192.0,
        "logbias": "latency",
        "creation": "20130411T20:02:35",
        "nodestroy": false,
        "dedup": false,
        "sharenfs": "on",
        "sharesmb": "off",
        "default_permissions": "700",
        "mountpoint": "/export",
        "snaplabel": "",
        "id": "042919bb-0882-d903-0000-000000000000",
        "readonly": false,
        "rrsrc_actions": [],
        "compression": "off",
        "sharetftp": "",
        "default_sparse": false,
        "snapdir": "hidden",
        "aclmode": "discard",
        "copies": 1,
        "aclinherit": "restricted",
        "shareftp": "",
        "canonical_name": "zfs-storage-1/local/default",
        "recordsize": 131072.0,
        "usage": {
            "available": 1758424767306.0,
            "loading": false,
            "quota": 0.0,
            "snapshots": 0.0,
            "compressratio": 100.0,
            "child_reservation": 0.0,
            "reservation": 0.0,
            "total": 45960.0,
            "data": 45960.0
        },
        "default_volsize": 0.0,
        "secondarycache": "all",
        "collection": "local",
        "exported": true,
        "vscan": false,
        "reservation": 0.0,
        "atime": true,
        "pool": "p1",
        "default_user": "nobody",
        "name": "default",
        "checksum": "fletcher4",
        "default_group": "other",
        "sharesftp": "",
        "nbmand": false,
        "sharedav": "",
        "rstchown": true
    }
}

Create Project

The create project command creates a project with a given name residing in the given storage pool. The request takes a single URI parameter, which is the storage pool name. The new project with default properties is returned.

JSON body request parameters:

name – The project name must be supplied to create a project
Project properties – Any of the project properties can be set as the new project's initial values

Example request to create a project named proj-01:

POST /api/storage/v1/pools/p1/projects HTTP/1.1
Host: zfs-storage.example.com:215
Content-Type: application/json
Accept: application/json

{
    "name": "proj-01",
    "sharenfs": "ro"
}

Successful creation returns HTTP status 201 (Created) with the location header containing the URI of the new project. The body contains all of the project 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

{
    "project": {
        "name": "proj-01",
        "href": "/api/storage/v1/pools/p1/projects/proj-01",
        "mountpoint": "/export/acme/zfs-storage-1",
        ...
    }
}

Modify Project

The modify project command changes the attributes of an existing project. The following URI parameters are used:

pool - Storage pool name
project - Project name

Request parameters: project properties – Any of the project properties can be set as the new project's initial values.

Example request to change a project's name from proj-01 to new-name:

POST /api/storage/v1/pools/p1/projects/proj-01 HTTP/1.1
Host: zfs-storage.example.com:215
Content-Type: application/json
Accept: application/json

{
    "name": "new-name",
    "sharenfs": "rw",
    "compression": "gzip-9"
}

Successful response returns HTTP status 202 (Accepted) and lists all project properties.

Example Result:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/storage/v1/pools/p1/projects/new-name

{
    "project": {
        "name": "new-name",
        "sharenfs": "rw",
        "compression: "gzip-9",
         ...
    }
}

Delete Project

The delete project command removes a single project in a given pool. The following URI parameters are used:

pool - Storage pool name
project - Project name

To monitor the amount of space to be reclaimed in the storage pool if deferred update Asynchronous Dataset Deletion (OS8.7.0 or later) has been accepted, 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 HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json

Project Usage

Get requests project usage resources can be used to get usage data per user or per group for the project.