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, required, Body) - the name of the local filesystem 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 andy/ahn" }, "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.