Local Filesystems
Local Filesystems live on one Atlas System only, and are highly tuned for high bandwidth and low latency
Basic Operations
Local Filesystems may be created, read, updated, and destroyed from the API. When a Local Filesystem is created, we set the permissions on it to be easy for our users.
Each Local Filesystem will give you back some details, which may be confusing. Here’s a key to what the fields mean.
(AVAIL): Available on each file system (USED): Being used total (USEDSNAP): Being consumed only by snapshots of each data set (USEDDS): Being used only by the data set itself (USED REFRESERV): Being used by a ref reservation set on the data set (USEDCHILD): Being used by the children of this data set, same as USED above but for all children, not including parent
List the Local Filesystems
Send this request to get back a list of all the local filesystems.
Request Object
+ URL
/api/v2/zfs
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
Sending this should get you back a valid response, if you’ve sent correct credentials.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
[
{
"name": "pool01",
"used_snapshots": 0,
"used_deleting_snapshots": 31372,
"used_reclaiming": 0,
"used_children": 92070,
"avail": 7714809716174,
"used": 123442,
"refer": 31372,
"mountpoint": "/pool01",
"total": 7714809839616
}
]
+ Schema
{
"type": "array",
"items": [
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"used_snapshots": {
"type": "integer"
},
"used_deleting_snapshots": {
"type": "integer"
},
"used_reclaiming": {
"type": "integer"
},
"used_children": {
"type": "integer"
},
"avail": {
"type": "integer"
},
"used": {
"type": "integer"
},
"refer": {
"type": "integer"
},
"mountpoint": {
"type": "string"
},
"total": {
"type": "integer"
}
}
}
]
}
Get Details on a Filesystem
You can also specifically request a Local Filesystem by pool and Fs Name.
Request Object
+ URL
/api/v2/zfs/$poolName/details
+ Method
POST
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"fs": "SampleFS"
}
Response Object
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"name": "B01/B01",
"used_snapshots": 0,
"used_data_set": 39160,
"used_reclaiming": 0,
"used_children": 0,
"avail": 107793969015020,
"used": 39160,
"refer": 39160,
"mountpoint": "/B01/B01",
"total": 107793969054180,
"props": [
{
"name": "B01/B01",
"property": "quota",
"value": "0",
"source": "default"
},
{
"name": "B01/B01",
"property": "reservation",
"value": "0",
"source": "default"
},
{
"name": "B01/B01",
"property": "mountpoint",
"value": "/B01/B01",
"source": "default"
},
{
"name": "B01/B01",
"property": "compression",
"value": "lz4",
"source": "local"
},
{
"name": "B01/B01",
"property": "atime",
"value": "off",
"source": "local"
},
{
"name": "B01/B01",
"property": "readonly",
"value": "off",
"source": "local"
},
{
"name": "B01/B01",
"property": "casesensitivity",
"value": "insensitive",
"source": "-"
},
{
"name": "B01/B01",
"property": "recordsize",
"value": "1048576",
"source": "local"
},
{
"name": "B01/B01",
"property": "nbmand",
"value": "on",
"source": "local"
},
{
"name": "B01/B01",
"property": "sync",
"value": "disabled",
"source": "local"
},
{
"name": "B01/B01",
"property": "snapdir",
"value": "hidden",
"source": "local"
},
{
"name": "B01/B01",
"property": "overlay",
"value": "off",
"source": "local"
}
]
}
Create a new Filesystem
Local Filesystems are created in pools, which are collections of storage devices assembled to provide great performance.
Request Object
+ URL
/api/v2/zfs/create
+ Method
POST
+ Parameters
name (string, required, Body) - the name to be given to the local filesystem
pool (string, required, Body) - the name of the pool to create the local filesystem upon
properties (object of options, Body) - an object containing key value pairs for setting
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"name": "SampleFS",
"pool": "DaPool01",
"properties": {
"aclinherit":"passthrough",
"casesensitivity":"insensitive",
"recordsize":"1M",
"snapdir":"hidden",
"sync":"disabled",
"quota":"none",
"reservation":"none",
"compression":"lz4",
"atime":"off",
"readonly":"off",
"nbmand":"on",
"overlay":"off",
"acltype":"posixacl",
"xattr":"sa"
}
}
Update a Filesystem
Updating a Local Filesystem is fairly easy, with the exception being renaming and setting properties when 'readonly ' is on.
Request Object
+ URL
/api/v2/zfs/$poolName/update
+ Method
POST
+ Parameters
poolName (string, required, URL Param) - the name of the pool
fs (string, optional, Body) - the name of the local filesystem. If this parameter is not included, this request will update the zfs properties of the zpool specified
properties (string, Body) - a stringified JSON object that contains the key value pairs for updating a filesystem
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"fs": "SampleFS",
"properties": "{\"aclinherit\":\"passthrough\",\"casesensitivity\":\"insensitive\",\"recordsize\":\"1M\",\"snapdir\":\"hidden\",\"sync\":\"disabled\",\"quota\":\"none\",\"reservation\":\"none\",\"compression\":\"lz4\",\"atime\":\"off\",\"readonly\":\"off\",\"nbmand\":\"on\",\"overlay\":\"off\",\"acltype\":\"posixacl\",\"xattr\":\"sa\"}"
}
Response Object
|
It has been reported that there’s a bug in Atlas 2.3 where a successful update on a ZFS filesystem returns a response with an HTTPS status code, 500. We have verified that the bug is fixed in Atlas 2.4. Please contact the support team for upgrading your system to 2.4, or the latest release, in order to resolve this issue. If you would like to continue using Atlas 2.3, please make sure that your filesystem is correctly updated after getting the error response from your API request. |
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
{
"code": 500,
"message": {
"killed": false,
"code": 2,
"signal": null,
"cmd": "zfs set bandy/bahn"
},
"i18n": "api_zfsUpdateError",
"name": "Failed to Update filesystem"
}
Destroy a Filesystem
Destroying a Local Filesystem with the API does not have the usual safeguards that the UI uses. (An "Are you sure?" type dialog) Please take extreme care when using this route.