Filesystem Operations

Filesystem operations list and manage filesystem shares. All commands are scoped to a given storage pool or project.

service_uri/pools/pool/project/project

Table 13-5 Filesystem Commands

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

Each filesystem contains properties from the project and has the following filesystem-specific properties.

Table 13-6 Filesystem Properties

Property	Type	Description
`casesensitivity`	string	Case Sensitivity setting: `mixed`, `sensitive`, or `insensitive`
`group`	string	The group name
`normalization`	string	Normalization
`permissions`	string	The filesystem permissions
`project`	string	The project name
`quota_snap`	boolean	Flag to include snapshots in the quota
`reservation_snap`	boolean	Flag to include snapshots in the reservation
`retention_policy`	string	File retention: File retention policy: `disabled`, `privileged`, or `mandatory`
`retention_policy_changeacl`	boolean	File retention: Determines if a retained file's ACL/permissions can be changed: `off` or `on`
`retention_policy_onexpiry`	string	File retention: Determines behavior when file retention expires: `off`, `delete`, or `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
`shadow`	string	Data migration source
`errors`	string	Data migration errors
`sharesmb_name`	string	Name of SMB share
`source`	object	Project inheritance properties
`usage`	object	File system usage information
`user`	string	The user name that owns the share
`utf8only`	boolean	Flag to reject non-UTF-8

List Filesystems

The list filesystems command shows all filesystems in a given pool or project.

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.

The list filesystems command uses the following URI parameters:

pool - Storage pool name
project - Project name

Example Request:

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

Successful request returns HTTP status 200 (OK) along with an array of filesystem properties in JSON format.

Example Result:

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

{
    "filesystems": [{
        "name": "filesystem-01",
        "project": "proj-01",
        "pool": "p1",
        ...
    }, {
        "name": "filesystem-02",
        "project": "proj-01",
        "pool": "p1",
        ...
    }]
}

A list of all filesystems across all pools and projects is also supported. In that case, the URI would be /api/storage/v{1|2}/filesystems.

Example Request to get all filesystems with the "abcd" string as part of its properties:

GET /api/storage/v1/filesystems?filter=abcd HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json

Get Filesystem

The get filesystem command returns the properties of a single filesystem in a given pool or project. The following URI parameters are used:

pool - Storage pool name
project - Project name
filesystem - Filesystem name

Example request to list project named proj-01:

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

Successful get returns HTTP status 200 (OK) along with the filesystem properties in JSON format.

Example Result:

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

{
    "filesystem": {
        "logbias": "latency",
        "creation": "20130423T21:30:34",
        "nodestroy": false,
        "dedup": false,
        "sharenfs": "on",
        "sharesmb": "off",
        "mountpoint": "/export/mnt1",
        "snaplabel": "",
        "id": "424ca2ec-b3fa-df86-0000-000000000000",
        "readonly": false,
        "rrsrc_actions": [],
        "compression": "off",
        "sharetftp": "",
        "source": {
            "logbias": "default",
            "dedup": "default",
            "sharenfs": "inherited",
            "sharesmb": "off",
            "mountpoint": "inherited",
            "rrsrc_actions": "local",
            "compression": "default",
            "sharetftp": "inherited",
            "snapdir": "default",
            "aclmode": "default",
            "copies": "default",
            "aclinherit": "default",
            "shareftp": "inherited",
            "readonly": "default",
            "secondarycache": "default",
            "exported": "inherited",
            "vscan": "default",
            "reservation": "local",
            "atime": "default",
            "recordsize": "default",
            "checksum": "inherited",
            "sharesftp": "inherited",
            "nbmand": "default",
            "rstchown": "default"
        },
        "snapdir": "hidden",
        "aclmode": "discard",
        "copies": 1,
        "aclinherit": "restricted",
        "shareftp": "",
        "canonical_name": "p1/local/default/mnt1",
        "recordsize": 131072.0,
        "usage": {
            "available": 880395477504.0,
            "loading": false,
            "quota": 0.0,
            "snapshots": 18432.0,
            "compressratio": 100.0,
            "reservation": 0.0,
            "total": 50176.0,
            "data": 31744.0
        },
        "secondarycache": "all",
        "collection": "local",
        "exported": true,
        "vscan": false,
        "reservation": 0.0,
        "shadow": "none",
        "atime": true,
        "pool": "p1",
        "quota_snap": true,
        "name": "mnt1",
        "checksum": "fletcher4",
        "project": "default",
        "sharesftp": "",
        "nbmand": false,
        "reservation_snap": true,
        "sharedav": "",
        "rstchown": true,
        "root_acl": {
             "owner@:cC:fd:deny",
             "everyone@:rw:fd:allow",
             "user:admin1:rw:allow",
        }
        "smbshareacl": {
             "owner@:cC:fd:deny",
             "everyone@:rw:fd:allow",
             "user:admin1:rw:allow",
        }
}

Create Filesystem

The create filesystem command creates a filesystem with a given name residing in the given storage pool or project. The new filesystem with default properties is returned.

The following URI parameters are used:

pool - Storage pool name
project - Project name
filesystem - Filesystem name

Request parameters:

name – The filesystem name must be supplied to create a new filesystem
Filesystem properties – Any of the properties listed in filesystem properties or project properties can be set as initial values

Example Request (to create a filesystem named share-01 and owned by the user admin1):

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

{
    "name": "share-01",
    "root_user": "admin1"
}

Successful creation returns HTTP status 201 (Created) with the Location header containing the URI of the new filesystem. The body contains all filesystem properties in JSON format.

Example Result:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/storage/v1/pools/p1/projects/proj-01/filesystems/share-01

{
    "filesystem": {
        "name": "share-01",
        "pool": "p1",
        "collection": "local",
        "project": "proj-01",
        "root_user": "admin1"
        ...
    }
}

Modify Filesystem

The modify filesystem command changes the attributes of an existing filesystem. Successful response returns HTTP status 202 (Accepted) and lists all filesystem properties.

The following URI parameters are used:

pool - Storage pool name
project - Project name
filesystem - Filesystem name

Request parameters: filesystem properties – Any of the filesystem or project properties can be modified.

Example Request (to change a filesystem name from share-01 to new-name and change the owner to nobody):

PUT /api/storage/v1/pools/p1/projects/proj-01/filesystems/share-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/filesystems/share-01

{
    "filesystem": {
        "name": "new-name",
        "pool": "p1",
        "collection": "local",
        "project": "proj-01",
        "root_user": "nobody"
        ...
    }
}

Delete Filesystem

The delete filesystem command removes a single filesystem in a given pool or project.

The following URI parameters are used:

pool - Storage pool name
project - Project name
filesystem - Filesystem 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/filesystems/share-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

Filesystem Quota and Usage

User or group quotas can be created or modified with POST or PUT requests, respectively. GET requests to filesystem use resources are used to get usage data per user or per group for the project.