PowerScale OneFS

API Reference
9.2.0.0

November 2021
Rev. 02
Notes, cautions, and warnings

NOTE: A NOTE indicates important information that helps you make better use of your product.

CAUTION: A CAUTION indicates either potential damage to hardware or loss of data and tells you how to avoid
the problem.

WARNING: A WARNING indicates a potential for property damage, personal injury, or death.

© 2015 -2021 Dell Inc. or its subsidiaries. All rights reserved. Dell, EMC, and other trademarks are trademarks of Dell Inc. or its subsidiaries.
Other trademarks may be trademarks of their respective owners.
 Contents

Chapter 1: Introduction to this guide............................................................................................. 5

About this guide................................................................................................................................................................... 5
About the PowerScale SDK.............................................................................................................................................. 5
Scale-out NAS overview....................................................................................................................................................6
Getting help.......................................................................................................................................................................... 6

Chapter 2: Introduction to the OneFS API..................................................................................... 7

OneFS API overview........................................................................................................................................................... 7
OneFS API architecture................................................................................................................................................7
OneFS API terminology ............................................................................................................................................... 8
OneFS API access............................................................................................................................................................... 9
HTTP methods..............................................................................................................................................................10
OneFS API authentication................................................................................................................................................10
HTTP Basic Authentication........................................................................................................................................10
Session cookies............................................................................................................................................................. 11
Authentication with CSRF protection..................................................................................................................... 14

Chapter 3: System configuration API........................................................................................... 16

System configuration API overview.............................................................................................................................. 16
Collection patterns.......................................................................................................................................................16
API versions in OneFS.................................................................................................................................................19
API directory and browsing URIs..............................................................................................................................21
OneFS API self-documentation............................................................................................................................... 25
Code samples for file system configuration................................................................................................................26
System configuration API resources............................................................................................................................ 26
Authentication and access control..........................................................................................................................26
Auditing.......................................................................................................................................................................... 49
Access zones................................................................................................................................................................52
NFS................................................................................................................................................................................. 54
SMB................................................................................................................................................................................ 62
S3.................................................................................................................................................................................... 67
FTP...................................................................................................................................................................................71
HTTP and HTTPS security........................................................................................................................................ 72
HDFS...............................................................................................................................................................................72
OpenStack Swift..........................................................................................................................................................78
Networking....................................................................................................................................................................79
IPMI remote power..................................................................................................................................................... 86
System jobs...................................................................................................................................................................88
Cluster statistics..........................................................................................................................................................93
FSA................................................................................................................................................................................. 95
Events and alerts.........................................................................................................................................................99
HealthCheck................................................................................................................................................................102
Snapshots.................................................................................................................................................................... 104
NDMP backup and recovery................................................................................................................................... 109

Contents 3
 SyncIQ backup and recovery................................................................................................................................... 113
SmartLock................................................................................................................................................................... 128
Deduplication.............................................................................................................................................................. 130
General cluster configuration..................................................................................................................................132
Licensing...................................................................................................................................................................... 149
Security hardening.....................................................................................................................................................150
External key management for SEDs using KMIP............................................................................................... 152
Upgrading OneFS.......................................................................................................................................................157
Cluster date and time............................................................................................................................................... 162
Managing SNMP settings........................................................................................................................................ 163
Hardware..................................................................................................................................................................... 163
File pools...................................................................................................................................................................... 165
Storage pools.............................................................................................................................................................. 168
CloudPools................................................................................................................................................................... 174
SmartQuotas............................................................................................................................................................... 178
Common Anti-Virus Agent (CAVA)....................................................................................................................... 183
ICAP anti-virus............................................................................................................................................................184
Performance................................................................................................................................................................187

Chapter 4: File system access API............................................................................................. 190

File system access API overview................................................................................................................................. 190
Common response headers..................................................................................................................................... 190
Common request headers........................................................................................................................................ 191
Common namespace attributes.............................................................................................................................. 191
Troubleshooting............................................................................................................................................................... 192
File system access operations...................................................................................................................................... 193
Access points..............................................................................................................................................................194
Directory operations..................................................................................................................................................201
File operations............................................................................................................................................................ 215
Access control lists...................................................................................................................................................228
Query operations.......................................................................................................................................................249
SmartLock settings...................................................................................................................................................253
Code samples for file system access......................................................................................................................... 256

4 Contents
 1
Introduction to this guide
The OneFS API reference guide is an introduction to the OneFS API, and documents the system configuration API resource
handlers and the file system API.
Topics:
• About this guide
• About the PowerScale SDK
• Scale-out NAS overview
• Getting help

About this guide

This guide describes how the PowerScale OneFS application programming interface (API) provides access to cluster
configuration and access to cluster data. This guide also provides a list of all available API resource URLs, HTTP methods,
and parameter and object descriptions.
Your suggestions help us to improve the accuracy, organization, and overall quality of the documentation. Send your
feedback to http://bit.ly/isilon-docfeedback. If you cannot provide feedback through the URL, send an email message to
[email protected].

About the PowerScale SDK

Information about the PowerScale SDK documentation and resources.

The PowerScale software development kit (PowerScale SDK) is a collection of documentation, resources, tools, and code
samples that allow the creation of applications for the PowerScale family of products.

Table 1. PowerScale SDK documentation and resources

Resource Location
PowerScale support https://www.dell.com/support/home/en-us/product-
support/product/
GitHub repository for the PowerScale SDK https://github.com/isilon/isilon_sdk
PowerScale SDK Info Hub https://www.dell.com/support/article/en-us/sln318906/
isilon-sdk-isilon-info-hub

Table 2. PowerScale SDK code samples

Resource Location
Python Language Bindings https://github.com/Isilon/isilon_sdk_python
Stat Browser https://github.com/Isilon/isilon_stat_browser

Introduction to this guide 5

Scale-out NAS overview
The scale-out NAS storage platform combines modular hardware with unified software to harness unstructured data. Powered
by the OneFS operating system, a cluster to deliver a scalable pool of storage with a global namespace.
The unified software platform provides centralized web-based and command-line administration to manage the following
features:
● A cluster that runs a distributed file system
● Scale-out nodes that add capacity and performance
● Storage options that manage files and tiering
● Flexible data protection and high availability
● Software modules that control costs and optimize resources.

Getting help
This topic contains resources for getting answers to questions about PowerScale products.

Dell Technologies support ● https://www.dell.com/support/incidents-online/en-us/contactus/product/

isilon-onefs
Telephone support ● United States: 1-800-SVC-4EMC (1-800-782-4362)
● Canada: 1-800-543-4782
● Worldwide: 1-508-497-7901
● Local phone numbers for a specific country or region are available at https://
www.dell.com/support/incidents-online/en-us/contactus/product/isilon-onefs.
PowerScale OneFS Documentation Info ● https://www.dell.com/support/kbdoc/en-us/000152189/powerscale-onefs-info-
Hubs hubs
Dell Community Board for self-help ● https://www.dell.com/community

6 Introduction to this guide

 2
Introduction to the OneFS API
The OneFS application programming interface (API) is divided into two functional areas: One area enables cluster configuration,
management, and monitoring functionality, and the other area enables operations on files and directories on the cluster.
Topics:
• OneFS API overview
• OneFS API access
• OneFS API authentication

OneFS API overview

The OneFS application programming interface (API) is divided into two functional areas: One area enables cluster configuration,
management, and monitoring functionality, and the other area enables operations on files and directories on the cluster. You
can send requests to the OneFS API through a Representational State Transfer (REST) interface, which is accessed through
resource URIs and standard HTTP methods.
An API request is sent over HTTPS to a cluster IP address or hostname. That request is authenticated and then authorized
through role-based access control (RBAC). After the request is approved, access is provided to either file system configuration
libraries or directories and files on the cluster.

OneFS API architecture

When you send an HTTP request through the OneFS API, your request is sent to an Apache server. The Apache server verifies
your username and password. The credentials are verified either through HTTP Basic Authentication for single requests or
through an established session to a single node for multiple requests.
After the user account is authenticated, the role-based access control (RBAC) verifies the privileges that are associated with
the user account that generated the request. If the user account has the required privileges, the request enables access to files
and directories on the cluster or to system configuration libraries, as per the resource URL provided in the request.
The following simplified diagram shows the basic flow of the two types of OneFS API requests:

Introduction to the OneFS API 7

 API request through
HTTPS/URI

HTTP Basic or Session

Apache Server
Authentication

/namespace RBAC /platform

(file system access API) (Authorization) (system configuration API)

Directories and files

System configuration libraries
on the cluster

OneFS API terminology

The following terms are relevant to understanding the OneFS API.

Term Definition
Access point Root path of the URL to the file system. You can define an
access point for any directory in the file system.
Collection Group of objects of a similar type. For example, all the user-
defined quotas in the system make up a collection of quotas.
Data object An object that contains content data, such as a file on the
system
Namespace The file system structure on the cluster
Object Containers or data objects
This term is also known as system configuration data that a
user creates, or a global setting on the system.
For example, a user-created object can be a file system
snapshot, quota, share, export, logical unit, or synchronization
policy.

8 Introduction to the OneFS API

Term Definition

An object can also be global settings on the system, such

as default share settings, HTTP server settings, snapshot
subsystem settings, and so on.

Resource An object, collection, or function that you can access by a

URI.

OneFS API access

By applying standard HTTP methods to resource URIs, you can modify file system settings or access content on any node in
a cluster through the OneFS API. When making multiple changes through the OneFS API, it is recommended that you send all
requests to a single node to avoid configuration collisions.
OneFS API resource URIs are composed of the following components.

Component Definition
my_cluster The IPv4 or IPv6 address or hostname for the cluster.
obj_port The number of the port. The default setting is 8080.

access_point The name of the access point, such as /ifs.

resource_path The file path to the directory that you want to access.
api_version The version of the OneFS API. It is an optional component, as
OneFS automatically uses the latest API.
collection_pattern The namespace, collection name, and object ID of the
resource that you want to configure.

In both types of API requests, you can append query parameters to the end of resource URIs to refine your request. For
example, you can revise a GET request to return only a set number of entries. In the following example, a maximum of 1,000
SMB shares are returned:

GET https://192.168.1.100:8080/platform/12/protocols/smb/shares?limit="1000"

File system configuration API requests

For file system configuration API requests, the resource URI is composed of the following components:

https://<my_cluster>:<obj_port>/<api-version>/<collection_pattern>

For example, you can send a GET request to the following URI to retrieve all SMB shares on a cluster. Where protocols is the
namespace, SMB is the collection name, and shares is the object ID:

GET https://192.168.1.100:8080/platform/12/protocols/smb/shares

File system access API requests

For file system access APIs requests, the resource URI is composed of the following components:

https://<my_cluster>:<obj_port>/namespace/<access_point>/<resource_path>

For example, you can send a GET request to the following URI to view files that are stored in the folder at /ifs/users/
folder1:

GET https://192.168.0.25:8080/namespace/ifs/users/folder1

Introduction to the OneFS API 9

For example, you can send a PUT request to the following URI to copy files that are stored in the folder to another location:

PUT https://10.7.146.164:8080/namespace/user1store/dir6

If you specify the header x-isi-ifs-mode-mask value as preserve, then it copies the file/dir mode, ownership, ACL,
timestamps information along with file data.
Also, in file system access API requests, you can indicate a special operation in your request by appending a predefined keyword
to the end of the resource URI. These keywords must be placed first in the argument list and must not contain any value. If
these keywords are placed in any other position in the argument list, the keywords are ignored. Predefined keywords are acl,
metadata, worm, and query. For example:

GET https://192.168.0.25:8080/namespace/ifs/users/folder1?acl

HTTP methods
You can apply certain HTTP methods to resource URIs through the OneFS API to modify file system settings or to access file
system content.
The following conditions apply to the HTTP methods available for the OneFS API:
● The GET method returns an object or collection.
● The HEAD method returns response header metadata without the response body content.
● The DELETE method removes an object from a collection.
● The POST method creates objects.
● The POST method returns a document indicating the success of the request and the location of the created resource.
● The PUT method enables partial modification of a resource.
● The PUT and POST methods do not return full resource entity bodies upon success; these methods return success or failure
codes.

OneFS API authentication

You can authenticate to OneFS API resource URIs by establishing a session with a cookie or through HTTP Basic Authentication.
You can only authenticate to resources for which you have privileges.
You can establish a session by creating a session cookie through the session resource. HTTP Basic Authentication requires more
system processing resources and is slower than authentication with a session cookie. If you want to initiate multiple requests
over a time, it is recommended that you create a session cookie.

HTTP Basic Authentication

With HTTP Basic Authentication (RFC 2617), you can create a standard Authorization header with a valid username and
password and send your request to the server. If the server authenticates your username and password, you can access the
resource.
The following example shows a sample HTTP Basic Authentication request.

GET https://<cluster-ip-or-host-name>:<port>/<resource_uri> HTTP/1.1

Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Privileges
Privileges permit users to complete tasks on a cluster.
Privileges are associated with an area of cluster administration such as Job Engine, SMB, or statistics.
Privileges have one of two forms:

10 Introduction to the OneFS API

Action Allows a user to perform a specific action on a cluster. For example, the ISI_PRIV_LOGIN_SSH privilege
allows a user to log in to a cluster through an SSH client.
Read/Write Allows a user to view or modify a configuration subsystem such as statistics, snapshots, or quotas. For
example, the ISI_PRIV_SNAPSHOT privilege allows an administrator to create and delete snapshots and
snapshot schedules. A read/write privilege can grant either read-only or read/write access. Read-only
access allows a user to view configuration settings; read/write access allows a user to view and modify
configuration settings.

Privileges are granted to the user on login to a cluster through the OneFS API, the web administration interface, SSH, or a
console session. A token is generated for the user, which includes a list of all privileges that are granted to the user. Each
URI, web-administration interface page, and command requires a specific privilege to view or modify the information available
through any of these interfaces.
Sometimes, privileges cannot be granted or there are privilege limitations.
● Privileges are not granted to users that do not connect to the System Zone during login or to users that connect through
the deprecated Telnet service, even if they are members of a role.
● Privileges do not provide administrative access to configuration paths outside of the OneFS API. For example, the
ISI_PRIV_SMB privilege does not grant a user the right to configure SMB shares using the Microsoft Management Console
(MMC).
● Privileges do not provide administrative access to all log files. Most log files require root access.
The privilege ISI_PRIV_RESTRICTED_AUTH provides limited administrative privileges. Administrators with the
ISI_PRIV_RESTRICTED_AUTH privilege can modify only those users and groups that have the same or less privilege. For
example, a help desk administrator can be granted ISI_PRIV_RESTRICTED_AUTH privileges to enable performing basic user and
group management operations without having the full abilities of the ISI_PRIV_AUTH privilege.

Session cookies
Establish a session by creating a session cookie through the session resource.
You can create a session cookie by sending credentials to a session service resource, which responds with a Set-Cookie header.
The Set-Cookie header contains an authentication token that can then be sent with subsequent requests to provide immediate
authentication.

Session resource overview

You can set a session cookie that provides extended authentication to a single node.

Object properties

Property Type Description

username String Specifies the username for the account requesting access
to the cluster
password String Specifies the password for the username requesting
access to the cluster
services Array Specifies a list of services to obtain access to
timeout_absolute Integer Retrieves the number of seconds before the session
expires in a GET request.
timeout_inactive Integer Retrieves the number of seconds of inactivity before the
session expires in a GET request.

Introduction to the OneFS API 11

Create a session
You can authenticate to a OneFS API resource URI by creating a session cookie and a session. When you create a session, you
extend your authentication to a node for multiple requests over a time.

About this task

Session cookies are specific to a single node; all requests must be made to the same node from which the session cookie is
obtained.

Steps
1. Send a POST request to /session/1/session by specifying the JSON content-type in the request header. Also specify your
username, password, and the service that you want to access in the request body. In the services property, specify
platform for system configuration or namespace for file system access.

Content-type: application/json
Body:
{
"username": "<string>",
"password": "<string>",
"services": ["platform" | “namespace”]
}

If the server validates your username and password, a Set-Cookie header is returned.
2. Obtain the isisessid value from the Set-Cookie header.

201 Created
Content-Length:104
Content-Type:application/json
Date:Fri, 22 Feb 2013 19:08:36 GMT
Set-Cookie:isisessid=12345678-abcd-1234-abcd-1234567890ab; path=/;
HttpOnly; Secure
Response Body:
{
"services":[
"platform",
"namespace"
],
"timeout_absolute":14400,
"timeout_inactive":900,
"username":"user123"
}

This value authenticates the session when you send a request through a session cookie.

Results
A session is created on the node on which the POST request was performed.

Send a request for access through a session cookie

Authenticate to a session through a session cookie.

Prerequisites
Create a session and obtain an isisessid value from the Set-Cookie header.

About this task

Do not specify a WWW-AUTHENTICATE header.

Steps
● Send a GET request to any API resource by typing the isisessid value in the Cookie request header.
If the server validates your username and password, access is granted.

12 Introduction to the OneFS API

Results
Authentication is granted for future requests on the specified node.
Example
Request example

GET 10.10.111.120:8080/platform/1/quota/quotas
Cookie: isisessid=12345678-abcd-1234-abcd-1234567890ab

Response example

200 OK
Content-Type:application/json
{
//JSON content
}

Get information about the current session

You can send a GET request to obtain information about the current session. If the server validates your session cookie, the
system returns a JSON document that contains information about the session. If the server does not validate the session ID
contained in the cookie, the server returns an error message.

Request syntax

GET /session/1/session
Cookie: isisessid=12345678-abcd-1234-abcd-1234567890ab

Response body
If authorization is successful:

"username": <string>
"services": [<string>, ...]
"timeout_absolute": <integer>,
"timeout_inactive": <integer>

{
"services":[
"platform",
"namespace"
],
"timeout_absolute":14396,
"timeout_inactive":900,
"username":"user123"
}

If authorization fails:

401 Unauthorized
Content-Type: application/json
{
"errors":[
{
"message":"authorization required"
}
]
}

Introduction to the OneFS API 13

Log out of a session
If you no longer required to stay authenticated to a node, you can log out of a session by deleting the session cookie. Session
cookies are configured to expire automatically in 15 minutes after a period of inactivity or in 4 hours after an absolute time.

Request syntax

DELETE /session/1/session
Cookie: isisessid=12345678-abcd-1234-abcd-1234567890ab

Response body
If authorization is successful:

204 No Content
Set-Cookie:isisessid=deleted; path=/; Expires=Thu, 01-Jan-1970 00:00:01 GMT; HttpOnly;
Secure
Content-Length: 0

If authorization fails:

401 Unauthorized
Content-Type: application/json
{
"errors":[
{
"message":"authorization required"
}
]
}

Authentication with CSRF protection

To protect OneFS APIs from Cross-Site Request Forgery (CSRF) attacks, the OneFS API enforces an additional anti-CSRF
token header be passed by the client with each request to the API. The anti-CSRF token is obtained from the server on the
initial API authentication request and, to pass authentication checks, must be included with all API requests along with the
session token.

Implement CSRF authentication

Obtain a CSRF token to submit with each OneFS API request.

Steps
1. Send an authentication request with credentials to the OneFS session API (/session/11/session).

$ curl -vk https://00.0.0.0:8080/session/1/session -X POST \

-H 'Content-Type: application/json' \
-d '{ "username": "testuser",
"password": "A_Pa$$word",
"services": ["platform"]
}'

The server validates supplied credentials and performs global API authorization checks. If client identity is confirmed and
authorization checks pass, the server responds with two tokens: a session token (isisessid) and an anti-CSRF token
(isicsrf). Save both tokens and submit them on subsequent API requests to pass authentication checks. If authentication
fails, then an appropriate HTTP error code is returned.
Response:

HTTP/1.1 201 Created

Date: Thu, 25 Jan 2020 22:34:20 GMT

14 Introduction to the OneFS API

 Server: Apache/2.2.34 (FreeBSD) mod_ssl/2.2.34 OpenSSL/1.0.2k-fips
mod_fastcgi/2.4.6
Set-Cookie: isisessid=924bb64a-cffd-4d98-9ccc-6703fabc3210; path=/;
HttpOnly; Secure; SameSite=strict
Set-Cookie: isicsrf=8c5da1e4-5508-4609-9978-4a6d283e4c3a; path=/;
Secure
Content-Length: 96
Content-Type: application/json

{"services":
["platform"],"timeout_absolute":14400,"timeout_inactive":900,"username":"testuser"}

2. For authenticated requests to the OneFS platform API, the client sends their OneFS session cookie. For successful CSRF
request validation checks, the client also sends the CSRF token cookie that is obtained at initial authentication in a special
header (X-CSRF-Token). Also send a populated Referrer header matching the connecting host.

$ curl -vk https://00.0.0.0:8080/platform/12/auth/id \

-b 'isisessid=924bb64a-cffd-4d98-9ccc-6703fabc3210' \
-H 'X-CSRF-Token: 8c5da1e4-5508-4609-9978-4a6d283e4c3a' \
--referer https://00.0.0.0:8080

Response:

HTTP/1.1 200 Ok
Date: Thu, 25 Jan 2020 22:53:03 GMT
Server: Apache/2.2.34 (FreeBSD) mod_ssl/2.2.34 OpenSSL/1.0.2k-fips
mod_fastcgi/2.4.6
Allow: GET, HEAD
Transfer-Encoding: chunked
Content-Type: application/json
{
"ntoken": {
"additional_id": [
{
"id": "SID:S-1-5-11"
}
],
"gid": {
"id": "GID:1800"
},
"group_sid": {
"id": "SID:S-1-5-21-902947705-743178377-3070079125-800"
},
"ifs_restricted": false,
"local_address": "00.0.000.000",
"on_disk_group_id": {
"id": "GID:1800"
},
"on_disk_user_id": {
"id": "UID:2000"
},
"privilege": [
{
"id": "ISI_PRIV_LOGIN_PAPI",
"name": "Platform API",
"read_only": true
}
],
"protocol": 10,
"remote_address": "00.0.000.000",
"uid": {
"id": "UID:2000"
},
"user_sid": {
"id": "SID:S-1-5-21-902947705-743178377-3070079125-1000"
},
"zid": 1,
"zone_id": "System"
}
}

Introduction to the OneFS API 15

 3
System configuration API
You can access cluster configuration, status information, and file system content through objects and collections of objects.
These objects and collections are exposed as resource URIs, which are represented as JavaScript Object Notation (JSON)
formatted documents.
Topics:
• System configuration API overview
• Code samples for file system configuration
• System configuration API resources

System configuration API overview

You can access cluster configuration, status information, and file system content through objects and collections of objects.
These objects and collections are exposed as resource URIs, which are represented as JavaScript Object Notation (JSON)
formatted documents.

Collection patterns
You can configure the file system on your cluster through the OneFS API. You can do so by applying HTTP methods to resource
URIs according to a set of collection patterns.
NOTE:

The OneFS API supports a maximum URI length of 8,198 characters.

Read a system object

You can read a system object that has a unique identifier through the GET method; the identifier is the name or system-
generated id for that object.
Request pattern:

GET https://<cluster-ip-or-host-name>:<port>/<api-version>/<namespace>/<object-id>

Response:

Content-Type: application/json
{
"<object>": {
"<property>": <value>,
...
}
}

Modify a system object

You can modify an object by sending one or more of the object properties through the PUT method. Only the specified
properties are modified on the resource, which leaves all other properties in their current state.
Request pattern:

PUT https://<cluster-ip-or-host-name>:<port>/<api-version>/<namespace>/<object-id>
Content-Type: application/json

16 System configuration API

 {
"<property>": <value>
...
}

Response:

{Standard JSON success or error response}

Read an entire collection

You can read all the objects in a collection through the GET method.
Request pattern:

GET https://<cluster-ip-or-host-name>:<port>/<api-version>/<namespace>/<collection-name>

Response:

Content-Type: application/json
{
"<collection>": [
"<property>": <value>
...
]
}

Read an object from a collection

You can read an object in a collection through the GET method.
Request pattern:

GET https://<cluster-ip-or-host-name>:<port>/<api-version>/<namespace>/<collection-name>/
<object-id>

Response:

Content-Type: application/json

{
"<collection>": [
"<property>": <value>
...
]
}

Create an object in a collection

You can create a user object in a collection through the POST method. The system responds with the final URI where the new
object is located.
Request pattern:

POST https://<cluster-ip-or-host-name>:<port>/<api-version>/<namespace>/<collection-
name>
Content-Type: application/json
{
"<property>": <value>,
...
}

System configuration API 17

Response:

Location: https://<cluster-ip-or-host-name>:<port>/<api-version>/<namespace>/<collection-
name>/<new-object-id>

Content-Type: application/json

{Standard JSON success or error response}

Modify an object in a collection

You can modify an object in a collection through the PUT method.
Request pattern:

PUT https://<cluster-ip-or-host-name>:<port>/<api-version>/<namespace>/<collection-name>/
<object-id>

Content-Type: application/json
{
"parameter_name": <value>
...
}

Response:

{Standard JSON success or error response}

Delete an object from a collection

You can delete a user object from a collection through the DELETE method.
Request pattern:

DELETE https://<cluster-ip-or-host-name>:<port>/<api-version>/<namespace>/<collection-
name>/<object-id>

Response:

{Standard JSON success or error response}

Filter a collection
You can apply a filter to a collection to retrieve user objects that match some common criteria.
Request pattern:

GET https://<cluster-ip-or-host-name>:<port>/<api-version>/<namespace>/<collection-name>?
<parameter_name>=<match-pattern>&...

Response:

Content-Type: application/json
{
"count": <integer>,
"<collection-name>": [
{
"<parameter-name>":
<matched-value>,
...
},
...
]
}

18 System configuration API

API versions in OneFS
OneFS provides version control of API resources.
To use the latest API version, retrieve the latest API version at the URI /platform/latest. In OneFS 9.2.0.0, the API version
is 12.
In OneFS 9.2.0.0, you can access the latest version of any configuration API resource at:

/platform/12/<path-to-resource>

Where resources have older versions, the older versions can be accessed at:

/platform/<version>/<path-to-resource>

The functionality of each resource is preserved, even with subsequent API versions. For example, if /resource/x is
introduced in API version 1, updated in API version 3, and then updated again in API version 8, the following URI-to-resource
mapping applies:

/platform/1/resource/x -> resource from API version 1

/platform/2/resource/x -> resource from API version 1
/platform/3/resource/x -> resource from API version 3
/platform/4/resource/x -> resource from API version 3
/platform/5/resource/x -> resource from API version 5
/platform/8/resource/x -> resource from API version 8

You are guaranteed that when you write code to a specific resource version, that behavior continues to function even if
subsequent API versions are released.
These are the OneFS API versions and their corresponding releases:

OneFS version API version

9.2.0.0 12
9.1.0.0 11
9.0.0.0 10
8.2.2 9
8.2.1 8
8.2 7
8.1.1 6
8.1 5
8.0.1 4
8.0 3

In future OneFS releases, when the configuration API version is incremented, the /platform/latest URI returns the latest
version number. You are guaranteed to access to the latest version of any resource by using the applicable version number in
the resource URI.
Older versions of certain resources might be deprecated in the future. Large changes in the underlying OneFS system and
configuration can cause certain fields or sets of fields to no longer be applicable. PowerScale only deprecates resources when
necessary. If an old version of a resource can function, it is accessible at its original API version number URI.

Changes to the OneFS API across releases

The following table lists deprecated APIs, by OneFS version, that are removed from OneFS when upgrading to a newer version.

System configuration API 19

Release API Deleted APIs
version
9.2.0.0 12 N/A
9.1.0.0 11 N/A
9.0.0.0 10 N/A
8.2.2 9 N/A
8.2.1 8 N/A
8.2.0 7 /1/cluster/smartconnect_zones
/2/versiontest/other/
/4/performance/workload-categories
/4/performance/workload-categories/<WORKLOAD-CATEGORY>
/4/performance/workload-categories/<WORKLOAD-CATEGORY>/workloads
/4/performance/workload-categories/<WORKLOAD-CATEGORY>/workloads /<WORKLOAD>
/4/performance/category-elements
/4/performance/category-elements/<CATEGORY-ELEMENT>
/6/cluster/branding

8.1.1.X 6 N/A
8.1.2.X
8.1.3.X

8.1.0.X 5 N/A
8.0.1.X 4 N/A
8.0.0.X 3 Upgrade supported from 8.0.0.X.

The following table lists deleted APIs that have been replaced with newer versions in later OneFS releases.

Release API Deleted APIs available in latest version

version
9.2.0.0 12 N/A
9.1.0.0 11 N/A
9.0.0.0 10 N/A
8.2.2 9 N/A
8.2.1 8 N/A
8.2.0 7
/3/cloud/accounts
/4/cloud/accounts
/4/network/interfaces
/3/network/interfaces
/3/network/groupnets/<GROUPNET>/subnets/<SUBNET>/pools/<POOL>/interfaces
/4/network/groupnets/<GROUPNET>/subnets/<SUBNET>/pools/<POOL>/interfaces
/3/cloud/accounts/<ACCOUNT>
/3/cloud/pools
/3/cloud/pools/<POOL>
/4/performance/settings
/4/cloud/accounts/<ACCOUNT>

8.1.1.X 6 N/A
8.1.2.X
8.1.3.X

8.1.0.X 5 N/A
8.0.1.X 4 N/A

20 System configuration API

Release API Deleted APIs available in latest version
version
8.0.0.X 3 Upgrade supported from 8.0.0.X.

The following table shows deleted APIs that were replaced in a later API version.

Deleted APIs Same APIs with updated version

/3/cloud/accounts /3.1/cloud/accounts
/4/cloud/accounts /4.1/cloud/accounts
7/cloud/accounts

/4/network/interfaces /7/network/interfaces
/3/network/interfaces

/3/network/groupnets/<GROUPNET>/subnets/<SUBNET>/ /7/network/groupnets/<GROUPNET>/subnets/
pools/<POOL>/interfaces <SUBNET>/pools/<POOL>/interfaces
/4/network/groupnets/<GROUPNET>/subnets/<SUBNET>/
pools/<POOL>/interfaces

/3/cloud/accounts/<ACCOUNT> /3.1/cloud/accounts/<ACCOUNT>
/4/cloud/accounts/<ACCOUNT> /4.1/cloud/accounts/<ACCOUNT>
/7/cloud/accounts/<ACCOUNT>

/3/cloud/pools /3.1/cloud/pools
/7/cloud/pools

/3/cloud/pools/<POOL> /3.1/cloud/pools/<POOL>
/7/cloud/pools/<POOL>

/4/performance/settings /7/performance/settings

API directory and browsing URIs

There are special URIs that you can use to get more information about system configuration API resources and their versions.

List all API URIs

You can list all URIs for the system configuration API.
To retrieve a list of all system configuration API URIs:

https://<cluster-ip>:<port>/platform/?describe&list

The example above retrieves a separate listing for every update of each resource. For example, the resource for /cluster/
config was introduced in API version 1 and updated in version 3, so /platform/?describe&list lists both:

"/1/cluster/config"
"/3/cluster/config"

NOTE: /2/cluster/config is also a valid URI, and forwards the same resource as /1/cluster/config, because
there were no updates to the resource in API version 2.

System configuration API 21

List all URIs for a specific API version
You can list all the URIs for a specific version of the system configuration API.
To retrieve a list of all URIs available for the specified API version:

https://<cluster-ip>:<port>/platform/<version>/?describe&list

For example, the following retrieves all URIs available for API version 14:

https://<cluster-ip>:<port>/platform/14/?describe&list

The above query generates an output like the following example:

{
"directory" :
[
"/14/api/sessions/invalidations
/14/api/sessions/invalidations/<USER>
/14/api/sessions/rekey
/14/api/settings/sessions",
.
.
.
"/14/upgrade/cluster/patch/patches",
"/14/upgrade/cluster/patch/patches/<ID>",
]
}

List all URIs updated and newly created in a specific API version
You can list all the URIs that changed in a specific version of the system configuration API.
To retrieve a list of changed URIs that were updated for a specific API version:

https://<cluster-ip>:<port>/platform/changed/<version>

The previous example also returns a list of any removed URIs that were originally introduced or updated at the specified version.
But that now have been permanently deprecated and can no longer be accessed.
NOTE: Usually there is at least one new resource that provides the current functionality to replace any deprecated
resources.
For example, to list all URIs that changed in API version 12:

https://<cluster-ip>:<port>/platform/changed/12

The above query generates an output like the following example:

{
"changed" :
[
"/12/auth/log-level",
"/12/cluster/nodes",
"/12/cluster/nodes/<LNN>",
"/12/cluster/nodes/<LNN>/hardware",
"/12/cluster/nodes/<LNN>/state",
"/12/cluster/nodes/<LNN>/state/servicelight",
"/12/cluster/nodes/<LNN>/status",
"/12/cluster/nodes/<LNN>/status/nvram",
"/12/cluster/nodes/<LNN>/status/powersupplies",
"/12/config/exports",
"/12/config/exports/<ID>",
"/12/config/imports",
"/12/config/imports/<ID>",
"/12/event/channels",
"/12/event/channels/<ID>",
"/12/event/eventgroup-definitions",

22 System configuration API

"/12/event/eventgroup-definitions/<ID>",
"/12/event/eventgroup-occurrences",
"/12/event/eventgroup-occurrences/<ID>",
"/12/event/maintenance",
"/12/event/settings",
"/12/event/suppress",
"/12/event/suppress/<ID>",
"/12/filepool/policies",
"/12/filepool/policies/<POLNAME>",
"/12/job/job-summary",
"/12/keymanager/kmip/server/verify",
"/12/keymanager/kmip/servers",
"/12/keymanager/kmip/servers/<ID>",
"/12/keymanager/sed/migrate",
"/12/keymanager/sed/settings",
"/12/keymanager/sed/status",
"/12/keymanager/sed/status/<LNN>",
"/12/local/cluster/nodes",
"/12/local/cluster/nodes/<LNN>",
"/12/local/cluster/nodes/<LNN>/hardware",
"/12/local/cluster/nodes/<LNN>/state",
"/12/local/cluster/nodes/<LNN>/state/servicelight",
"/12/local/cluster/nodes/<LNN>/status",
"/12/local/cluster/nodes/<LNN>/status/nvram",
"/12/local/cluster/nodes/<LNN>/status/powersupplies",
"/12/local/keymanager/kmip/server/verify",
"/12/local/keymanager/sed/status",
"/12/local/network/interfaces",
"/12/network/external",
"/12/network/groupnets/<GROUPNET>/subnets",
"/12/network/groupnets/<GROUPNET>/subnets/<SUBNET>/pools",
"/12/network/groupnets/<GROUPNET>/subnets/<SUBNET>/pools/<POOL>",
"/12/network/interfaces",
"/12/network/pools",
"/12/performance/datasets",
"/12/performance/datasets/<DATASET>",
"/12/performance/datasets/<DATASET>/filters",
"/12/performance/datasets/<DATASET>/filters/<FILTER>",
"/12/performance/datasets/<DATASET>/workloads",
"/12/performance/datasets/<DATASET>/workloads/<WORKLOAD>",
"/12/performance/metrics",
"/12/performance/metrics/<METRIC>",
"/12/performance/settings",
"/12/protocols/hdfs/log-level",
"/12/protocols/nfs/log-level",
"/12/protocols/nfs/netgroup/save",
"/12/protocols/nfs/settings/global",
"/12/protocols/s3/buckets",
"/12/protocols/s3/buckets/<BUCKET>",
"/12/protocols/s3/settings/zone",
"/12/protocols/smb/log-level",
"/12/quota/quotas",
"/12/quota/quotas/<QID>",
"/12/storagepool/nodetypes",
"/12/storagepool/nodetypes/<NID>",
"/12/storagepool/nodetypes/<NID>/assess",
"/12/upgrade/cluster/drain",
"/12/upgrade/cluster/drain/list",
"/12/upgrade/cluster/drain/timeout",
"/12/upgrade/cluster/firmware/upgrade",
"/12/upgrade/cluster/nodes",
"/12/upgrade/cluster/rolling-reboot",
"/12/upgrade/cluster/upgrade"
],
"removed" : []
}

System configuration API 23

List URI introduction or update version
You can retrieve a list of URIs detailing when a resource was introduced or updated in the system configuration API.
To retrieve a list of URIs representing the API versions in which a specified resource was introduced or updated:

https://<cluster-ip>:<port>/platform/updated/<path-to-resource>

For example, to retrieve information about when the API resource for OneFS audit settings was introduced or updated:

https://<cluster-ip>:<port>/platform/updated/audit/settings

The above query generates an output like the following example:

{
"removed" : [],
"updated" : [ "/1/audit/settings", "/3/audit/settings", "/7/audit/settings" ]
}

List API resource versions

You can list all the versions in which a resource exists.
To retrieve a list of URIs representing all API versions in which the specified resource exists as a valid resource in any form,
including versions in which the resource was not updated, but excluding versions before the resource existed:

https://<cluster-ip>:<port>/platform/versions/<path-to-resource>

For example, to list the versions of the resource for NFS NLM sessions:

https://<cluster-ip>:<port>/platform/versions/protocols/nfs/nlm/sessions

The above query generates an output like the following example:

{
"versions" :
[
"/1/protocols/nfs/nlm/sessions",
"/2/protocols/nfs/nlm/sessions",
"/3/protocols/nfs/nlm/sessions",
"/3.0/protocols/nfs/nlm/sessions",
"/3.1/protocols/nfs/nlm/sessions",
"/3.2/protocols/nfs/nlm/sessions",
"/4/protocols/nfs/nlm/sessions",
"/4.0/protocols/nfs/nlm/sessions",
"/4.1/protocols/nfs/nlm/sessions",
"/5/protocols/nfs/nlm/sessions",
"/5.0/protocols/nfs/nlm/sessions",
"/5.1/protocols/nfs/nlm/sessions",
"/6/protocols/nfs/nlm/sessions",
"/7/protocols/nfs/nlm/sessions",
"/8/protocols/nfs/nlm/sessions",
"/9/protocols/nfs/nlm/sessions",
"/10/protocols/nfs/nlm/sessions",
"/11/protocols/nfs/nlm/sessions"
]
}

24 System configuration API

OneFS API self-documentation
The system configuration API is self-documenting. You can access detailed information about each URI by appending the ?
describe query parameter. This self-documentation includes URI descriptions, query arguments, allowable HTTP methods, and
the request and response JSON representation structures.
To access the OneFS API self-documentation through any /platform resource URI, append the ?describe query parameter
as follows:

https://<cluster-ip>:<port>/platform/<version>/<path-to-resource>?describe

For example, the following retrieves the API version 12 JSON schema documentation for upgrading nodes on a OneFS cluster:

https://<cluster-ip>:<port>/platform/12/upgrade/cluster/nodes?describe

The above query generates an output like the following example:

Resource URL: /platform/12/upgrade/cluster/nodes

Overview: View information about nodes during an upgrade, rollback, or

pre-upgrade assessment.

Methods: GET

********************************************************************************

Method GET: View information about nodes during an upgrade, rollback, or

pre-upgrade assessment.

URL: GET /platform/12/upgrade/cluster/nodes

Query arguments:
by_domain=<boolean> If true, tag nodes that are assigned to like-failure domains

GET response body schema:

{
"type": [
{
"additionalProperties": false,
"type": "object",
"description": "A list of errors that may be returned.",
"properties": {
"errors": {
"minItems": 1,
"items": {
"additionalProperties": false,
"type": "object",
"description": "An object describing a single error.",
"properties": {
"field": {
"minLength": 1,
"type": "string",
"description": "The field with the error if applicable.",
"maxLength": 8192
},
.
.
.

You can retrieve a list of all the resources for a feature by appending the describe, list, and all query parameters. The
content is returned as mime-type text or plain. For example, to return a list of all resource URIs for snapshots, type the following
URL:

https://<cluster-ip-or-host-name>:<port>/platform/12/snapshot/snapshots?describe&list&all

You can retrieve a list of all the resource URIs on your cluster by typing the following URL:

https://<cluster-ip-or-host-name>:<port>/platform?describe&list

System configuration API 25

You can retrieve the JSON-formatted documents that are in the self-documentation through any resource URI by appending the
query parameters describe and json. This content is returned as mime-type application/json.
For example, to obtain the JSON-formatted document for the quotas resource, type the following URL:

https://<cluster-ip-or-host-name>:<port>/platform/12/quota/quotas?describe&json

If you include any values for either the describe or json parameters, the values are ignored.

Code samples for file system configuration

Code samples illustrate the basic syntax of OneFS API requests for file system configuration.
You can access a .zip file to download that contains code samples for the Python programming language and for curl commands
from the OneFS SDK - Info Hub. The sample code provides brief examples on how to access, modify, and delete configuration
settings on your cluster through OneFS API requests.

System configuration API resources

You can make requests through the OneFS API to access system configuration resources.

Authentication and access control overview

OneFS supports several methods for ensuring that your cluster remains secure. It includes UNIX- and Windows-style
permissions for data-level access control, access zones for data isolation, and role-based administration control access to
system configuration settings.
OneFS is designed for a mixed environment that allows you to configure both Access Control Lists (ACLs) and standard UNIX
permissions on the cluster file system.
NOTE: In most situations, the default settings are sufficient. You can configure additional access zones, custom roles, and
permissions policies as necessary for your particular environment.

Authentication classes
Authentication classes define values for the object properties in authentication resources.

<persona-id>
The <persona-id> class must be set in the following format: user:<string>, group:<string>, SID:<string>,
UID:<string>, GID:<string>, such as: GID:2003 or user:johndoe.

<persona>
The <persona> class must be set with either the persona-id or the type and name parameters, as follows:

Property Type Description

id <persona-id> Specifies the serialized form of the persona
type String Specifies the type of persona which is combined with
a name. The type of the persona can be set to user,
group, or wellknown.
name String Specifies the persona name, which is combined with a
type

26 System configuration API

<user-id>
The <user-id> class must be set in the following format: user:<string>, SID:<string>, UID:<string>, such as:
UID:2283 or user:johndoe.

<user>
The <user> class contains the following properties:

Property Type Description

dn String Specifies the distinguished name for the user
dns_domain String Specifies the DNS domain
domain String Specifies the domain that the object is part of
email String Specifies an email address
enabled Boolean True if the user is enabled.
expired Boolean True if the password for the user has expired.
expiry Integer Specifies the UNIX Epoch time at which the user account
expires.
gecos String Specifies the GECOS value, which is usually the full name
generated_gid Boolean Indicates if the GID was generated.
generated_uid Boolean Indicates if the UID was generated.
gid <persona> Specifies the group ID
home_directory String Specifies the home directory for the user
id String Specifies the system ID given to the user or group. In a
POST request, this value is the ID that indicates the item
in the collection item resource path.
locked Boolean Specifies if the account is locked.
max_password_age Integer Specifies the maximum age in seconds allowed for the
password before the password expires.
member_of Array of [<persona>] Specifies groups that this user or group is members of
name String Specifies a user or group name
password_expired Boolean Specifies whether the password has expired.
password_expires Boolean Specifies whether the password is allowed to expire.
password_last_set Integer Specifies the last time that the password was set
primary_group_sid <persona> Specifies the security ID of the primary group for the user
prompt_password_change Boolean Prompts a password change for the user at the next login
provider String Specifies the authentication provider the object belongs
to.
sam_account_name String Specifies a user or group name
shell String Specifies the path to the shell for the user
sid <persona> Specifies the security identifier
type String Indicates the object type
uid <persona> Specifies the user ID
upn String Specifies the principal name for the user

System configuration API 27

Property Type Description
user_can_change_password Boolean Specifies whether the user can change their own
password.

<group-id>
The <group-id> class must be set in the following format: group:<string>, SID:<string>, GID:<string>, such as:
GID:2003 or group:admins.

<group>
The <group> class contains the following properties:

Property Type Type Property of

dn String Specifies the distinguished name for the group or groups
object.
dns_domain String Specifies the DNS domain for the object. groups
domain String Specifies the domain of the group. groups
generated_gid Boolean Indicates if the GID was generated. groups
gid <persona> Specifies properties for the persona. groups
id String Specifies the system ID given to the user or groups
group. In a POST request, this value indicates the
item in the collection item resource path.
member_of Array of Specifies properties for groups that this user or groups
[<persona>] group is member of
name String Specifies a user or group name groups
provider String Specifies an authentication provider groups
sam_account_name String Specifies a user or group name groups
sid <persona> Specifies properties for the security identifier groups
type String Indicates the object type groups

<privilege>
The <privilege> class must be set as follows:

Property Type Description

id String Specifies the formal name of the privilege
name String Specifies the name of the privilege
read-only Boolean Determines if the privilege is specified as read-only.

28 System configuration API

Authentication resources
You can retrieve, create, modify, or delete authentication providers, users, groups, and other configurations and settings
through authentication resource URIs.

Authentication access token resource

Retrieve information about the access token for the authenticated user.

Operation Method and URI

Retrieve the security token for the authenticated user. GET <cluster-ip:port>/platform/12/auth/id

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/id?
information about query parameters and object properties. describe

Authentication user access resource

Retrieve the access rights that a specified user has for a file.

Operation Method and URI

Retrieve the access rights that a user has for a specified file. GET <cluster-ip:port>/platform/12/auth/
access/<user-id>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. access/<user-id>?describe

Security objects cache resource

Flush the security objects cache.

Operation Method and URI

Flush objects from the security objects cache POST <cluster-ip:port>/platform/12/auth/cache
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/cache?describe
information about query parameters and object properties.

Authentication user password resource

Enable users to change their password on a local authentication provider.

Operation Method and URI

Change the password for a user. PUT <cluster-ip:port>/platform/12/auth/
users/<user-id>/change_password

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. users/<user-id>/change_password?describe

Authentication users resource

Create, modify, delete, or retrieve information about users who are authenticated through a local authentication provider.
Remote users are restricted to read-only operations.

Operation Method and URI

Get all users. GET <cluster-ip:port>/platform/12/auth/users

System configuration API 29

Operation Method and URI
Get one user. GET <cluster-ip:port>/platform/12/auth/
users/<user-id>

Modify a user. PUT <cluster-ip:port>/platform/12/auth/

users/<user-id>

Create a user. POST <cluster-ip:port>/platform/12/auth/

users

Flush the users cache. DELETE <cluster-ip:port>/platform/12/auth/

users

Delete a user. DELETE <cluster-ip:port>/platform/12/auth/

users/<user-id>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. users?describe

Authentication users member of resource

Create, retrieve, or remove group membership for a user who is authenticated through a local authentication provider. Remote
users are restricted to read-only operations.

Operation Method and URI

Retrieve the groups that a user is a member of. GET <cluster-ip:port>/platform/12/auth/
users/<user-id>/member_of

Add a group membership for a user. POST <cluster-ip:port>/platform/12/auth/

users/<user-id>/member_of

Remove a group membership from a user. DELETE <cluster-ip:port>/platform/12/auth/

users/<user-id>/member_of/<group-id>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. users/<user-id>/member_of?describe

Authentication groups resource

Create, modify, delete, or retrieve information about groups that are authenticated through a local or remote authentication
provider.

Operation Method and URI

Retrieve all groups. GET <cluster-ip:port>/platform/12/auth/
groups

Flush the groups cache. DELETE <cluster-ip:port>/platform/12/auth/

groups

Retrieve a group. GET <cluster-ip:port>/platform/12/auth/

groups/<group-id>

Create a group. POST <cluster-ip:port>/platform/12/auth/

groups

Modify a group. PUT <cluster-ip:port>/platform/12/auth/

groups/<group-id>

Delete a group. DELETE <cluster-ip:port>/platform/12/auth/

groups/<group-id>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. groups?describe

30 System configuration API

Authentication groups members resource
Add, remove, or retrieve information about the members of a group who are authenticated through a local or remote
authentication provider.

Operation Method and URI

Retrieve the members of a group. GET <cluster-ip:port>/platform/12/auth/
groups/<group-id>/members

Add a member to a group. POST <cluster-ip:port>/platform/12/auth/

groups/<group-id>/members

Remove a member from a group. DELETE <cluster-ip:port>/platform/12/auth/

groups/<group-id>/members/<persona-id>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. groups/<group-id>/members?describe

Authentication netgroups resource

Retrieve information about the members of a netgroup that are specified through a local or remote authentication provider.

Operation Method and URI

Retrieve the members of a netgroup. GET <cluster-ip:port>/platform/12/auth/
netgroups/<netgroup>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. netgroups/<netgroup>?describe

Authentication settings mapping resource

Modify or retrieve information about identity mapping settings.

Operation Method and URI

Retrieve default identity mapping settings. GET <cluster-ip:port>/platform/12/auth/
settings/mapping/defaults

Modify the default identity mapping settings. PUT <cluster-ip:port>/platform/12/auth/

settings/mapping/defaults

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. settings/mapping/defaults?describe

Authentication mapping identities resource

Set, modify, delete, or retrieve information about identity mappings.

Operation Method and URI

Retrieve identity mapping (UID, GID, SID, and on-disk) for the GET <cluster-ip:port>/platform/12/auth/
specified source persona. mapping/identities/<identity>

Flush the identity mappings cache. DELETE <cluster-ip:port>/platform/12/auth/

mapping/identities?remove=true

Flush the identity mapping. DELETE <cluster-ip:port>/platform/12/auth/

mapping/identities/<identity>?remove=true

Manually set or modify the mapping between two personae. POST <cluster-ip:port>/platform/12/auth/
mapping/identities

System configuration API 31

Operation Method and URI
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. mapping/identities?describe
GET <cluster-ip:port>/platform/12/auth/
mapping/identities/<identity>?describe

Authentication mapping users rules resource

Retrieve the rules for user mapping. User mapping rules define how access tokens are created during authentication.

Operation Method and URI

Retrieve the user mapping rules. GET <cluster-ip:port>/platform/12/auth/
mapping/users/rules

Replace all user mapping rules. PUT <cluster-ip:port>/platform/12/auth/

mapping/users/rules

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. mapping/users/rules?describe

Authentication mapping users lookup resource

Retrieve the access token for any authenticated user.

Operation Method and URI

Look up a user through the usermapper. GET <cluster-ip:port>/platform/12/auth/
mapping/users/lookup

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. mapping/users/lookup?describe

Authentication providers summary resource

Retrieve a summary of all the authentication providers that are configured on the cluster.

Operation Method and URI

Retrieve a summary of authentication providers. GET <cluster-ip:port>/platform/12/auth/

providers/summary

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. providers/summary?describe

Authentication Kerberos providers resource

Create, modify, delete, or retrieve information about Kerberos authentication providers.

Operation Method and URI

Retrieve all Kerberos providers. GET <cluster-ip:port>/platform/12/auth/
providers/krb5

Retrieve a Kerberos provider. GET <cluster-ip:port>/platform/12/auth/

providers/krb5/<PROVIDER-ID>

Create a Kerberos provider. POST <cluster-ip:port>/platform/12/auth/

providers/krb5

32 System configuration API

Operation Method and URI
Modify a Kerberos provider. PUT <cluster-ip:port>/platform/12/auth/
providers/krb5/<PROVIDER-ID>

Delete a Kerberos provider. DELETE <cluster-ip:port>/platform/12/auth/

providers/krb5/<PROVIDER-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. providers/krb5?describe
GET <cluster-ip:port>/platform/12/auth/
providers/krb5/<PROVIDER-ID>?describe

Authentication settings krb5 defaults resource

Retrieve or modify default Kerberos authentication settings.

Operation Method and URI

Retrieve the default Kerberos authentication settings. GET <cluster-ip:port>/platform/12/auth/
settings/krb5/default

Modify the default Kerberos authentication settings. PUT <cluster-ip:port>/platform/12/auth/

settings/krb5/default

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. settings/krb5/default?describe

Authentication settings krb5 realms resource

Create, modify, delete, or retrieve information about a Kerberos authentication realm.

Operation Method and URI

Retrieve Kerberos authentication settings for realm. GET <cluster-ip:port>/platform/12/auth/
settings/krb5/realms

Retrieve Kerberos authentication settings for a specific realm. GET <cluster-ip:port>/platform/12/auth/

settings/krb5/realms/<realm name or ID>

Create a Kerberos authentication realm. POST <cluster-ip:port>/platform/12/auth/

settings/krb5/realms

Modify Kerberos authentication realm settings. PUT <cluster-ip:port>/platform/12/auth/

settings/krb5/realms/<realm name or ID>

Delete a Kerberos authentication realm. DELETE <cluster-ip:port>/platform/12/auth/

settings/krb5/realms/<realm name or ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. settings/krb5/realms?describe
GET <cluster-ip:port>/platform/12/auth/
settings/krb5/realms/<realm name or ID>?
describe

Authentication settings krb5 domains resource

Create, modify, delete, or retrieve information about a Kerberos authentication domain.

Operation Method and URI

Retrieve Kerberos authentication settings for domains. GET <cluster-ip:port>/platform/12/auth/
settings/krb5/domains

System configuration API 33

Operation Method and URI
Retrieve Kerberos authentication settings for a specific GET <cluster-ip:port>/platform/12/auth/
domain. settings/krb5/domains/<domain name or ID>

Create a Kerberos authentication domain. POST <cluster-ip:port>/platform/12/auth/

settings/krb5/domains

Modify Kerberos authentication domain settings. PUT <cluster-ip:port>/platform/12/auth/

settings/krb5/domains/<domain name or ID>

Delete a Kerberos authentication domain. DELETE <cluster-ip:port>/platform/12/auth/

settings/krb5/domains/<domain name or ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. settings/krb5/domains?describe
GET <cluster-ip:port>/platform/12/auth/
settings/krb5/domains/<domain name or ID>?
describe

LDAP provider template resources

Retrieve a list of all LDAP provider templates.

Operation Method and URI

Retrieve a list of all LDAP provider templates. GET <cluster-ip:port>/platform/12/auth/ldap-
templates

Retrieve a specific LDAP provider template. GET <cluster-ip:port>/platform/12/auth/ldap-

templates/<USERID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/ldap-
information about query parameters and object properties. templates?describe

Authentication ADS providers domains resource

Retrieve information about the trusted domains of configured ADS providers.

Operation Method and URI

List all trusted domains of ADS providers. GET <cluster-ip:port>/platform/12/auth/
providers/ads/<ID>/domains

View the trusted domains of a single ADS provider. GET <cluster-ip:port>/platform/12/auth/

providers/ads/<ID>/domains/<ADS-DOMAIN>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. providers/ads/<ID>/domains?describe
GET <cluster-ip:port>/
platform/12/auth/providers/ads/<ID>/domains/
<ADS-DOMAIN>?describe

Authentication ADS providers resource

View, modify, create, or delete ADS providers.

Operation Method and URI

List all ADS providers. GET <cluster-ip:port>/platform/12/auth/
providers/ads

34 System configuration API

Operation Method and URI
View an ADS provider. GET <cluster-ip:port>/platform/12/auth/
providers/ads/<PROVIDER-ID>

Create an ADS provider. POST <cluster-ip:port>/platform/12/auth/

providers/ads

Modify an ADS provider. PUT <cluster-ip:port>/platform/12/auth/

providers/ads/<PROVIDER-ID>

Delete an ADS provider. DELETE <cluster-ip:port>/platform/12/auth/

providers/ads/<PROVIDER-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. providers/ads?describe
GET <cluster-ip:port>/platform/12/auth/
providers/ads/<PROVIDER-ID>?describe

Authentication ADS providers controllers resource

Retrieve information about all the domain controllers for a trusted ADS domain.

Operation Method and URI

Get all domain controllers for a trusted ADS domain. GET <cluster-ip:port>/platform/12/auth/
providers/ads/<domain-id>/controllers

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/
information about query parameters and object properties. platform/12/auth/providers/ads/<domain-id>/
controllers?describe

Authentication ADS providers search resource

Perform searches within Active Directory service (ADS) providers for users, groups, and system accounts.

Operation Method and URI

Get objects that are searchable in domains. GET <cluster-ip:port>/platform/12/auth/
providers/ads/<OBJECT>/search

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. providers/ads/<OBJECT>/search?describe

Authentication Duo provider resource

View or modify the Duo provider settings.

Operation Method and URI

View a Duo provider. GET <cluster-ip:port>/platform/12/auth/
providers/duo

Modify a Duo provider. PUT <cluster-ip:port>/platform/12/auth/

providers/duo

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. providers/duo?describe

System configuration API 35

Authentication file providers resource
Create, modify, delete, or retrieve information about an authentication file provider.

Operation Method and URI

Retrieve all file providers. GET <cluster-ip:port>/platform/12/auth/
providers/file

Retrieve one file provider. GET <cluster-ip:port>/platform/12/auth/

providers/file/<provider-id>

Create a file provider. POST <cluster-ip:port>/platform/12/auth/

providers/file

Modify a file provider. PUT <cluster-ip:port>/platform/12/auth/

providers/file/<provider-id>

Delete a file provider. DELETE <cluster-ip:port>/platform/12/auth/

providers/file/<provider-id>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. providers/file?describe

Authentication LDAP providers resource

Create, modify, delete, or retrieve information about a Lightweight Directory Access Protocol (LDAP) provider.

Operation Method and URI

Retrieve all LDAP providers. GET <cluster-ip:port>/platform/12/auth/
providers/ldap

Retrieve one LDAP provider. GET <cluster-ip:port>/platform/12/auth/

providers/ldap/<PROVIDER-ID>

Create an LDAP provider. POST <cluster-ip:port>/platform/12/auth/

providers/ldap

Modify an LDAP provider. PUT <cluster-ip:port>/platform/12/auth/

providers/ldap/<PROVIDER-ID>

Delete an LDAP provider. DELETE <cluster-ip:port>/platform/12/auth/

providers/ldap/<PROVIDER-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. providers/ldap?describe
GET <cluster-ip:port>/platform/12/auth/
providers/ldap/<PROVIDER-ID>?describe

Authentication local providers resource

Create, modify, delete, or retrieve information about a local authentication provider.

Operation Method and URI

Retrieve all local providers. GET <cluster-ip:port>/platform/12/auth/
providers/local

Retrieve one local provider. GET <cluster-ip:port>/platform/12/auth/

providers/local/<PROVIDER-ID>

Create a local provider. POST <cluster-ip:port>/platform/12/auth/

providers/local

36 System configuration API

 Operation Method and URI
Modify a local provider. PUT <cluster-ip:port>/platform/12/auth/
providers/local/<PROVIDER-ID>

Delete a local provider. DELETE <cluster-ip:port>/platform/12/auth/

providers/local/<PROVIDER-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. providers/local?describe
GET <cluster-ip:port>/platform/12/auth/
providers/local/<PROVIDER-ID>?describe

Authentication NIS providers resource

Create, modify, delete, or retrieve information about a Network Information Service (NIS) authentication provider.

Operation Method and URI

Retrieve all NIS providers. GET <cluster-ip:port>/platform/12/auth/
providers/nis

Retrieve one NIS provider. GET <cluster-ip:port>/platform/12/auth/

providers/nis/<PROVIDER-ID>

Create an NIS provider. POST <cluster-ip:port>/platform/12/auth/

providers/nis

Modify an NIS provider. PUT <cluster-ip:port>/platform/12/auth/

providers/nis/<PROVIDER-ID>

Delete an NIS provider. DELETE <cluster-ip:port>/platform/12/auth/

providers/nis/<PROVIDER-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. providers/nis?describe
GET <cluster-ip:port>/platform/12/auth/
providers/nis/<PROVIDER-ID>?describe

Authentication settings ACL resource

View or modify ACL policy settings and preset configurations.

Operation Method and URI

List ACL policy settings. GET <cluster-ip:port>/platform/12/auth/
settings/acls

Modify ACL policy settings. PUT <cluster-ip:port>/platform/12/auth/

settings/acls

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. settings/acls?describe

Authentication privileges resource

List all privileges.

Operation Method and URI

List authentication privileges. GET <cluster-ip:port>/platform/12/auth/
privileges

System configuration API 37

Operation Method and URI
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. privileges?describe

Authentication roles resource

Create, modify, delete, or retrieve information about roles that are assigned to authenticated users.

Operation Method and URI

Get all roles. GET <cluster-ip:port>/platform/12/auth/roles

Get one role. GET <cluster-ip:port>/platform/12/auth/

roles/<ROLE-ID>

Create a role. POST <cluster-ip:port>/platform/12/auth/

roles

Modify a role. PUT <cluster-ip:port>/platform/12/auth/

roles/<ROLE-ID>

Delete a role. DELETE <cluster-ip:port>/platform/12/auth/

roles/<ROLE-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. roles?describe

Authentication roles members resource

Add, modify, remove, or retrieve information about the members that are assigned to a role.

Operation Method and URI

Retrieve the members of a role. GET <cluster-ip:port>/platform/12/auth/
roles/<ROLE>/members

Add a member to a role. POST <cluster-ip:port>/platform/12/auth/

roles/<ROLE-ID>/members

Remove a member from a role. DELETE <cluster-ip:port>/platform/12/auth/

roles/<ROLE-ID>/members/<persona-id>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. roles/<ROLE-ID>/members?describe

Authentication roles privileges resource

Add, modify, remove, or retrieve information about the privileges that are assigned to a role.

Operation Method and URI

Retrieve the privileges of a role. GET <cluster-ip:port>/platform/12/auth/
roles/<ID>/privileges

Add a privilege to a role. POST <cluster-ip:port>/platform/12/auth/

roles/<ID>/privileges

Remove a privilege from a role. DELETE <cluster-ip:port>/platform/12/auth/

roles/<ID>/privileges/<PRIVILEGE-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. roles/<ID>/privileges?describe

38 System configuration API

Authentication global settings resource
Retrieve or modify the global authentication settings on the cluster.

Operation Method and URI

Retrieve global settings. GET <cluster-ip:port>/platform/12/auth/
settings/global

Modify global settings. PUT <cluster-ip:port>/platform/12/auth/

settings/global

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. settings/global?describe

Authentication shells resource

Retrieve a list of user shells that are supported on the cluster.

Operation Method and URI

Retrieve a list of user shells that are supported on the cluster. GET <cluster-ip:port>/platform/12/auth/
shells

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. shells?describe

Authentication well-known resource

Retrieve well-known personas from the cluster.

Operation Method and URI

Retrieve all well-known personas. GET <cluster-ip:port>/platform/12/auth/
wellknowns

Retrieve a well-known persona. GET <cluster-ip:port>/platform/12/auth/

wellknowns/<WELLKNOWN>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. wellknowns?describe

Configured TLS certificate authority resource

View, import, modify, or delete one or more TLS certificate authorities.

Operation Method and URI

Retrieve a list of all configured TLS certificate authorities. GET <cluster-ip:port>/platform/12/
certificate/authority

Retrieve a single configured TLS certificate authority. GET <cluster-ip:port>/platform/12/

certificate/authority/<AUTHORITY-ID>

Modify a TLS certificate authority. PUT <cluster-ip:port>/platform/12/

certificate/authority/<AUTHORITY-ID>

Delete a TLS certificate authority. DELETE <cluster-ip:port>/platform/12/

certificate/authority/<AUTHORITY-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. certificate/authority?describe

System configuration API 39

Operation Method and URI
GET <cluster-
ip:port>/platform/12/certificate/authority/
<AUTHORITY-ID>?describe

Configured TLS server certificate resources

Retrieve a list of all configured TLS server certificates.

Operation Method and URI

Retrieve a list of all configured TLS server certificates. GET <cluster-ip:port>/platform/12/
certificate/server

Retrieve a single TLS server certificate. GET <cluster-ip:port>/platform/12/

certificate/server/<CERTIFICATE-ID>

Modify a TLS server certificate. PUT <cluster-ip:port>/platform/12/

certificate/server/<CERTIFICATE-ID>

Delete a TLS server certificate. DELETE <cluster-ip:port>/platform/12/

certificate/server/<CERTIFICATE-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. certificate/server?describe
GET <cluster-ip:port>/platform/12/
certificate/server/<CERTIFICATE-ID>?describe

Configured TLS certificate settings resource

Retrieve and modify system-wide TLS certificate settings.

Operation Method and URI

View a configured TLS certificate setting. GET <cluster-ip:port>/platform/12/
certificate/settings

Modify a configured TLS certificate setting. PUT <cluster-ip:port>/platform/12/

certificate/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. certificate/settings?describe

Authentication error resource

View authentication error details.

Operation Method and URI

View authentication error. GET <cluster-ip:port>/platform/12/auth/
error/<error-id>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/auth/
information about query parameters and object properties. error/<error-id>?describe

40 System configuration API

ID resolution resource
Retrieves Logical Inode Numbers (LIN) and their file path mappings.

Operation Method and URI

Resolve all LIN to file path mappings. GET <cluster-ip:port>/platform/12/id-
resolution/paths

Resolve a specific LIN to file path mapping. GET <cluster-ip:port>/platform/12/id-

resolution/paths/<LIN>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/id-
information about query parameters and object properties. resolution/paths?describe
GET <cluster-ip:port>/platform/12/id-
resolution/paths/<LIN>?describe

ID resolution domains resource

List domain to path mappings for one or more domains.

Operation Method and URI

List domain to path mappings. GET <cluster-ip:port>/platform/12/id-
resolution/domains

List a path mapping for a specific domain. GET <cluster-ip:port>/platform/12/id-

resolution/domains/<DOMAIN-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/id-
information about query parameters and object properties. resolution/domains/<DOMAIN-ID>?describe

ID resolution LIN resource

List LIN to path mappings.

Operation Method and URI

List LIN to path mappings. GET <cluster-ip:port>/platform/12/id-
resolution/lins

List a specific LIN to path mapping. GET <cluster-ip:port>/platform/12/id-

resolution/lins/<LIN-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/id-
information about query parameters and object properties. resolution/lins/<LIN-ID>?describe

ID resolution zones resource

List zone ID to zone name mappings.

Operation Method and URI

List zone ID to zone name mappings. GET <cluster-ip:port>/platform/12/id-
resolution/zones

List a specific zone ID to zone name mapping. GET <cluster-ip:port>/platform/12/id-

resolution/zones/<ZONE-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/id-
information about query parameters and object properties. resolution/zones/<ZONE-ID>?describe

System configuration API 41

ID resolution zone groups resource
List GIDs/GSIDs to group name mappings.

Operation Method and URI

List GID/GSID mappings for a zone to a group name. GET <cluster-ip:port>/platform/12/id-
resolution/zones/<ZONE-ID>/groups

List a specific GID/GSID mapping for a zone to a group. GET <cluster-ip:port>/platform/12/id-

resolution/zones/<ZONE-ID>/groups/<GROUP-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/id-
information about query parameters and object properties. resolution/zones/<ZONE-ID>/groups?describe

ID resolution zones users resource

List mappings between UIDs/SIDs and username.

Operation Method and URI

List mappings between UIDs/SIDs and username. GET <cluster-ip:port>/platform/12/id-
resolution/zones/<ZONE-ID>/users

List mappings between UIDs/SIDs and a specific username. GET <cluster-ip:port>/platform/12/id-

resolution/zones/<ZONE-ID>/users/<USER-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/id-
information about query parameters and object properties. resolution/zones/<ZONE-ID>/users?describe

Authentication API examples

You can see examples for some authentication API requests.

Change a user password

Change a user password.

Request example
Specify both the new and old password.

PUT /platform/12/auth/users/USER:johndoe/change_password
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"new_password":"ABC12345",
"old_password":"12345ABC"}

Response example

204 No Content
Content-type: text/plain

42 System configuration API

Create a local group
Create a local group.

Request example

POST /platform/12/auth/group
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name": "mygroup", “type”: “GROUP”}

Response example

201 Created
Content-type: application/json

{
"id" : "SID:S-1-5-21-4224731515-2571109568-2823010237-1003"
}

Modify a local group

Modify a local group.

Request example
Include the force parameter when modifying an authentication group.

PUT /platform/12/auth/groups/GROUP:mygroup?force=true
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"gid": 2004}

Response example

204 No Content
Content-type: text/plain

Add a member to a local group

Add a member to a local group.

Request example

POST /platform/12/auth/groups/GROUP:mygroup/members
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"id": "USER:user01"}

Response example

201 Created
Content-type: application/json

{"id" : "SID:S-1-5-21-4224731515-2571109568-2823010237-1003"}

System configuration API 43

Create a user
Create a user and add the user to a local group.

Request example
Create the user "user123" through the following request:

POST /platform/12/auth/users
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name": "user123", “type”: “USER”}

Response example

201 Created
Content-type: application/json

{
"id" : "SID:S-1-5-21-4224731515-2571109568-2823010237-1005"
}

Request example
Then, add "user123" to a group called "administrators" through the following request:

POST /platform/12/auth/groups/administrators/members
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name": "user123", “type”: “USER”}

Response example

201 Created
Content-type: application/json

{
"id" : "SID:S-7-6-25-4784731515-2575609568-2323010237-2005"
}

Modify a user
Modify the properties for a user.

Request example
In this example, an email address is added for the user.

PUT /platform/12/auth/users/USER:user123
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"email": "[email protected]"}

Response example

204 No Content
Content-type: application/json

44 System configuration API

Join a domain
Join an Active Directory server domain.

Request example

POST /platform/12/auth/providers/ads
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"server.company.com",
"user":"Administrator",
"password":"abc123"}

Response example

201 Created
Content-type: application/json

{
"id" : "SERVER.COMPANY.COM"
}

Modify an ADS provider

Modify an Active Directory authentication provider.

Request example

PUT /platform/12/auth/providers/ads/server1.company.com
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"home_directory_template":"/ifs/home/ads"}

Response example

204 No Content
Content-type: text/plain

Create an LDAP provider

Create an LDAP provider.

Request example

POST /platform/12/auth/providers/ldap
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"ldaptest",
"server_uris":["ldap://ldaptest.company.com"],
"base_dn":"dc=company,dc=com"}

Response example

201 Created
Content-type: application/json

{
"id" : "ldaptest"
}

System configuration API 45

Modify an LDAP provider
Modify an LDAP provider.

Request example

PUT /platform/12/auth/providers/ldap/ldaptest
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"ldaptest2",
"server_uris":["ldap://ldaptest.company.com"],
"base_dn":"dc=company,dc=com"}

Response example

204 No Content
Content-type: text/plain

Modify a local provider

Modify a local provider.

Request example

PUT /platform/12/auth/providers/local/zone1
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"home_directory_template" : "/ifs/home/%Z/%U"}

Response example

204 No Content
Content-type: text/plain

Create an authentication role

Create an authentication role.

Request example

POST /platform/12/auth/roles
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"dba"}

Response example

201 Created
Content-type: application/json

{
"id" : "dba"
}

46 System configuration API

Modify an authentication role
Modify an authentication role.

Request example

PUT /platform/12/auth/roles/dba
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"dba2"}

Response example

204 No Content
Content-type: text/plain

Modify global authentication settings

Modify global authentication settings.

Request example

PUT /platform/12/auth/settings/global
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"send_ntlmv2":"true"}

Response example

204 No Content
Content-type: text/plain

Create a krb5 realm

Create a krb5 authentication realm.

Request example

POST /platform/12/auth/settings/krb5/realms
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"realm":"test_realm"}

Response example

201 Created
Content-type: application/json

{"id" : "2024839292}

System configuration API 47

Create a krb5 domain
Create a krb5 authentication domain.

Request example

POST /platform/12/auth/settings/krb5/domains
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"domain":"test_domain",
"realm":"test_realm"
}

Response example

201 Created
Content-type: application/json

{
"id" : "29274939282"
}

Modify krb5 domains

Modify a krb5 authentication domain.

Request example

PUT /platform/12/auth/settings/krb5/domains/test_domain
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"domain":"test_domain2",
"realm":"test_realm4"
}

Response example

204 No Content
Content-type: application/json

Modify krb5 settings

Modify default krb5 authentication settings.

Request example

PUT /platform/12/auth/settings/krb5/defaults
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"dns_lookup_realm":"true"
"dns_lookup_kdc":"true"
}

48 System configuration API

Response example

204 No Content
Content-type: application/json

Auditing overview
You can audit system configuration changes and protocol activity on an PowerScale cluster. All audit data is stored and
protected in the cluster file system and organized by audit topics.
Auditing can detect many potential sources of data loss, including fraudulent activities, inappropriate entitlements, and
unauthorized access attempts. Customers in industries such as financial services, health care, life sciences, and media and
entertainment, as well as in governmental agencies, must meet stringent regulatory requirements developed to protect against
these sources of data loss.
System configuration auditing tracks and records all configuration events that are handled by the OneFS HTTP API. The process
involves auditing the command-line interface (CLI), web administration interface, and OneFS APIs. When you enable system
configuration auditing, no additional configuration is required. System configuration auditing events are stored in the config
audit topic directories.
Protocol auditing tracks and stores activity performed through SMB, NFS, and HDFS protocol connections. You can enable
and configure protocol auditing for one or more access zones in a cluster. If you enable protocol auditing for an access zone,
file-access events through the SMB, NFS, and HDFS protocols are recorded in the protocol audit topic directories. You can
specify which events to log in each access zone. For example, you might want to audit the default set of protocol events in
the System access zone but audit only successful attempts to delete files in a different access zone.
The audit events are logged on the individual nodes where the SMB, NFS, or HDFS client initiated the activity. The events are
then stored in a binary file under /ifs/.ifsvar/audit/logs. The logs automatically roll over to a new file after the size
reaches 1 GB. The logs are then compressed to reduce space.
The protocol audit log file is consumable by auditing applications that support the Common Event Enabler (CEE).

Audit resources
You can retrieve and modify OneFS audit topics and settings.

Audit settings resource

Modify or retrieve information about audit settings per access zone.

Operation Method and URI

Retrieve audit settings. GET <cluster-ip:port>/platform/12/audit/
settings

Modify audit settings. PUT <cluster-ip:port>/platform/12/audit/

settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/audit/
information about query parameters and object properties. settings?describe

Audit global settings resource

Modify or retrieve information about audit global settings.

Operation Method and URI

Retrieve audit global settings. GET <cluster-ip:port>/platform/12/audit/
settings/global

Modify audit global settings. PUT <cluster-ip:port>/platform/12/audit/

settings/global

System configuration API 49

Operation Method and URI
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/audit/
information about query parameters and object properties. settings/global?describe

Audit logs resource

Delete out-of-data audit logs, and retrieve the status of deleted logs.

Operation Method and URI

Retrieve status of audit log deletion. GET <cluster-ip:port>/platform/12/audit/logs

Delete audit logs. DELETE <cluster-ip:port>/platform/12/audit/

logs

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/audit/
information about query parameters and object properties. logs?describe

Audit topic resource

Modify or retrieve information about audit topics.

Operation Method and URI

Retrieve all audit topics. GET <cluster-ip:port>/platform/12/audit/
topics

Retrieve an audit topic. GET <cluster-ip:port>/platform/12/audit/

topics/<name>

Modify an audit topic. PUT <cluster-ip:port>/platform/12/audit/

topics/<name>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/audit/
information about query parameters and object properties. topics?describe

Audit progress resource

View the current audit log time.

Operation Method and URI

Retrieve the current audit log time by node. GET <cluster-ip:port>/platform/12/audit/
progress

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/audit/
information about query parameters and object properties. progress?describe

Audit progress global resource

View the global audit log time.

Operation Method and URI

Retrieve the current global audit log time. GET <cluster-ip:port>/platform/12/audit/
progress /global

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/audit/
information about query parameters and object properties. progress/global?describe

50 System configuration API

Audit API examples
You can see examples for some audit API calls.

Enable protocol auditing

You can enable SMB protocol auditing on the system for specified zones.

Request example
In the following example, protocol auditing is enabled for the "myZone" and "System" zones.

PUT /platform/12/audit/settings
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'audited_zones': ['myZone', 'System'],
'protocol_auditing_enabled': True
}

Response example
In the following example, the request was successful, and protocol auditing is enabled on the system for the specified zones. No
message body is returned for this request.

204 No Content
Content-type: text/plain,
Allow: 'GET, PUT, HEAD'

Enable configuration auditing

You can enable configuration auditing on the system.

Request example

PUT /platform/12/audit/settings
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'config_auditing_enabled': True
}

Response example
No message body is returned for this request.

204 No Content
Content-type: text/plain,
Allow: 'GET, PUT, HEAD'

Modify an audit topic

You can modify an audit topic on the system.

Request example

PUT /12/audit/topics/protocol
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

System configuration API 51

 {
"max_cached_messages": 1000
}

Response example
No message body is returned for this request.

204 No Content
Content-type: text/plain,
Allow: 'GET, PUT, HEAD'

Data Security overview

The default view of a PowerScale cluster is that of one physical machine. But you can partition a cluster into multiple virtual
containers called access zones. Access zones allow you to isolate data and control who can access data in each zone.
Access zones support configuration settings for authentication and identity management services on a cluster. Access zones
enable you to configure authentication providers and provision protocol directories such as SMB shares and NFS exports on a
zone-by-zone basis. Creating an access zone automatically creates a local provider, which allows you to configure each access
zone with a list of local users and groups. You can also authenticate through a different authentication provider in each access
zone.
To control data access, you associate the access zone with a groupnet. A groupnet is a top-level networking container that
manages DNS client connection settings and contains subnets and IP address pools. When you create an access zone, you
must specify a groupnet. If a groupnet is not specified, the access zone references the default groupnet. Multiple access zones
can reference a single groupnet. You can direct incoming connections to the access zone through a specific IP address pool in
the groupnet. Associating an access zone with an IP address pool restricts authentication to the associated access zone and
reduces the number of available and accessible SMB shares and NFS exports.
An advantage to multiple access zones is the ability to configure audit protocol access for individual access zones. You can
modify the default list of successful and failed protocol audit events and then generate reports through a third-party tool for an
individual access zone.
A cluster includes an access zone that is named System where you manage all aspects of a cluster and other access zones. By
default, all cluster IP addresses connect to the System zone. Role-based access, which primarily allows configuration actions,
is available through only the System zone. All administrators, including those given privileges by a role, must connect to the
System zone to configure a cluster. The System zone is automatically configured to reference the default groupnet on the
cluster, which is groupnet0.
Configuration management of a non-System access zone is not permitted through SSH, the OneFS API, or the web
administration interface. However, you can create and delete SMB shares in an access zone through the Microsoft Management
Console (MMC).

Access zone resources

Retrieve, create, modify, or delete access zone configurations and settings.

Access zones resource

Create, modify, delete, or retrieve information about the access zones on a cluster.

Operation Method and URI

Retrieve all access zones. GET <cluster-ip:port>/platform/12/zones

Retrieve one access zone. GET <cluster-ip:port>/platform/12/zones/

<ZONE-ID>

Create an access zone. POST <cluster-ip:port>/platform/12/zones

Modify an access zone. PUT <cluster-ip:port>/platform/12/zones/

<ZONE-ID>

52 System configuration API

Operation Method and URI
Delete an access zone. DELETE <cluster-ip:port>/platform/12/zones/
<ZONE-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/zones?
information about query parameters and object properties. describe
GET <cluster-ip:port>/platform/12/zones/
<ZONE-ID>?describe

Access zones summary resource

Retrieve summary information about the access zones on a cluster.

Operation Method and URI

Retrieve information about all access zones. GET <cluster-ip:port>/platform/12/zones-
summary

Retrieve nonprivileged information about a specific access GET <cluster-ip:port>/platform/12/zones-

zone. summary/<ZONE>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/zones-
information about query parameters and object properties. summary?describe
GET <cluster-ip:port>/platform/12/zones-
summary/<ZONE>?describe

Access zone API examples

You can see examples for some access zone API calls.

Create an access zone

Create an access zone on the cluster.

Request example

POST /platform/12/zones
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"MyZone", "path":"/ifs/data/myzone"}

Response example

201 Created
Content-type: application/json

{"id":"MyZone"}

System configuration API 53

Modify an access zone
Modify the properties for an access zone on the cluster.

Request example
In the following example, the name for ZoneA is changed to ZoneB.

PUT /platform/12/zones/ZoneA
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"ZoneB"}

Response example

204 No Content
Content-type: 'text/plain

NFS security
OneFS provides an NFS server so you can share files on your cluster with NFS clients that adhere to the RFC1813 (NFSv3) and
RFC3530 (NFSv4) specifications.
NFS is disabled by default. To enable NFS, use the following command:

isi services nfs enable

In OneFS, the NFS server is fully optimized as a multithreaded service running in user space instead of the kernel. This
architecture load balances the NFS service across all nodes of the cluster, providing the stability and scalability necessary to
manage up to thousands of connections across multiple NFS clients.
NFS mounts run and refresh quickly, and the server constantly monitors fluctuating demands on NFS services and makes
adjustments across all nodes to ensure continuous, reliable performance. Using an integrated process scheduler, OneFS helps
ensure fair allocation of node resources so that no client can seize more than its fair share of NFS services.
The NFS server also supports access zones that are defined in OneFS, so that clients can access only the exports appropriate
to their zone. For example, if NFS exports are specified for Zone 2, only clients that are assigned to Zone 2 can access these
exports.
To simplify client connections, especially for exports with large path names, the NFS server also supports aliases, which are
shortcuts to mount points that clients can specify directly.
For secure NFS file sharing, OneFS supports NIS and LDAP authentication providers.

NFS classes
NFS classes define values for the object properties in NFS resources.

<user-mapping>
The <user-mapping> class must be set as follows:

Property Type Description

enabled Boolean True if the user mapping is applied.
user <persona> Specifies the name of the privilege
primary_group <persona> Specifies persona properties for the primary user group. A
persona consists of either a type and name, or an ID.

54 System configuration API

Property Type Description
secondary_group Array of <persona> Specifies persona properties for the secondary user group.
A persona consists of either a type and name, or an ID.

<persona>
The <persona> class must be set with either the <persona-id> or the <type> and <name> parameters, as follows:

Property Type Description

id <persona-id> Specifies the serialized form of the persona
type String Specifies the type of persona, which must be combined
with a name. The type of the persona can be set to user,
group, or wellknown.

name String Specifies the persona name, which must be combined with
a type

<persona-id>
The <persona-id> class must be set in the following format: user:<string>, group:<string>, SID:<string>,
UID:<string>, GID:<string>, such as: GID:2003 or user:johndoe.

NFS resources
You can retrieve, create, modify, or delete NFS export configurations and settings.

NFS exports summary resource

Retrieve summary information for NFS exports.

Operations Method and URI

Retrieve the NFS exports summary. GET <cluster-ip:port>/platform/12/protocols/nfs/
exports-summary

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/nfs/
which has information about query parameters and exports-summary?describe
object properties.

NFS exports resource

Create, modify, delete, or retrieve information about NFS exports.

Operation Method and URI

Retrieve all NFS exports. GET <cluster-ip:port>/platform/12/protocols/nfs/
exports

Retrieve one NFS export. GET <cluster-ip:port>/platform/12/protocols/nfs/

exports/<EID>

Create an NFS export. POST <cluster-ip:port>/platform/12/protocols/nfs/

exports

Modify an NFS export. PUT <cluster-ip:port>/platform/12/protocols/nfs/

exports/<EID>

Delete an NFS export. DELETE <cluster-ip:port>/platform/12/protocols/nfs/

exports/<EID>

System configuration API 55

Operation Method and URI
View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/nfs/
which has information about query parameters exports?describe
and object properties.
GET <cluster-ip:port>/platform/12/protocols/nfs/
exports/<EID>?describe

NFS check resource

Retrieve NFS export validation information.

Operation Method and URI

Retrieve NFS export validation information. GET <cluster-ip:port>/platform/12/
protocols/nfs/check

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/nfs/check?describe

NFS aliases resource

Create, modify, delete, or retrieve information about NFS aliases. Aliases are names for physical paths in the file system. You are
retrieving, deleting, or modifying aliases with forward slashes "/" in their names, and you must substitute the URI encoding. For
example, if the alias name is /username, you must substitute %2fusername in the call.

Operation Method and URI

Retrieve all NFS aliases. GET <cluster-ip:port>/platform/12/
protocols/nfs/aliases

Retrieve an NFS alias. GET <cluster-ip:port>/platform/12/

protocols/nfs/aliases/<AID>

Create an NFS alias. POST <cluster-ip:port>/platform/12/

protocols/nfs/aliases

Modify an NFS alias. PUT <cluster-ip:port>/platform/12/

protocols/nfs/aliases/<AID>

Delete an NFS alias. DELETE <cluster-ip:port>/platform/12/

protocols/nfs/aliases/<AID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/nfs/aliases?describe
GET <cluster-ip:port>/platform/12/
protocols/nfs/aliases/<AID>?describe

NFS NLM locks resource

Retrieve information about NFS Network Lock Manager (NLM) advisory locks.

Operation Method and URI

Get a list of NFS advisory locks. GET <cluster-ip:port>/platform/12/protocols/nfs/nlm/
locks

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/protocols/nfs/nlm/

resource, which has information about query locks?describe
parameters and object properties.

56 System configuration API

NFS NLM lock waiters resource
Retrieve information about NFS Network Lock Manager (NLM) lock waiters.

Operation Method and URI

Get a list of NLM lock waiters on NFS. GET <cluster-ip:port>/platform/12/protocols/nfs/nlm/
waiters

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/nfs/nlm/
which has information about query parameters and waiters?describe
object properties.

NFS NLM sessions resource

Delete or retrieve information about NFS Network Lock Manager (NLM) sessions.

Operation Method and URI

Retrieve all NFS NLM sessions. GET <cluster-ip:port>/platform/12/protocols/nfs/nlm/
sessions

Retrieve all lock states for a specific NFS GET <cluster-ip:port>/platform/12/protocols/nfs/nlm/

NLM session. sessions/<ID>

Delete all lock states for a specific NFS NLM DELETE <cluster-ip:port>/platform/12/protocols/nfs/nlm/
session. sessions/<ID>

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/protocols/nfs/nlm/

resource, which has information about query sessions?describe
parameters and object properties.
GET <cluster-ip:port>/platform/12/protocols/nfs/nlm/
sessions/<ID>?describe

NFS NLM sessions check resource

Perform an active scan for lost NFSv3 locks.

Operation Method and URI

Scan for lost NFSv3 locks. POST <cluster-ip:port>/platform/12/protocols/nfs/nlm/
sessions-check

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/protocols/nfs/nlm/

resource, which has information about query sessions-check?describe
parameters and object properties.

NFS log level resource

Retrieve or set the current NFS logging level.

Operation Method and URI

Retrieve the current NFS logging level. GET <cluster-ip:port>/platform/12/
protocols/nfs/log-level

Set the NFS logging level. PUT <cluster-ip:port>/platform/12/

protocols/nfs/log-level

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/nfs/log-level?describe

System configuration API 57

NFS netgroup resource
Get or modify the current NFS netgroup cache settings.

Operation Method and URI

Retrieve the current NFS netgroup cache settings. GET <cluster-ip:port>/platform/12/
protocols/nfs/netgroup

Modify the current NFS netgroup cache settings. PUT <cluster-ip:port>/platform/12/

protocols/nfs/netgroup

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/nfs/netgroup?describe

NFS netgroup check resource

Update the NFS netgroups in the cache.

Operation Method and URI

Update the NFS netgroups. POST <cluster-ip:port>/platform/12/
protocols/nfs/netgroup/check

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/nfs/netgroup/check?describe

NFS netgroup flush resource

Flush the NFS netgroups in the cache.

Operation Method and URI

Flush the NFS netgroups. POST <cluster-ip:port>/platform/12/
protocols/nfs/netgroup/flush

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/nfs/netgroup/flush?describe

NFS default export settings resource

Modify or retrieve information about the default NFS export settings.

Operation Method and URI

Get default NFS export settings. GET <cluster-ip:port>/platform/12/protocols/nfs/
settings/export

Modify default NFS export settings. PUT <cluster-ip:port>/platform/12/protocols/nfs/

settings/export

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/nfs/
which has information about query parameters settings/export?describe
and object properties.

58 System configuration API

NFS global settings resource
Retrieve or modify global configuration settings for NFS exports.

Operation Method and URI

Get default NFS export settings. GET <cluster-ip:port>/platform/12/protocols/nfs/settings/
global

Modify default NFS export settings. PUT <cluster-ip:port>/platform/12/protocols/nfs/settings/

global

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/protocols/nfs/settings/

resource, which has information about global?describe
query parameters and object properties.

NFS exports configuration check resource

Retrieve information about the status and validity of current NFS exports. Each export with an error is reported along with the
first error that is encountered during the check.

Operation Method and URI

Check NFS exports for configuration errors. GET <cluster-ip:port>/platform/12/protocols/nfs/
check

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/nfs/
which has information about query parameters and check?describe
object properties.

NFS zone settings resource

Retrieve or modify zone configuration settings for NFS exports.

Operation Method and URI

Retrieve NFS server settings for a zone. GET <cluster-ip:port>/platform/12/protocols/nfs/settings/
zone

Modify NFS server settings for a zone. PUT <cluster-ip:port>/platform/12/protocols/nfs/settings/

zone

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/protocols/nfs/settings/

resource, which has information about zone?describe
query parameters and object properties.

NFS reload resource

Reload cached export information. If the time to live (TTL) has expired, the netgroup cache is updated against the remote
provider and hosts are updated against the DNS. Netgroups are automatically refreshed on an interval that is specified by the
netgroup expiration option. DNS hosts are intermittently refreshed. Local export information, such as options that are specified
with exports create or exports modify, is updated immediately following the action.

Operation Method and URI

Reload NFS exports. POST <cluster-ip:port>/platform/12/
protocols/nfs/reload

View the detailed JSON schema for this resource, which GET <cluster-ip:port>/platform/12/
has information about query parameters and object protocols/nfs/reload?describe
properties.

System configuration API 59

NFS API examples
You can see examples for some NFS API requests.

Create NFS alias

Create an NFS alias.

Request example

POST /platform/12/protocols/nfs/aliases
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"name":"nfs_alias_01",
"path":"/ifs/nfs/aliases"
}

Response example

201 Created
Content-type: application/json

{
"id":"204"
}

Modify NFS alias

Modify an NFS alias.

Request example

PUT /platform/12/protocols/nfs/aliases/204
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"nfs_alias_02"}

Response example

204 No Content
Content-type: text/plain

Create NFS export

Create an NFS export.

Request example

POST /platform/12/protocols/nfs/exports
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"paths":[
"/ifs/nfs/exports/test",
"/ifs/nfs/exports/test2"
]
}

60 System configuration API

Response example

201 Created
Content-type: application/json

{
"id":24
}

Modify NFS export

Modify an NFS export.

Request example

PUT /platform/12/protocols/nfs/exports/24
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"write_transfer_max_size":1024,
"write_transfer_multiple":512
}

Response example

204 No Content
Content-type: text/plain

Modify default NFS settings

Modify the default NFS settings on the cluster.

Request example

PUT /platform/12/protocols/nfs/settings/export
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"block_size":512,
"can_set_time":true,
"case_insensitive":false
}

Response example

204 No Content
Content-type: text/plain

Modify global NFS settings

Modify the global NFS settings on the cluster.

Request example

PUT /platform/12/protocols/nfs/settings/global
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

System configuration API 61

 "nfsv3_enabled":true
}

Response example

204 No Content
Content-type: text/plain

Modify NFS zone settings

Modify the settings for an NFS access zone.

Request example

PUT /platform/12/protocols/nfs/settings/zone
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"nfsv4_allow_numeric_ids":true,
"nfsv4_domain":"test_domain"
}

Response example

204 No Content
Content-type: text/plain

SMB
OneFS includes a configurable SMB service to create and manage SMB shares. SMB shares provide Windows clients network
access to file system resources on the cluster. You can grant permissions to users and groups to carry out operations such as
reading, writing, and setting access permissions on SMB shares.
SMB shares act as checkpoints, and users must have access to a share in order to access objects in a file system on a share.
If the user security mode is enabled, users who connect to a share from an SMB client must provide a valid username with
proper credentials. If a user has access that is granted to a file system, but not to the share on which it resides, that user
cannot access the file system regardless of privileges. For example, assume a share that is named ABCDocs contains a file that
is named file1.txt in a path such as: /ifs/data/ABCDocs/file1.txt. If a user attempting to access file1.txt does
not have share privileges on ABCDocs, that user cannot access the file even if originally granted read and/or write privileges to
the file.
The SMB protocol uses security identifiers (SIDs) for authorization data. All identities are converted to SIDs during retrieval and
are converted back to their on-disk representation before they are stored on the cluster.
When a file or directory is created, OneFS checks the access control list (ACL) of its parent directory. If the ACL contains any
inheritable access control entries (ACEs), a new ACL is generated from those ACEs. Otherwise, OneFS creates an ACL from the
combined file and directory create mask and create mode settings.

Supported clients
The table lists the clients that are supported by OneFS.
OneFS supports the following clients. Clients running Operating System X can connect to a Isilon cluster using the NFS or SMB
protocol.

Supported Clients
Any NFS client that complies with NFSv3 or NFSv4.0 client implementations compliant with RFC1813 and RFC3530
respectively.

62 System configuration API

Supported Clients
Implementations of SMB1 provided in Microsoft Windows operating systems, and SMB2/3 systems compliant with the Open
Specifications document MS-SMB2.

EMC Isilon tests SMB clients that are covered under Extended Support Policy of Microsoft and the following:
● Operating system X 10.9
● Operating system X 10.10
● Operating system X 10.11

MacOS X
Clients running MacOS X can connect to a Isilon cluster using the NFS or SMB protocol. To take advantage of Apple-specific
SMB2 features such as color tagging, enable the Apple extensions for SMB2.

SMB resources
You can retrieve, create, modify, or delete SMB share configurations and settings.

SMB shares summary resource

Retrieve summary information for SMB shares.

Operation Method and URI

Retrieve the SMB shares summary GET <cluster-ip:port>/platform/12/protocols/smb/shares-
summary
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/smb/shares-
information about query parameters and object properties. summary?describe

SMB shares resource

Modify, delete, and create SMB shares; and retrieve information about SMB shares.
When creating a share, specify the ID of the access zone where the share is to be created. The zone specification is in the URI,
for example:

POST <cluster-ip:port>/platform/12/protocols/smb/shares?zid=2

Specify the share name, path, and other properties in the JSON body of the request.

Operation Method and URI

Retrieve a single SMB share. GET <cluster-ip:port>/platform/12/
protocols/smb/shares/<SHARE>

Retrieve a list of SMB shares. GET <cluster-ip:port>/platform/12/

protocols/smb/shares

Create an SMB share. POST <cluster-ip:port>/platform/12/

protocols/smb/shares/<ZONE-ID>

Modify an SMB share. PUT <cluster-ip:port>/platform/12/

protocols/smb/shares/<SHARE>

Delete an SMB share. DELETE <cluster-ip:port>/platform/12/

protocols/smb/shares/<SHARE>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/smb/shares?describe
GET <cluster-ip:port>/platform/12/
protocols/smb/shares/<SHARE>?describe

System configuration API 63

SMB share settings resource
Modify or retrieve information about default SMB share settings.

Operation Method and URI

Retrieve SMB share settings. GET <cluster-ip:port>/platform/12/
protocols/smb/settings/share

Modify SMB share settings. PUT <cluster-ip:port>/platform/12/

protocols/smb/settings/share

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/smb/settings/share?describe

SMB global settings resource

Modify or retrieve information about global SMB share settings.

Operation Method and URI

Retrieve the global SMB settings. GET <cluster-ip:port>/platform/12/
protocols/smb/settings/global

Modify the global SMB settings. PUT <cluster-ip:port>/platform/12/

protocols/smb/settings/global

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/smb/settings/global?describe

SMB open files resource

Retrieve a listing of all files that are open through SMB on the queried node or close an open file.

Operation Method and URI

Retrieve a list of files opened through SMB. GET <cluster-ip:port>/platform/12/
protocols/smb/openfiles

Close a file opened through SMB. DELETE <cluster-ip:port>/platform/12/

protocols/smb/openfiles/<FILE-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/smb/openfiles?describe
GET <cluster-ip:port>/platform/12/
protocols/smb/openfiles/<FILE-ID>?describe

SMB sessions resource

Close or retrieve a listing of all SMB user sessions that are open on the queried node.

Operation Method and URI

Retrieve a list of SMB sessions. GET <cluster-ip:port>/platform/12/
protocols/smb/sessions

Close an SMB session user. DELETE <cluster-ip:port>/platform/12/

protocols/smb/sessions/<COMPUTER>/<USER>

Close an SMB session system. DELETE <cluster-ip:port>/platform/12/

protocols/smb/sessions/<COMPUTER>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/smb/sessions?describe

64 System configuration API

Operation Method and URI
GET <cluster-
ip:port>/platform/12/protocols/smb/sessions/
<COMPUTER>/<USER>?describe
GET <cluster-ip:port>/platform/12/
protocols/smb/sessions/<COMPUTER>?describe

NOTE: The node-lnn is optional for /protocols/smb/sessions . With this parameter, the output lists the
connected client's information of interested node. When the parameter is missing, it is assumed as local node.

SMB log level resource

List or modify the SMB logging level.

Operation Method and URI

Retrieve the SMB logging level. GET <cluster-ip:port>/platform/12/
protocols/smb/log-level

Modify the SMB logging level. PUT <cluster-ip:port>/platform/12/

protocols/smb/log-level

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/smb/log-level?describe

SMB log level filters resource

Retrieve, add, or delete SMB logging level filter information.

Operation Method and URI

View all SMB log filters. GET <cluster-ip:port>/platform/12/protocols/smb/log-
level/filters

View a specific SMB log filter. GET <cluster-ip:port>/platform/12/protocols/smb/log-

level/filters/<ID>

Add an SMB log filter. POST <cluster-ip:port>/platform/12/protocols/smb/log-

level/filters

Delete existing SMB log filters. DELETE <cluster-ip:port>/platform/12/protocols/smb/log-

level/filters

Delete a specific SMB log filter. DELETE <cluster-ip:port>/platform/12/protocols/smb/log-

level/filters/<ID>

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/protocols/smb/log-

resource, which has information about query level/filters?describe
parameters and object properties.
GET <cluster-ip:port>/platform/12/protocols/smb/log-
level/filters/<ID>?describe

SMB zone settings resource

Modify or retrieve information about SMB share settings on a per-zone basis.

Operation Method and URI

Retrieve the SMB settings for an access zone. GET <cluster-ip:port>/platform/12/
protocols/smb/settings/zone

Modify the SMB settings for an access zone. PUT <cluster-ip:port>/platform/12/

protocols/smb/settings/zone

System configuration API 65

Operation Method and URI
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/smb/settings/zone?describe

SMB API example

You can see an example of creating an SMB share.

Create an SMB share

When creating an SMB share, obtain and specify the access zone that contains the share in the URI.

Request to obtain the access zone ID

POST /platform/12/zones
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Response

{
"zones": [
{
"alternate_system_provider": "lsa-file-provider:System",
"auth_providers": [
"lsa-local-provider:System",
"lsa-file-provider:System"
],
"cache_entry_expiry": 14400,
"groupnet": "groupnet0",
"home_directory_umask": 63,
"id": "System",
"ifs_restricted": [],
"map_untrusted": "",
"name": "System",
"negative_cache_entry_expiry": 60,
"netbios_name": "",
"path": "/ifs",
"skeleton_directory": "/usr/share/skel",
"system": true,
"system_provider": "lsa-file-provider:System",
"user_mapping_rules": [],
"zone_id": 1
},
{
"alternate_system_provider": "lsa-file-provider:MinimumRequired",
"auth_providers": [
"lsa-local-provider:home-admin"
],
"cache_entry_expiry": 14400,
"groupnet": "groupnet0",
"home_directory_umask": 63,
"id": "home-admin",
"ifs_restricted": [],
"map_untrusted": "",
"name": "home-admin",
"negative_cache_entry_expiry": 60,
"netbios_name": "",
"path": "/ifs/home/admin",
"skeleton_directory": "/usr/share/skel",
"system": false,
"system_provider": "lsa-file-provider:System",
"user_mapping_rules": [],
"zone_id": 2
}

66 System configuration API

 ]
}

Request to create share

POST /platform/12/protocols/smb/shares?zid=2
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"MyShare", "path":"/ifs/home/admin/share"}

Response

201 Created
Content-type: application/json

{"id": "MyShare"}

S3
OneFS supports the Simple Storage Service (S3) protocol for reading data from and writing data to the PowerScale platform.
The OneFS API for the S3 protocol supplements the S3 API.
The S3 objects map to the PowerScale file system as follows:
● Bucket = base directory
● Object prefix = directory path within bucket
● Object = file
The S3 object key maps directly to a file system path.
The S3 protocol supports bucket and object creation, retrieving, updating, and deletion. Object retrievals and updates are
atomic. Bucket properties can be updated.
Objects are accessible using NFS and SMB as normal files, providing cross-protocol support. The S3 access control lists (ACLs)
translate into SMB ACLs as follows:
● The S3 Predefined group AllUsers translates to SMB well known 'Everyone'.
● The S3 Predefined group AllAuthenticatedUsers translates to SMB well-known 'Authenticated Users'.
● An S3 request without a signature is treated as if they were the user 'nobody'.
Administrators generate access IDs and secret keys for authenticated users for access to use S3. Secret keys expire, and when
an administrator generates a new secret key, the old key validity overlaps briefly with the new key validity.
See the Amazon Simple Storage Service documentation for more information.

S3 resources
You can retrieve, create, modify, or delete S3 configurations and settings.

S3 buckets resource
Retrieve a list of buckets and retrieve, create, modify, and delete a bucket. When creating a bucket, AWS S3 restrictions apply.

Operation Method and URI

Retrieve a list of buckets. GET <cluster-ip:port>/platform/12/
protocols/s3/buckets

Retrieve a bucket. GET <cluster-ip:port>/platform/12/

protocols/s3/buckets/<BUCKET>

Create a bucket. POST <cluster-ip:port>/platform/12/

protocols/s3/buckets

System configuration API 67

Operation Method and URI
Modify a bucket. PUT <cluster-ip:port>/platform/12/
protocols/s3/buckets/<BUCKET>

Delete a bucket. DELETE <cluster-ip:port>/platform/12/

protocols/s3/buckets/<BUCKET>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/s3/buckets?describe
GET <cluster-ip:port>/platform/12/
protocols/s3/buckets/<BUCKET>?describe

S3 keys user resource

Retrieve, create, or delete a user secret key.

Operation Method and URI

Retrieve a user key. GET <cluster-ip:port>/platform/12/
protocols/s3/keys/<USER>

Create a user key. POST <cluster-ip:port>/platform/12/

protocols/s3/keys/<USER>

Delete a user key. DELETE <cluster-ip:port>/platform/12/

protocols/s3/keys/<USER>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/s3/keys/<USER>?describe

S3 log level resource

Retrieve and set the S3 log level.

Operation Method and URI

Retrieve the log level. GET <cluster-ip:port>/platform/12/
protocols/s3/log-level

Set the log level. PUT <cluster-ip:port>/platform/12/

protocols/s3/log-level

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/s3/log-level?describe

S3 mykeys resource
Retrieve, generate, and delete the secret key information of the current requestor.

Operation Method and URI

Retrieve user secret key information. GET <cluster-ip:port>/platform/12/
protocols/s3/mykeys

Generate user secret key information. POST <cluster-ip:port>/platform/12/

protocols/s3/mykeys

Delete user secret key information. DELETE <cluster-ip:port>/platform/12/

protocols/s3/mykeys

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/s3/mykeys?describe

68 System configuration API

S3 settings global resource
Retrieve and modify global S3 bucket configuration.

Operation Method and URI

Retrieve the global S3 configuration. GET <cluster-ip:port>/platform/12/
protocols/s3/settings/global

Set the global S3 configuration. PUT <cluster-ip:port>/platform/12/

protocols/s3/settings/global

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/s3/settings/global?describe

S3 settings zone resource

Retrieve and modify S3 zone configuration.

Operation Method and URI

Retrieve the zone S3 configuration. GET <cluster-ip:port>/platform/12/
protocols/s3/settings/zone

Set the zone S3 configuration. PUT <cluster-ip:port>/platform/12/

protocols/s3/settings/zone

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/s3/settings/zone?describe

S3 API examples
Code samples for using S3 protocol with OneFS.

Generate a key
Create a key for S3 object access.

Request example

POST /platform/12/protocols/s3/keys/admin
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Response example

{
"keys" :
{
"access_id" : "1_admin_accid",
"old_key_expiry" : 1584753428,
"old_key_timestamp" : 1584742174,
"old_secret_key" : "jegc8mY7vI93SGBiLDdsnRYqGdCB",
"secret_key" : "E3DyE_-aQtMrhGPqPZ22AczK_z6j",
"secret_key_timestamp" : 1584752828
}
}

System configuration API 69

Retrieve a bucket
Retrieve an S3 bucket.

Request example

GET /platform/12/protocols/s3/buckets/mybucket
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Response example

{
"buckets" :
[

{
"acl" : [],
"bucketid" : 844424930230273,
"clients" : [],
"creationtime" : "2020-03-19T21:28:31.000Z",
"description" : "Objects for user12",
"id" : "mybucket",
"name" : "mybucket",
"object_acl_policy" : "replace",
"owner" : "admin",
"path" : "/ifs/home/user12",
"zid" : 1
}
]
}

Create a bucket
Create a bucket.

Request example

POST /platform/12/protocols/s3/buckets
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"create_path": true,
"description" : "New bucket",
"name" : "bucket123",
"owner" : "admin",
"path" : "/ifs/home/user13"
}

Response example

{
"buckets" :
[

{
"acl" : [],
"description" : "",
"id" : "mybucket",
"name" : "mybucket",
"object_acl_policy" : "replace",
"owner" : "root",
"path" : "/ifs/mybucket",
"zid" : 1
}

70 System configuration API

 ]
}

Manage S3 settings
Retrieve and set S3 settings.

Request example
Retrieve the zone settings.

GET /platform/12/protocols/s3/settings/zone
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Response example

{
"settings" :
{
"base_domain" : "",
"bucket_directory_create_mode" : 511,
"object_acl_policy" : "replace",
"root_path" : "/ifs",
"use_md5_for_etag" : true,
"validate_content_md5" : true
}
}

Request example
Set the root path of the zone.

put /platform/12/protocols/s3/settings/zone
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"root_path" : "/ifs/home"
}

Response example
No message body is returned for this request.

204 No Content
Content-type: text/plain

FTP
OneFS includes a secure FTP service that is called Very Secure FTP Daemon (VSFTPD), that you can configure for standard
FTP and FTPS file transfers.
FTP is disabled by default. To enable FTP, use the following command:

isi services ftp enable

FTP resources
You can retrieve or modify global FTP configuration settings.

System configuration API 71

FTP settings resource
Retrieve and modify global FTP configuration settings.

Operation Method and URI

Retrieve global FTP configuration settings. GET <cluster-ip:port>/platform/12/
protocols/ftp/settings

Modify global FTP configuration settings. PUT <cluster-ip:port>/platform/12/

protocols/ftp/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/ftp/settings?describe

HTTP and HTTPS security

OneFS includes a configurable Hypertext Transfer Protocol (HTTP) service. Use HTTP to request files that are stored on the
cluster and to interact with the web administration interface.
HTTP and HTTPS are disabled by default. To enable them, use the following commands:

isi http settings modify --service=enabled

isi http settings modify --https=true

NOTE: Set the file and directory permissions to allow HTTP or HTTPS to access them.

OneFS supports both HTTP and its secure variant, HTTPS. Each node in the cluster runs an instance of the Apache HTTP
Server to provide HTTP access. You can configure the HTTP service to run in different modes.
Both HTTP and HTTPS are supported for file transfer, but only HTTPS is supported for API calls. The HTTPS-only requirement
includes the web administration interface. OneFS supports a form of the web-based DAV (WebDAV) protocol that enables users
to modify and manage files on remote web servers. OneFS performs distributed authoring, but does not support versioning and
does not perform security checks. You can enable DAV in the web administration interface.

HTTP resources
You can retrieve and modify global HTTP configuration settings.

HTTP settings resource

Retrieve and modify global HTTP configuration settings.

Operation Method and URI

Retrieve global HTTP configuration settings. GET <cluster-ip:port>/platform/12/protocols/
http/settings

Modify global HTTP configuration settings. PUT <cluster-ip:port>/platform/12/protocols/

http/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/
information about query parameters and object properties. http/settings?describe

HDFS security
Aside from what is contained in the OneFS PowerScale HDFS Reference Guide, the only additional security consideration is that
Cloudera Data Platform (CDP) Hadoop supports only secure URLs.

72 System configuration API

HDFS resources
You can retrieve, create, modify, or delete HDFS configurations and settings.

HDFS access zone settings resource

Modify or retrieve information about HDFS settings for a specified access zone. When no zone is specified, settings for the
system zone are returned or modified.

Operation Method and URI

Retrieve access zone HDFS settings. GET <cluster-ip:port>/platform/12/protocols/
hdfs/settings

Modify access zone HDFS settings. PUT <cluster-ip:port>/platform/12/protocols/

hdfs/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/
information about query parameters and object properties. hdfs/settings?describe

HDFS global settings resource

Modify or retrieve information about global HDFS settings.

Operation Method and URI

Retrieve the global HDFS settings. GET <cluster-ip:port>/platform/12/protocols/
hdfs/settings/global

Modify the global HDFS settings. PUT <cluster-ip:port>/platform/12/protocols/

hdfs/settings/global

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/
information about query parameters and object properties. hdfs/settings/global?describe

HDFS racks resource

Create, modify, delete, or retrieve information about HDFS racks.

Operation Method and URI

Retrieve all HDFS racks. GET <cluster-ip:port>/platform/12/protocols/
hdfs/racks

Create an HDFS rack. POST <cluster-ip:port>/platform/12/

protocols/hdfs/racks

Get an HDFS rack. GET <cluster-ip:port>/platform/12/protocols/

hdfs/racks/<rack ID>

Modify an HDFS rack. PUT <cluster-ip:port>/platform/12/protocols/

hdfs/racks/<rack ID>

Delete an HDFS rack. DELETE <cluster-ip:port>/platform/12/

protocols/hdfs/racks/<rack ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/
information about query parameters and object properties. hdfs/racks?describe
GET <cluster-ip:port>/platform/12/protocols/
hdfs/racks/<rack ID>?describe

System configuration API 73

HDFS proxy users resource
Create, delete, or retrieve information about HDFS proxy users.

Operation Method and URI

Retrieve all HDFS proxy users. GET <cluster-ip:port>/platform/12/protocols/
hdfs/proxyusers

Retrieve an HDFS proxy user. GET <cluster-ip:port>/platform/12/protocols/

hdfs/proxyusers/<NAME>

Create an HDFS proxy user. POST <cluster-ip:port>/platform/12/

protocols/hdfs/proxyusers/ or
PUT <cluster-ip:port>/platform/12/protocols/
hdfs/proxyusers/<NAME>

Delete an HDFS proxy user. DELETE <cluster-ip:port>/platform/12/

protocols/hdfs/proxyusers/<NAME>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/
information about query parameters and object properties. hdfs/proxyusers?describe
GET <cluster-ip:port>/platform/12/protocols/
hdfs/proxyusers/<NAME>?describe

HDFS proxy users name members resource

Add, delete, or retrieve information about HDFS proxy user members.

Operation Method and URI

Get all members of the HDFS proxy users. GET <cluster-ip:port>/platform/12/protocols/
hdfs/proxyusers/<NAME>/members

Add a member to the HDFS proxy user. POST <cluster-ip:port>/platform/12/

protocols/hdfs/proxyusers/<NAME>/members/ or

PUT <cluster-ip:port>/platform/12/protocols/
hdfs/proxyusers/<NAME>/members/<MEMBER>

Remove a member from the HDFS proxy user. DELETE <cluster-ip:port>/platform/12/

protocols/hdfs/proxyusers/<NAME>/members/
<MEMBER>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/
information about query parameters and object properties. hdfs/proxyusers/<NAME>/members?describe

HDFS log level resource

Retrieve or modify the HDFS service logging level for a node.

Operation Method and URI

Retrieve the HDFS logging level. GET <cluster-ip:port>/platform/12/protocols/
hdfs/log-level

Modify the HDFS logging level. PUT <cluster-ip:port>/platform/12/protocols/

hdfs/log-level

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/
information about query parameters and object properties. hdfs/log-level?describe

74 System configuration API

HDFS Apache Ranger plug-in settings resource
Retrieve and modify the HDFS Apache Ranger plug-in properties.

Operation Method and URI

Retrieve the HDFS Range plug-in properties. GET <cluster-ip:port>/platform/12/protocols/
hdfs/ranger-plugin/settings

Modify the HDFS Range plug-in properties. PUT <cluster-ip:port>/platform/12/protocols/

hdfs/ranger-plugin/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/
information about query parameters and object properties. hdfs/ranger-plugin/settings?describe

HDFS crypto settings resource

List or modify HDFS crypto settings.

Operation Method and URI

List HDFS crypto settings. GET <cluster-ip:port>/platform/12/protocols/
hdfs/crypto/settings

Modify HDFS crypto settings. PUT <cluster-ip:port>/platform/12/protocols/

hdfs/crypto/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/
information about query parameters and object properties. hdfs/crypto/settings?describe

HDFS crypto encryption zones resource

List encryption zones, or turn an empty directory into an encryption zone.

Operation Method and URI

List HDFS encryption zones. GET <cluster-ip:port>/platform/12/protocols/
hdfs/crypto/encryption-zones

Create an HDFS encryption zone. POST <cluster-ip:port>/platform/12/

protocols/hdfs/crypto/encryption-zones

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/
information about query parameters and object properties. hdfs/crypto/encryption-zones?describe

HDFS API examples

You can see examples for some HDFS API requests.

Create an HDFS rack

You can create an HDFS rack.

Request example
Put a forward slash (/) before the rack name.

POST /platform/12/protocols/hdfs/racks
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

System configuration API 75

 "name":"/racktest"
}

Response example

201 Created
Content-type: application/json

{
"id" : "1-5-21-4224731515-2571109568-2823010237-1003"
}

Modify an HDFS rack

You can modify the properties for an HDFS rack.

Request example
Put a forward slash (/) before the rack name. In the URL, replace the forward slash with the escape character %2F.

PUT /platform/12/protocols/hdfs/racks/%2Fracktest

Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"name":"/rack2test"
}

Response example
No message body is returned for this request.

204 No Content
Content-type: text/plain,
Allow: 'GET, PUT, HEAD'

Modify global HDFS settings

You can modify the properties of global HDFS settings. This example enables the HDFS service.

Request example

PUT /platform/12/protocols/hdfs/settings/global
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"service_enabled":true
}

Response example
No message body is returned for this request.

204 No Content
Content-type: text/plain,
Allow: 'GET, PUT, HEAD'

76 System configuration API

Modify access zone HDFS settings
You can modify the properties for access zone HDFS settings. Specify the access zone in the URI.

Request example

PUT /platform/12/protocols/hdfs/settings?zone=MyZone
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"default_checksum_type":"crc32"
}

Response example
No message body is returned for this request.

204 No Content
Content-type: text/plain,
Allow: 'GET, PUT, HEAD'

Create HDFS proxy users

Create an HDFS proxy user.

Request example

POST /platform/12/protocols/hdfs/proxyusers
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"proxy_user_test"}

Response example

201 Created
Content-type: application/json

You can also create an HDFS proxy user through the PUT method.

Request example

PUT /platform/12/protocols/hdfs/proxyusers/proxy_user_test
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{}

Response example

204 No Content
Content-type: text/plain

System configuration API 77

Create HDFS proxy user member
Create an HDFS proxy user member.

Request example

POST /platform/12/protocols/hdfs/proxyusers/proxy_user_test/members
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"proxy_user_member_test"}

Response example

201 Created
Content-type: application/json

You can also create an HDFS proxy user member through the PUT method.

Request example

PUT /platform/12/protocols/hdfs/proxyusers/proxy_user_test/members/
USER:proxy_user_member_test
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{}

Response example

204 No Content
Content-type: text/plain

OpenStack Swift
OneFS supports OpenStack Swift, an object storage interface compatible with the OpenStack Swift 1.0 application
programming interface (API). Through OpenStack Swift, you can access file-based data that is stored on your cluster as
objects. The Swift API is implemented as a set of Representational State Transfer (REST) web services over HTTP or
secure HTTP (HTTPS). Since the Swift API is considered as a protocol, content and metadata can be ingested as objects
and concurrently accessed through protocols that are configured on the cluster. The cluster requires a licensed to support
OpenStack Swift.
NOTE: Support for OpenStack Swift will be removed for OneFS in a future release. Dell Technologies recommends using
the OneFS S3 protocol support instead. See KB#542999 for more information.
The OpenStack Swift protocol service is a licensed feature. Contact your Dell Technologies representative to obtain a license
key to access the Swift protocol and RESTful APIs for object storage operations.

Swift resources
You can list, create, modify, or delete Swift account information.

Swift accounts resource

List, modify, create, or delete Swift accounts.

Operation Method and URI

List all Swift accounts. GET <cluster-ip:port>/platform/12/protocols/swift/
accounts

78 System configuration API

Operation Method and URI
List a specific Swift account. GET <cluster-ip:port>/platform/12/protocols/swift/
accounts/<ACCOUNT>

Create a Swift account. POST <cluster-ip:port>/platform/12/protocols/swift/

accounts

Modify a Swift account. PUT <cluster-ip:port>/platform/12/protocols/swift/

accounts/<ACCOUNT>

Delete a Swift account. DELETE <cluster-ip:port>/platform/12/protocols/swift/

accounts/<ACCOUNT>

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/protocols/swift/

resource, which has information about query accounts?describe
parameters and object properties.
GET <cluster-ip:port>/platform/12/protocols/swift/
accounts/<ACCOUNT>?describe

Networking
After you determine the topology of your network, you can set up and manage your internal and external networks.
There are two types of networks on the PowerScale cluster:

Internal Nodes communicate with each other using a high-speed low latency InfiniBand network. You can
optionally configure a second InfiniBand network to enable failover for redundancy.
External Clients connect to the cluster through the external network with Ethernet. The cluster supports standard
network communication protocols, including NFS, SMB, HDFS, HTTP, and FTP. The cluster includes
various external Ethernet connections, providing flexibility for a wide variety of network configurations.

Network resources
List, create, modify, or delete information specific to OneFS networks.

Network external resource

View or modify external network settings.

Operation Method and URI

View external network settings. GET <cluster-ip:port>/platform/12/network/
external

Modify external network settings. PUT <cluster-ip:port>/platform/12/network/

external

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. external?describe

Network subnets resource

List OneFS network subnets.

Operation Method and URI

List OneFS network subnets. GET <cluster-ip:port>/platform/12/network/
subnets

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. subnets?describe

System configuration API 79

Network DNS cache resource
View or modify network DNS cache settings.

Operation Method and URI

View DNS cache settings. GET <cluster-ip:port>/platform/12/network/
dnscache

Modify DNS cache settings. PUT <cluster-ip:port>/platform/12/network/

dnscache

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. dnscache?describe

Network DNS cache flush resource

Flush the DNS cache.

Operation Method and URI

Flush the DNS cache. POST <cluster-ip:port>/platform/12/network/
dnscache/flush

View the detailed JSON schema for this resource, which has GET<cluster-ip:port>/platform/12/network/
information about query parameters and object properties. dnscache/flush?describe

Network interfaces resource

List OneFS network interfaces. The /network/interfaces API shows you the live status of the interfaces, allowing you to
monitor or view the status of the network interfaces within your PowerScale cluster. Using the API, you can find information
regarding the overall status, VLAN status, what IPs belong to which network pools, and more.

Operation Method and URI

List all OneFS network interfaces. GET <cluster-ip:port>/platform/12/network/
interfaces

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. interfaces?describe

Request query parameters

View the various query parameters for network interface API requests.

Query Parameter Accepted Values Description Example

lnn Integer Filter the list of Network GET /12/
interfaces to the interfaces network/interfaces?
belonging to the specified lnns lnn=1&lnn=2
type Enum Filter the returned IPs GET /12/
● static and owners by specifying network/interfaces?
the required IP type. To type=network_pool_ips
● dynamic
get similar results to past
● smartconnect_service versions of this API, use
● ipv6_link_local network_pool_ips as it
● internal returns only IPs from Network
● network_pool_ips Pools
● all
The default query returns
all non IPv6 Link Local
IPs.

80 System configuration API

Query Parameter Accepted Values Description Example
owner String Filter by the specified owner GET /12/
ID which can be an exact network/interfaces?
match, or a partial match. An owner=subnet0.pool0
exact match is an identifier
such as GET /12/network/
groupnet0.subnet0.poo interfaces?
l0, while a partial match is owner=groupnet0.subne
'groupnet0.subnet0'. Partial t.pool0
match includes the following
in the output: GET /12/
● groupnet0.subnet0.p network/interfaces?
ool0 owner=groupnet0
● other pools in the subnet
● SmartConnect Service IPs
configured in the subnet
network Enum Allows for specifying which GET /12/
● all network to filter results by network/interfaces?
● external (DEFAULT) network=external
● internal
cache Enum /12/network/ GET /12/network/
● cache-only interfaces by default interfaces?cache=no-
● no-cache attempts to gather cache
● nodes-first (DEFAULT) live results from
nodes to reply to requests.
As this is not wanted, this
query parameter allows the
caller to specify the behavior.
cache-only: Fetches
results that are cached
Cached results are unable to
display:
● Mtu
● Gateway information
● SmartConnect Service IPs
● IPv6 Link Local IPs
no-cache: Returns results
from nodes that give
responses. If there is no
response from a node, an
error occurs in the errors
array.
nodes-first: Queries
nodes, and on failure falls
back to grab results from the
cache

include_vlans Boolean. If you do not want to see any GET /12/

VLAN results in the output, network/interfaces?
Default: true
setting this parameter to false include_vlans=false
filters out any VLANs
vlan_id Integer If you want to view VLANs GET /12/
of a certain VLAN ID, network/interfaces?
this parameter allows you vlan_id=101
to filter the list down to
the specified VLAN ID. The
physical interface the VLAN is
configured on, is returned.

System configuration API 81

Network interfaces examples
View examples regarding selective network interface API requests.

Request example

GET /platform/12/network/interfaces?
lnn=1&type=network_pool_ips&owner=groupnet0.subnet0.pool0 HTTP/1.1
Host: <CLUSTER_IP>:8080
User-Agent: curl/7.73.0
Accept: */*

* Mark bundle as not supporting multiuse

HTTP/1.1 200 Ok
Date: Fri, 26 Feb 2021 17:20:55 GMT
Server: Apache
Allow: GET, HEAD
X-Frame-Options: sameorigin
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000;
Transfer-Encoding: chunked
Content-Type: application/json

Response example

{
"errors" : null,
"interfaces" :
[

{
"flags" : [ "ACCEPT_ROUTER_ADVERT" ],
"id" : "1:ext-1",
"ip_addrs" : [ "<IP>" ],
"ipv4_gateway" : "<IP>",
"ipv6_gateway" : "<IP>",
"lnn" : 1,
"mtu" : 1500,
"name" : "ext-1",
"nic_name" : "em1",
"owners" :
[

{
"access_zone" : "System",
"groupnet" : "groupnet0",
"id" : "groupnet0.subnet0.pool0",
"ip_addrs" : [ "<IP>" ],
"pool" : "pool0",
"subnet" : "subnet0",
"type" : "static",
"vlan_id" : null
}
],
"status" : "up",
"type" : "gige",
"vlans" : []
}
],
"resume" : null,
"total" : 1
}

82 System configuration API

Network pools resource
List OneFS flex net pools.

Operation Method and URI

List OneFS flex net pools. GET <cluster-ip:port>/platform/12/network/
pools

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. pools?describe

Network rules resource

List OneFS network rules.

Operation Method and URI

List OneFS network rules. GET <cluster-ip:port>/platform/12/network/
rules

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. rules?describe

Network SmartConnect rebalance all IP resource

Rebalance IP addresses in all pools.

Operation Method and URI

Rebalance IP addresses in all pools. POST <cluster-ip:port>/platform/12/network/
sc-rebalance-all

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. sc-rebalance-all?describe

Network groupnets resource

List, create, modify, or delete OneFS network groupnets.

Operation Method and URI

List all groupnets. GET <cluster-ip:port>/platform/12/network/
groupnets

View a specific groupnet. GET <cluster-ip:port>/platform/12/network/

groupnets/<GROUPNET>

Create a groupnet. POST <cluster-ip:port>/platform/12/network/

groupnets

Modify a groupnet. PUT <cluster-ip:port>/platform/12/network/

groupnets/<GROUPNET>

Delete a groupnet. DELETE <cluster-ip:port>/platform/12/

network/groupnets/<GROUPNET>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. groupnets?describe
GET <cluster-ip:port>/platform/12/network/
groupnets/<GROUPNET>?describe

System configuration API 83

Network groupnets subnets resource
List, create, modify, or delete OneFS network subnets.

Operation Method and URI

List all subnets. GET <cluster-ip:port>/platform/12/network/
groupnets/<groupnet>/subnets

View a specific subnet. GET <cluster-ip:port>/platform/12/network/

groupnets/<groupnet>/subnets/<subnet>

Create a subnet. POST <cluster-ip:port>/platform/12/network/

groupnets/<groupnet>/subnets

Modify a subnet. PUT <cluster-ip:port>/platform/12/network/

groupnets/<groupnet>/subnets/<subnet>

Delete a groupnet. DELETE <cluster-ip:port>/

platform/12/network/groupnets/<groupnet>/
subnets/<subnet>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. groupnets/<groupnet>/subnets?describe
GET <cluster-ip:port>/
platform/12/network/groupnets/<groupnet>/
subnets/<subnet>?describe

Network groupnets subnets pools resource

Retrieve, create, modify, or delete OneFS network pools.

Operation Method and URI

Retrieve all pools. GET <cluster-ip:port>/platform/12/network/
groupnets/<groupnet>/subnets/<subnet>/pools

View a specific subnet pool. GET <cluster-ip:port>/platform/12/network/

groupnets/<groupnet>/subnets/<subnet>/pools/
<pool>

Create a pool. POST <cluster-ip:port>/platform/12/network/

groupnets/<groupnet>/subnets<subnet>/pools

Modify a pool. PUT <cluster-ip:port>/platform/12/network/

groupnets/<groupnet>/subnets/<subnet>/pools/
<pool>

Delete a pool. DELETE <cluster-ip:port>/

platform/12/network/groupnets/<groupnet>/
subnets/<subnet>/pools/<pool>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. groupnets/<groupnet>/subnets/<subnet>/pools?
describe
GET <cluster-ip:port>/platform/12/network/
groupnets/<groupnet>/subnets/<subnet>/pools/
<pool>?describe

Network groupnets subnets pools interfaces resource

List OneFS network interfaces within a pool.

NOTE:

84 System configuration API

 In OneFS 9.2, this functionality has been merged into the /12/network/interfaces API. This endpoint will no longer
receive new functionality. To upgrade to /12/network/interfaces from this API, replace:

/7/network/groupnets/<GROUPNET>/subnets/<SUBNET>/pools/<POOL>/interfaces

with
/12/network/interfaces?owner=<GROUPNET>.<SUBNET>.<POOL>

Operation Method and URI

List all OneFS network interfaces within a pool. GET <cluster-ip:port>/platform/7/network/
groupnets/<GROUPNET>/subnets/<SUBNET>/pools/
<POOL>/interfaces

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/7/network/
information about query parameters and object properties. groupnets/<GROUPNET>/subnets/<SUBNET>/pools/
<POOL>/interfaces?describe

Network groupnets subnets pools rebalance IP resource

Rebalance IP addresses in a specified pool.

Operation Method and URI

Rebalance IP addresses in a specified pool. POST <cluster-ip:port>/platform/12/network/
groupnets/<GROUPNET>/subnets<SUBNET>/pools/
<POOL>/rebalance-ips

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. groupnets/<GROUPNET>/subnets/<SUBNET>/pools/
<POOL>/rebalance-ips?describe

Network groupnets subnets pools rules resource

List, create, modify, or delete OneFS network rules within a pool.

Operation Method and URI

List all OneFS network rules within a pool. GET <cluster-ip:port>/platform/12/network/
groupnets/<groupnet>/subnets/<subnet>/pools/
<pool>/rules

View a specific OneFS network rule within a pool. GET <cluster-ip:port>/platform/12/network/

groupnets/<groupnet>/subnets/<subnet>/pools/
<pool>/rules/<name>

Create a OneFS network rule within a pool. POST <cluster-ip:port>/platform/12/network/

groupnets/<groupnet>/subnets<subnet>/pools/
<pool>/rules

Modify a OneFS network rule within a pool. PUT <cluster-ip:port>/platform/12/network/

groupnets/<groupnet>/subnets/<subnet>/pools/
<pool>/rules/<name>

Delete a OneFS network rule within a pool. DELETE <cluster-ip:port>/

platform/12/network/groupnets/<groupnet>/
subnets/<subnet>/pools/<pool>/rules/<name>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. groupnets/<groupnet>/subnets/<subnet>/pools/
<pool>/rules?describe
GET <cluster-ip:port>/platform/12/network/
groupnets/<groupnet>/subnets/<subnet>/pools/
<pool>/rules/<name>?describe

System configuration API 85

Network groupnets subnets pools SmartConnect suspend nodes resource
Suspend SmartConnect DNS query responses for a list of nodes.

Operation Method and URI

Suspend SmartConnect DNS query responses for a list of POST <cluster-ip:port>/platform/12/network/
nodes. groupnets/<groupnet>/subnets<subnet>/pools/
<pool>/sc-suspend-nodes

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. groupnets/<groupnet>/subnets/<subnet>/pools/
<pool>/sc-suspend-nodes?describe

Network groupnets subnets pools SmartConnect resume nodes resource

Resume SmartConnect DNS query responses for a list of nodes.

Operation Method and URI

Resume SmartConnect DNS query responses for a list of POST <cluster-ip:port>/platform/12/network/
nodes. groupnets/<groupnet>/subnets<subnet>/pools/
<pool>/sc-resume-nodes

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/network/
information about query parameters and object properties. groupnets/<groupnet>/subnets/<subnet>/pools/
<pool>/sc-resume-nodes?describe

IPMI remote power

The intelligent platform management interface (IPMI) lets you issue remote power control commands and serial over LAN (SOL)
functionality for platforms that support it. The baseboard management controller local area network (BMC LAN) manages IPMI
request messages. Allocated network IP addresses, either static or DHCP, are required for the BMC LAN channel.

IMPI configuration features resources

Retrieve, create, modify, or delete remote IPMI configurations and settings.

IPMI feature configuration resource

Retrieve detailed information about all IPMI features, retrieve feature configuration, and set feature configuration.

Operation Method and URI

Retrieve feature information. GET <cluster-ip:port>/platform/12/ipmi/
config/features

Retrieve a feature configuration. GET <cluster-ip:port>/platform/12/ipmi/

config/features/<FEATURE>

Modify a feature configuration. PUT <cluster-ip:port>/platform/12/ipmi/

config/features/<FEATURE>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/ipmi/
information about query parameters and object properties. config/features?describe
GET <cluster-ip:port>/platform/12/ipmi/
config/features/<FEATURE>?describe

86 System configuration API

IPMI configuration network resources
Retrieve and modify the static network configuration.

Operation Method and URI

Retrieve the static network configuration. GET <cluster-ip:port>/platform/12/ipmi/
config/network

Modify the static network configuration. PUT <cluster-ip:port>/platform/12/ipmi/

config/network

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/ipmi/
information about query parameters and object properties. config/network?describe

IPMI configuration nodes

Retrieve the remote IPMI management nodes configuration and the configuration of a specific node.

Operation Method and URI

Retrieve the configuration of all nodes. GET <cluster-ip:port>/platform/12/ipmi/
config/nodes

Retrieve the configuration of a specific node. GET <cluster-ip:port>/platform/12/ipmi/

config/nodes/<LNN>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/ipmi/
information about query parameters and object properties. config/nodes?describe
GET <cluster-ip:port>/platform/12/ipmi/
config/nodes/<LNN>?describe

IPMI configuration settings resource

Retrieve and modify remote IPMI management configuration settings.

Operation Method and URI

Retrieve the remote IPMI management configuration settings. GET <cluster-ip:port>/platform/12/ipmi/
config/settings

Modify the remote IPMI management configuration settings. PUT <cluster-ip:port>/platform/12/ipmi/

config/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/ipmi/
information about query parameters and object properties. config/settings?describe

IPMI configuration user resources

Retrieve and modify the remote IPMI management user.

Operation Method and URI

Retrieve the remote IPMI management user. GET <cluster-ip:port>/platform/12/ipmi/
config/user

Modify the remote IPMI management user. PUT <cluster-ip:port>/platform/12/ipmi/

config/user

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/ipmi/
information about query parameters and object properties. config/user?describe

System configuration API 87

System jobs overview
The most critical function of OneFS is maintaining the integrity of data on your PowerScale cluster. Other important system
maintenance functions include monitoring and optimizing performance, detecting and mitigating drive and node failures, and
freeing up available space.
Maintenance functions use system resources and can take hours to run. System components manage some maintenance
functions. For example, SyncIQ creates jobs to synchronize source and target content, and CloudPools creates jobs to upload
and download data to and from the cloud. This section describes the system maintenance functions, called jobs, that are
managed by the Job Engine. Jobs run in the background.
The time that it takes for a job to run can vary depending on several factors, including:
● Other system jobs that are running.
● Other processes that are taking up CPU and I/O cycles while the job is running.
● The configuration of your cluster
● The size of your dataset
● How long since the last iteration of the job was run.
It is recommended that you have no more than three jobs running simultaneously.
Job Engine evaluates jobs to enable higher priority jobs and administrator tasks to proceed. Job evaluation includes:
● Ensuring that jobs that have the same exclusion sets do not run simultaneously.
● Running jobs at different priority and impact levels
● Temporarily suspending jobs (with no loss of progress)
If a power failure occurs, the Job Engine checkpoint system resumes jobs as close as possible to the point at which they were
interrupted. The checkpoint system monitors the tasks in the current job phase until they are completed. When the cluster is
back up and available, Job Engine resumes the job phase from the last checkpoint.
As system administrator, through the Job Engine service, you can monitor, schedule, run, terminate, and apply other controls
to system maintenance jobs. The Job Engine provides statistics and reporting tools that you can use to determine how long
different system jobs take to run in your OneFS environment.

NOTE: To initiate any Job Engine tasks, you must have the role of SystemAdmin in the OneFS system.

Maintenance job resources

You can enable or disable the maintenance mode of a system.

Operation Method and URI

Determine if maintenance mode is enabled or disabled. GET /platform/12/event/maintenance

List the maintenance mode history. GET /platform/12/event/maintenance?

history=true

Enable or disable maintenance mode. PUT /platform/12/event/maintenance

View the detailed JSON schema for this resource, which has GET /platform/12/event/maintenance?describe
information about query parameters and object properties.

System job resources

You can retrieve, create, modify, or delete system job settings and configurations.

Jobs resource
Modify, create, or retrieve information about OneFS system jobs.

Operation Method and URI

Retrieve information about all system jobs. GET /platform/12/job/jobs

88 System configuration API

Operation Method and URI
Retrieve information about a system job. GET /platform/12/job/jobs/<JID>

Create a system job. POST /platform/12/job/jobs

Modify a system job. PUT /platform/12/job/jobs/<JID>

View the detailed JSON schema for this resource, which has GET /platform/12/job/jobs?describe
information about query parameters and object properties.
GET /platform/12/job/jobs/<JID>?describe

Job types resource

Modify or retrieve information about system job types.

Operation Method and URI

Retrieve all system job types. GET <cluster-ip:port>/platform/12/job/types

Retrieve a system job type. GET <cluster-ip:port>/platform/12/job/types/

<NAME>

Modify a system job type. PUT <cluster-ip:port>/platform/12/job/type/

<NAME>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/job/types?
information about query parameters and object properties. describe

Job policies resource

Create, modify, delete, or retrieve information about job impact policies.

Operation Method and URI

Get all job impact policies. GET <cluster-ip:port>/platform/12/job/
policies

Get a job impact policy. GET <cluster-ip:port>/platform/12/job/

policies/<NAME>

Create a job impact policy. POST <cluster-ip:port>/platform/12/job/

policies

Modify a job impact policy. PUT <cluster-ip:port>/platform/12/job/

policies/<NAME>

Delete a job impact policy. DELETE <cluster-ip:port>/platform/12/job/

policies/<NAME>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/job/
information about query parameters and object properties. policies?describe

Job reports resource

Retrieve information about system job reports.

Operation Method and URI

View all job reports. GET <cluster-ip:port>/platform/12/job/
reports

View a specific job report. GET <cluster-ip:port>/platform/12/job/

reports/<JID>

System configuration API 89

Operation Method and URI
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/job/
information about query parameters and object properties. reports?describe
GET <cluster-ip:port>/platform/12/job/
reports/<JID>?describe

Job summary resource

View job engine status.

Operation Method and URI

View job engine status. GET <cluster-ip:port>/platform/12/job/job-
summary

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/job/job-
information about query parameters and object properties. summary?describe

Job events resource

Retrieve information about system job events.

Operation Method and URI

Get information about job events. GET <cluster-ip:port>/platform/12/job/events

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/job/
information about query parameters and object properties. events?describe

Job statistics resource

Retrieve statistics about system jobs and workers across the cluster.

Operation Method and URI

Retrieve system job statistics. GET <cluster-ip:port>/platform/12/job/
statistics

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/job/
information about query parameters and object properties. statistics?describe

Job recent resource

List recently completed jobs.

Operation Method and URI

List recently completed jobs. GET <cluster-ip:port>/platform/12/job/recent

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/job/
information about query parameters and object properties. recent?describe

System job API examples

You can see examples for some system job API calls.

90 System configuration API

Modify a job type
You can modify a system job type.

Request example

PUT /platform/12/job/types/AVScan
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'policy': 'MEDIUM',
'enabled': True
}

Response example

204 No Content
Content-type: 'text/plain',
Allow: 'GET, PUT, HEAD'

Create a job policy

You can create a system job policy.

Request example

POST /platform/12/job/policies
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'intervals': [
{
'impact': 'High',
'begin': 'Tuesday 00:00',
'end': 'Thursday 23:59'}
],
'name': 'myPolicy',
'description': 'Custom policy'
}

Response example

201 CREATED
Content-type: application/json,
Allow: 'GET, PUT, POST, DELETE'

{
'id': 'myPolicy'
}

Modify a job policy

You can retrieve modify a system job policy.

Request example

PUT /platform/12/job/policies/myPolicy
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'intervals': [

System configuration API 91

 {
'impact': 'Medium',
'begin': 'Tuesday 00:00',
'end': 'Thursday 23:59'}
],
'description': 'Custom policy - medium impact Tuesday through Thursday'
}

Response example

204 No Content
Content-type: 'text/plain',
Allow: 'GET, PUT, POST, DELETE, HEAD'

Start a new system job

You can queue a new instance of a job to run after the current job is done.

Request example

POST /platform/12/job/jobs
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'type': 'AVScan',
'allow_dup': True
}

Response example

201 CREATED
Content-type: application/json,
Allow: 'GET, PUT, POST, HEAD'

{
"id": 1234
}

Modify a system job

You can modify, cancel, pause, or resume a running system job.

Request example

PUT /platform/12/job/jobs/AVScan
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'state': 'pause'
}

Response example

204 No Content
Content-type: 'text/plain',
Allow: 'GET, PUT, POST, HEAD'

92 System configuration API

Cluster statistics
You can view performance, historical, and in-depth usage statistics for your PowerScale cluster, and control the output for each
mode of statistics reporting.

Statistics resources
You can retrieve information about OneFS statistics through the following resources.

Statistics current resource

Query OneFS current statistics. These statistics are the most current metrics at the time of the request. For a list of
available statistics keys with descriptions, see the <cluster-ip:port>/platform/<version>/statistics/keys or
<cluster-ip:port>/platform/<version>/statistics/keys/<key> resources.

Operation Method and URI

Retrieve all current statistics. GET <cluster-ip:port>/platform/12/
statistics/current

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/current?describe

Statistics keys resource

Retrieve metadata for matching statistics keys.

Operation Method and URI

Retrieve all statistic keys. GET <cluster-ip:port>/platform/12/
statistics/keys

Retrieve a statistics key. GET <cluster-ip:port>/platform/12/

statistics/keys/<KEY>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/keys?describe
GET <cluster-ip:port>/platform/12/
statistics/keys/<key>?describe

Statistics history resource

Query OneFS time-series statistics over custom time ranges. Not all statistics have time-series that are enabled. For
those statistics with time-series enabled, the full extent of the requested time range may not be available due to
configuration or system uptime. For a list of available statistics keys with descriptions, see the <cluster-ip:port>/
platform/<version>/statistics/keys or <cluster-ip:port>/platform/<version>/statistics/keys/
<key> resources. These resources also describe available history policies for each key.

Operation Method and URI

Retrieve all statistics history. GET <cluster-ip:port>/platform/12/
statistics/history

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/history?describe

System configuration API 93

Statistics operations resource
List all operations that are implemented for protocol and client statistics on a OneFS cluster.

Operation Method and URI

List all statistics operations. GET <cluster-ip:port>/platform/12/
statistics/operations

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/operations?describe

Statistics protocols resource

Return a list of protocol and client statistics for OneFS.

Operation Method and URI

Get all protocols. GET <cluster-ip:port>/platform/12/
statistics/protocols

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/protocols?describe

Statistics summary client resource

Display OneFS cluster usage statistics that are sorted by cluster hosts and users.

Operation Method and URI

Display cluster usage statistics that are sorted by cluster GET <cluster-ip:port>/platform/12/
hosts and users. statistics/summary/client

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/summary/client?describe

Statistics summary drive resource

Display OneFS performance statistics by drive.

Operation Method and URI

Display performance statistics by drive. GET <cluster-ip:port>/platform/12/
statistics/summary/drive

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/summary/drive?describe

Statistics summary heat resource

List OneFS files and directories that are considered the busiest, or hottest, sorted by various performance-related factors.

Operation Method and URI

Display the busiest, or hottest, OneFS files and directories. GET <cluster-ip:port>/platform/12/
statistics/summary/heat

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/summary/heat?describe

94 System configuration API

Statistics summary protocol resource
Display cluster usage statistics sorted by protocol.

Operation Method and URI

Display cluster usage statistics sorted by protocol. GET <cluster-ip:port>/platform/12/
statistics/summary/protocol

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/summary/protocol?describe

Statistics summary protocol stats resource

Display detailed statistics about protocol usage, and OneFS, CPU, network, and disk statistics.

Operation Method and URI

Display detailed statistics about protocol usage. GET <cluster-ip:port>/platform/12/
statistics/summary/protocol-stats

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/summary/protocol-stats?describe

Statistics summary system resource

Display general cluster statistics, including operation rates for all supported protocols, and network and disk traffic in kilobytes
per second.

Operation Method and URI

Display general cluster statistics. GET <cluster-ip:port>/platform/12/
statistics/summary/system

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/summary/system?describe

Statistics summary workload resource

This resource summarizes statistics about system processes and jobs.

Operation Method and URI

Retrieve statistics about system processes and jobs. GET <cluster-ip:port>/platform/12/
statistics/summary/workload

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. statistics/summary/workload?describe

FSA
The FS Analyze job gathers and reports information about all files and directories beneath the /ifs path. This job requires you to
activate an InsightIQ license. You can use reports from this job to analyze the OneFS file system.
For more information, see the Isilon InsightIQ User Guide.

FSA resources
Retrieve, create, modify, or delete FSAnalyze (FSA) job-related configurations and settings.

System configuration API 95

FSA path resource
Retrieves the path to mount to access the results of the FS Analyze (FSA) job. Creates the FSA export rule if it does not
previously exist.

Operation Method and URI

Retrieve export path as plain text. GET <cluster-ip:port>/platform/12/fsa/path

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/fsa/path?
information about query parameters and object properties. describe

FSA index resource

This resource exposes all the FSA index tables available on a PowerScale cluster.

NOTE: To specify a LIN, use decimal format.

Operation Method and URI

List all the FSA index table names available on a PowerScale GET <cluster-ip:port>/platform/12/fsa/index
cluster.
List index entries from the given index table. GET <cluster-ip:port>/platform/12/fsa/index/
<NAME>/lins

List a single index entry from the index table. GET <cluster-ip:port>/platform/12/fsa/index/
<NAME>/lins/<LIN>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/fsa/index?
information about query parameters and object properties. describe
GET <cluster-ip:port>/platform/12/fsa/index/
<NAME>/lins?describe

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/fsa/index/
information about query parameters and object properties. <NAME>/lins/<LIN>?describe

FSA results resource

List all FSA job result sets, or list, modify, or delete individual result sets.
Specifying 0 (zero) as the RESULT-SET-ID acts on the latest result set.

Operation Method and URI

List all FSA job result sets. GET <cluster-ip:port>/platform/12/fsa/
results

List individual FSA job result set. GET <cluster-ip:port>/platform/12/fsa/

results/<RESULT-SET-ID>

Modify the pinned property for an FSA job result set. PUT <cluster-ip:port>/platform/12/fsa/
results/<RESULT-SET-ID>

Delete an FSA job result set. DELETE <cluster-ip:port>/platform/12/fsa/

results/<RESULT-SET-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/fsa/
information about query parameters and object properties. results?describe
GET <cluster-ip:port>/platform/12/fsa/
results/<RESULT-SET-ID>?describe

96 System configuration API

FSA pool usage for a directory resource
Retrieve pool usage information for the directory that is specified by the query path argument or the directory that is specified
by the logical inode number (LIN) parameter.

NOTE: To specify a LIN, use decimal format.

Operation Method and URI

Retrieve pool usage information for the directory specified by GET <cluster-ip:port>/platform/12/fsa/
the query path argument. results/<RESULT-SET-ID>/dir_pool_usage

Retrieve results directory information for the directory GET <cluster-ip:port>/platform/12/fsa/

specified by the LIN. results/<RESULT-SET-ID>/dir_pool_usage/<LIN>

View the detailed JSON schema for this resource, which has GET
information about query parameters and object properties. <cluster-ip:port>/platform/12/fsa/results/
<RESULT-SET-ID>/dir_pool_usage?describe
GET <cluster-
ip:port>/platform/12/fsa/results/<RESULT-
SET-ID>/dir_pool_usage/<LIN>?describe

FSA results directories resource

Retrieve results directory information for the directory that is specified by the query path argument or the directory that is
specified by the logical inode number (LIN) parameter.

NOTE: To specify a LIN, use decimal format.

Operation Method and URI

Retrieve results directory information for the directory GET <cluster-ip:port>/platform/12/fsa/
specified by the query path argument. results/<RESULT-SET-ID>/directories

Retrieve results directory information for the directory GET <cluster-ip:port>/platform/12/fsa/

specified by the LIN. results/<RESULT-SET-ID>/directories/<LIN>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/fsa/
information about query parameters and object properties. results/<RESULT-SET-ID>/directories?describe
GET
<cluster-ip:port>/platform/12/fsa/results/
<RESULT-SET-ID>/directories/<LIN>?describe

FSA results histogram resource

Retrieve file count histograms that are sorted by the STAT or BREAKOUT parameter.

Operation Method and URI

Retrieve a histogram of file counts for an individual FSA result GET <cluster-ip:port>/platform/12/fsa/
set. results/<RESULT-SET-ID>/histogram
GET <cluster-ip:port>/platform/12/fsa/
results/<RESULT-SET-ID>/histogram/<STAT>

Retrieve a histogram breakout for an individual FSA result set. GET <cluster-ip:port>/platform/12/fsa/
results/<RESULT-SET-ID>/histogram/<STAT>/by
GET <cluster-ip:port>/platform/12/fsa/
results/<RESULT-SET-ID>/histogram/<STAT>/by/
<BREAKOUT>

System configuration API 97

Operation Method and URI
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/fsa/
information about query parameters and object properties. results/<RESULT-SET-ID>/histogram?describe
GET
<cluster-ip:port>/platform/12/fsa/results/
<RESULT-SET-ID>/histogram/<STAT>?describe
GET <cluster-ip:port>/platform/12/fsa/
results/<RESULT-SET-ID>/histogram/<STAT>/by?
describe
GET <cluster-ip:port>/platform/12/fsa/
results/<RESULT-SET-ID>/histogram/<STAT>/by/
<BREAKOUT>?describe

FSA results top directories resource

Retrieves the top directories according to the stat parameter.

Operation Method and URI

Retrieve top directories. GET <cluster-ip:port>/platform/12/fsa/
<result-set-id>/top-dirs

Retrieve top directories using query parameters. GET <cluster-ip:port>/platform/12/fsa/

<result-set-id>/top-dirs/<stat>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/fsa/
information about query parameters and object properties. <result-set-id>/top-dirs?describe
GET <cluster-ip:port>/platform/12/fsa/
<result-set-id>/top-dirs/<stat>?describe

FSA results top files resource

Retrieves the top files according to the STAT parameter.

Operation Method and URI

Retrieve top files. GET <cluster-ip:port>/platform/12/fsa/
<RESULT-SET-ID>/top-files

Retrieve top directories using query parameters. GET <cluster-ip:port>/platform/12/fsa/

<RESULT-SET-ID>/top-files/<STAT>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/fsa/
information about query parameters and object properties. <RESULT-SET-ID>/top-files?describe
GET <cluster-ip:port>/platform/12/fsa/
<RESULT-SET-ID>/top-files/<STAT>?describe

FSA settings resource

List or modify FSA settings, or revert FSA settings to their default values.

Operation Method and URI

List FSA settings. GET <cluster-ip:port>/platform/12/fsa/
settings

Modify FSA settings. PUT <cluster-ip:port>/platform/12/fsa/

settings

98 System configuration API

Operation Method and URI
Revert FSA settings to their defaults. DELETE <cluster-ip:port>/platform/12/fsa/
settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/fsa/
information about query parameters and object properties. settings?describe

Events and alerts

Events are individual occurrences or conditions that are related to the data workflow, maintenance operations, and hardware
components of your cluster. An alert is a message that describes a change that has occurred in an event group.
Throughout OneFS, there are processes that are constantly monitoring and collecting information about cluster operations.
When the status of a component or operation changes, the change is captured as an event and placed into a priority queue at
the kernel level.
Every event has two ID numbers that help to establish the context of the event:
● The event type ID identifies the type of event that has occurred.
● The event instance ID is a unique number that is specific to a particular occurrence of an event type. When an event is
submitted to the kernel queue, an event instance ID is assigned. You can reference the instance ID to determine the exact
time that an event occurred.
You can view individual events. However, you manage events and alerts at the event group level.
At any point in time, you can view event groups to track situations occurring on your cluster. However, you can also create
alerts that proactively notify you if there is a change in an event group.
For example, you can generate an alert when a new event is added to an event group, when an event group is resolved, or when
the severity of an event group changes.
You can configure your cluster to only generate alerts for specific conditions or event groups, or during limited time periods.
Alerts are delivered through channels. You can configure a channel to determine who will receive the alert and when.

Event resources
Retrieve, create, modify, or delete event-related configurations and settings.

Event alert conditions resource

List, create, modify, or delete event alert conditions.

Operation Method and URI

List all event alert conditions. GET <cluster-ip:port>/platform/12/event/
alert-conditions

List one event alert condition. GET <cluster-ip:port>/platform/12/event/

alert-conditions/<CONDITION-ID>

Create an event alert condition. POST <cluster-ip:port>/platform/12/event/

alert-conditions

Modify an event alert condition. PUT <cluster-ip:port>/platform/12/event/

alert-conditions/<CONDITION-ID>

Bulk deletes event alert conditions. DELETE <cluster-ip:port>/platform/12/event/

alert-conditions

Delete an individual alert condition. DELETE <cluster-ip:port>/platform/12/event/

alert-conditions/<CONDITION-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/event/
information about query parameters and object properties. alert-conditions?describe

System configuration API 99

Operation Method and URI
GET <cluster-ip:port>/platform/12/event/
alert-conditions/<CONDITION-ID>?describe

Event categories resource

List one or all event categories.

Operation Method and URI

List all event categories. GET <cluster-ip:port>/platform/12/event/
categories

List one event category. GET <cluster-ip:port>/platform/12/event/

categories/<CATEGORY-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/event/
information about query parameters and object properties. categories?describe
GET <cluster-ip:port>/platform/12/event/
categories/<CATEGORY-ID>?describe

Event channels resource

List, create, modify, or delete event channels.

Operation Method and URI

List all event channels. GET <cluster-ip:port>/platform/12/event/
channels

List one event channel. GET <cluster-ip:port>/platform/12/event/

channels/<CHANNEL-ID>

Create an event channel. POST <cluster-ip:port>/platform/12/event/

channels

Modify an event channel. PUT <cluster-ip:port>/platform/12/event/

channels/<CHANNEL-ID>

Delete an event channel. DELETE <cluster-ip:port>/platform/12/event/

channels/<CHANNEL-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/event/
information about query parameters and object properties. channels?describe
GET <cluster-ip:port>/platform/12/event/
channels/<CHANNEL-ID>?describe

Event suppress resources

List, suppress, or unsuppress an event.

Operation Method and URI

Get a list of all suppressed events. GET /platform/12/event/suppress

View if an event is suppressed. GET /platform/12/event/suppress/<event type

id>

Suppress or unsuppress an event. PUT /platform/12/event/suppress/<event type

id>

View the detailed JSON schema for this resource, which has GET /platform/12/event/suppress?describe
information about query parameters and object properties.

100 System configuration API

Event eventgroup definitions resource
List eventgroup definitions.

Operation Method and URI

List all eventgroup definitions. GET <cluster-ip:port>/platform/12/event/
eventgroup-definitions

List one eventgroup definition. GET <cluster-ip:port>/

platform/12/event/eventgroup-definitions/
<EVENTGROUP-DEFINITION-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/event/
information about query parameters and object properties. eventgroup-definitions?describe
GET <cluster-ip:port>/
platform/12/event/eventgroup-definitions/
<EVENTGROUP-DEFINITION-ID>?describe

Event eventgroups occurrences resource

List or modify eventgroup occurrences.

Operation Method and URI

List all eventgroup occurrences. GET <cluster-ip:port>/platform/12/event/
eventgroup-occurrences

List one eventgroup occurrence. GET <cluster-ip:port>/

platform/12/event/eventgroup-occurrences/
<EVENTGROUP-OCCURRENCE-ID>

Modify all eventgroup occurrences (resolved or ignore all). PUT <cluster-ip:port>/platform/12/event/

eventgroup-occurrences

Modify an eventgroup occurrence. PUT <cluster-ip:port>/

platform/12/event/eventgroup-occurrences/
<EVENTGROUP-OCCURRENCE-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/event/
information about query parameters and object properties. eventgroup-occurrences?describe
GET <cluster-ip:port>/
platform/12/event/eventgroup-occurrences/
<EVENTGROUP-OCCURRENCE-ID>?describe

Event eventlists resource

List events by eventgroup occurrence.

Operation Method and URI

List all event occurrences grouped by eventgroup GET <cluster-ip:port>/platform/12/event/
occurrences. eventlists

List all events for one eventgroup occurrence. GET <cluster-ip:port>/platform/12/event/

eventlists/<EVENT-OCCURRENCE-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/event/
information about query parameters and object properties. eventlists?describe
GET <cluster-ip:port>/platform/12/event/
eventlists/<EVENT-OCCURRENCE-ID>?describe

System configuration API 101

Event events resource
Create a test event.

Operation Method and URI

Create a test event. POST <cluster-ip:port>/platform/12/event/
events

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/event/
information about query parameters and object properties. events?describe

Event settings resource

List or modify event settings.

Operation Method and URI

List all eventgroup occurrences. GET <cluster-ip:port>/platform/12/event/
settings

Modify all eventgroup occurrences (resolved or ignore all). PUT <cluster-ip:port>/platform/12/event/

settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/event/
information about query parameters and object properties. settings?describe

HealthCheck
The HealthCheck feature enables you to evaluate the status of specific software and hardware components of the cluster and
the cluster's environment.
Aspects of the cluster or its environment that can be evaluated are called items. Depending on the nature of the item, when
the item is evaluated, either each node in the cluster is checked or the cluster as a whole is checked. For example, an item
that evaluates the number of DIMM errors that have been logged checks the logs in to each node in the cluster. An item that
evaluates the amount of free space remaining on the cluster evaluates the cluster as a whole.
Parameters are elements of items to which you can assign specific values. For example, the item auth_ad_clock_skew
contains a parameter that is named ad_provider. You can assign a value such as win_ad to the ad_provider parameter
using the healthcheck/parameters/<ID> call.
Items and checklists can be evaluated according to a defined schedule. When an item or checklist is evaluated, the results are
saved in the /ifs/.ifsvar/modules/health-check/results/evaluations directory.

HealthCheck resources

You can retrieve, create, modify, or delete HealthCheck configurations and settings.

HealthCheck evaluations resource

List all HealthCheck evaluations. Create, retrieve, modify, and delete an evaluation.

Operation Method and URI

Retrieve all evaluations. GET <cluster-ip:port>/platform/12/
healthcheck/evaluations

Create an evaluation. POST <cluster-ip:port>/platform/12/

healthcheck/evaluations

Retrieve an evaluation. GET <cluster-ip:port>/platform/12/

healthcheck/evaluations/<ID>

102 System configuration API

Operation Method and URI
Modify an evaluation. PUT <cluster-ip:port>/platform/12/
healthcheck/evaluations/<ID>

Delete an evaluation. DELETE <cluster-ip:port>/platform/12/

healthcheck/evaluations/<ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. healthcheck/evaluations?describe
GET <cluster-ip:port>/platform/12/
healthcheck/evaluations/<ID>?describe

HealthCheck items resource

List all HealthCheck item definitions, or view a specific item definition.

Operation Method and URI

Retrieve all items. GET <cluster-ip:port>/platform/12/
healthcheck/items

Retrieve an item. GET <cluster-ip:port>/platform/12/

healthcheck/items/<ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. healthcheck/items?describe
GET <cluster-ip:port>/platform/12/
healthcheck/items/<ID>?describe

HealthCheck parameters resource

List all HealthCheck parameters. Create, retrieve, modify, and delete a parameter.

Operation Method and URI

Retrieve all parameters. GET <cluster-ip:port>/platform/12/
healthcheck/parameters

Create a parameter. POST <cluster-ip:port>/platform/12/

healthcheck/parameters

Retrieve a parameter. GET <cluster-ip:port>/platform/12/

healthcheck/parameters/<ID>

Modify a parameter. PUT <cluster-ip:port>/platform/12/

healthcheck/parameters/<ID>

Delete a parameter. DELETE <cluster-ip:port>/platform/12/

healthcheck/parameters/<ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. healthcheck/parameters?describe
GET <cluster-ip:port>/platform/12/
healthcheck/parameters/<ID>?describe

System configuration API 103

HealthCheck schedules resource
List all HealthCheck schedules. Create, retrieve, modify, and delete a schedule.

Operation Method and URI

Retrieve a list of schedules. GET <cluster-ip:port>/platform/12/
healthcheck/schedules

Create a schedule. POST <cluster-ip:port>/platform/12/

healthcheck/schedules

Retrieve a schedule. GET <cluster-ip:port>/platform/12/

healthcheck/schedules/<ID>

Modify a schedule. PUT <cluster-ip:port>/platform/12/

healthcheck/schedules/<ID>

Delete a schedule. DELETE <cluster-ip:port>/platform/12/

healthcheck/schedules/<ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. healthcheck/schedules?describe
GET <cluster-ip:port>/platform/12/
healthcheck/schedules/<ID>?describe

Snapshots overview
A OneFS snapshot is a logical pointer to data that is stored on a cluster at a specific point in time.
A snapshot references a directory on a cluster, including all data stored in the directory and its subdirectories. If the data
referenced by a snapshot is modified, the snapshot stores a physical copy of the data that was modified. Snapshots are created
according to user specifications or are automatically generated by OneFS to facilitate system operations.
To create and manage snapshots, you must activate a SnapshotIQ license on the cluster. Some applications must generate
snapshots to function but do not require you to activate a SnapshotIQ license; by default, these snapshots are automatically
deleted when OneFS no longer needs them. However, if you activate a SnapshotIQ license, you can retain these snapshots. You
can view snapshots that are generated by other modules without activating a SnapshotIQ license.
You can identify and locate snapshots by name or ID. A snapshot name is specified by a user and assigned to the virtual
directory that contains the snapshot. A snapshot ID is a numerical identifier that OneFS automatically assigns to a snapshot.

Snapshots resources
You can retrieve, create, modify, or delete snapshot configurations and settings.

Snapshot license resource

Retrieve license information for SnapshotIQ.

Operation Method and URI

Retrieve license information for SnapshotIQ. GET <cluster-ip:port>/platform/12/snapshot/
license

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/snapshot/
information about query parameters and object properties. license?describe

104 System configuration API

Snapshot summary resource
Retrieve summary information about file system snapshots.

Operation Method and URI

Get summary information about file system snapshots. GET <cluster-ip:port>/platform/12/snapshot/
snapshots-summary

View the detailed JSON schema for this resource, which GET <cluster-ip:port>/platform/12/snapshot/
has information about query parameters and object snapshots-summary?describe
properties.

Snapshots resource
Create, modify, delete, or retrieve information about file system snapshots.

Operation Method and URI

Retrieve a list of all snapshots. GET <cluster-ip:port>/platform/12/snapshot/snapshots

Retrieve a single snapshot. GET <cluster-ip:port>/platform/12/snapshot/snapshots/<ID|

SNAPSHOT-NAME>

Create a snapshot. POST <cluster-ip:port>/platform/12/snapshot/snapshots

Modify a snapshot. PUT <cluster-ip:port>/platform/12/snapshot/snapshots/<ID|

SNAPSHOT-NAME>

Delete all snapshots. DELETE <cluster-ip:port>/platform/12/snapshot/snapshots

Delete a snapshot. DELETE <cluster-ip:port>/platform/12/snapshot/snapshots/

<ID|SNAPSHOT-NAME>

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/snapshot/snapshots/<ID|

resource, which has information about SNAPSHOT-NAME>?describe
query parameters and object properties.
GET <cluster-ip:port>/platform/12/snapshot/snapshots?
describe

Snapshot schedules resource

Create, modify, delete, or retrieve information about snapshot schedules.

Operation Method and URI

Retrieve a list of all snapshot schedules. GET <cluster-ip:port>/platform/12/snapshot/schedules

Retrieve a single snapshot schedule. GET <cluster-ip:port>/platform/12/snapshot/schedules/

<SCHEDULE-ID>

Create a snapshot schedule. POST <cluster-ip:port>/platform/12/snapshot/schedules

Modify a snapshot schedule. PUT <cluster-ip:port>/platform/12/snapshot/schedules/

<SCHEDULE-ID>

Delete all snapshot schedules. DELETE <cluster-ip:port>/platform/12/snapshot/

schedules

Delete a snapshot schedule. DELETE <cluster-ip:port>/platform/12/snapshot/

schedules/<SCHEDULE-ID>

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/snapshot/schedules?

resource, which has information about query describe
parameters and object properties.
GET <cluster-ip:port>/platform/12/snapshot/schedules/
<SCHEDULE-ID>?describe

System configuration API 105

Snapshot locks resource
Create, modify, remove, or retrieve information about locks on an individual snapshot.

Operation Method and URI

Retrieve a list of locks on a snapshot. GET <cluster-ip:port>/platform/12/snapshot/snapshots/<ID|
SNAPSHOT-NAME>/locks

Retrieve a single lock on a snapshot. GET <cluster-ip:port>/platform/12/snapshot/snapshots/<ID|

SNAPSHOT-NAME>/locks/<LOCK-ID>

Create a lock on a snapshot. POST <cluster-ip:port>/platform/12/snapshot/snapshots/<ID|

SNAPSHOT-NAME>/locks

Modify a lock on a snapshot. PUT <cluster-ip:port>/platform/12/snapshot/snapshots/<ID|

SNAPSHOT-NAME>/locks/<LOCK-ID>

Remove a lock from a snapshot. DELETE <cluster-ip:port>/platform/12/snapshot/snapshots/

<LOCK-ID>/locks

View the detailed JSON schema for GET <cluster-ip:port>/platform/12/snapshot/snapshots/<ID|

this resource, which has information SNAPSHOT-NAME>/locks/<LOCK-ID>?describe
about query parameters and object
properties. GET <cluster-ip:port>/platform/12/snapshot/snapshots/<ID|
SNAPSHOT-NAME>/locks?describe

Snapshot pending resource

Retrieve information about scheduled snapshots.

Operation Method and URI

Retrieve a list of scheduled pending snapshots. GET <cluster-ip:port>/platform/12/snapshot/
pending

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/snapshot/
information about query parameters and object properties. pending?describe

Snapshot aliases resource

Create, modify, delete, or retrieve information about snapshot aliases.

Operation Method and URI

Get all snapshot aliases. GET <cluster-ip:port>/platform/12/snapshot/
aliases

Get a snapshot alias. GET <cluster-ip:port>/platform/12/snapshot/

aliases/<ID|SNAPSHOT-NAME>

Create a snapshot alias. POST <cluster-ip:port>/platform/12/snapshot/

aliases

Modify a snapshot alias. PUT <cluster-ip:port>/platform/12/snapshot/

aliases/<ID|SNAPSHOT-NAME>

Delete all snapshot aliases. DELETE <cluster-ip:port>/platform/12/

snapshot/aliases/

Delete a snapshot alias. DELETE <cluster-ip:port>/platform/12/

snapshot/aliases/<ID|SNAPSHOT-NAME>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/snapshot/
information about query parameters and object properties. aliases?describe

106 System configuration API

Operation Method and URI
GET <cluster-ip:port>/platform/12/snapshot/
aliases/<ID|SNAPSHOT-NAME>?describe

Snapshot changelists resource

Delete or retrieve information about snapshot changelists.

Operation Method and URI

Retrieve all snapshot changelists. GET <cluster-ip:port>/platform/12/snapshot/
changelists

Retrieve a snapshot changelist. GET <cluster-ip:port>/platform/12/snapshot/

changelists/<changelist>

Delete a snapshot changelist. DELETE <cluster-ip:port>/platform/12/

snapshot/changelists/<changelist>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/snapshot/
information about query parameters and object properties. changelists?describe

Snapshot changelists changelist lins resource

Retrieve information about a snapshot changelist entry.

Operation Method and URI

Retrieve a collection of snapshot changelist entries. GET <cluster-ip:port>/platform/12/snapshot/
changelists/<CHANGELIST>/lins

Retrieve a snapshot changelist entry for a specific LIN. GET <cluster-ip:port>/platform/12/snapshot/

changelists/<CHANGELIST>/lins/<LIN>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/snapshot/
information about query parameters and object properties. changelists/<CHANGELIST>/lins?describe
GET <cluster-ip:port>platform/12/snapshot/
changelists/<CHANGELIST>/lins/<LIN>?describe

Snapshot changelists changelist resource

Retrieve information about a snapshot changelist entry.
The call snapshot/changelists/<CHANGELIST>/diff-regions/<LIN> returns information about data block changes
between two snapshot versions of a file.

Operation Method and URI

Retrieve a snapshot changelist entry. GET <cluster-ip:port>/platform/12/snapshot/
changelists/<CHANGELIST>/entries/<ID>

Retrieve a collection of snapshot changelist entries. GET <cluster-ip:port>/platform/12/snapshot/

changelists/<CHANGELIST>/entries

Retrieve a collection of snap diff regions for a specified LIN. GET <cluster-ip:port>/platform/12/snapshot/
changelists/<CHANGELIST>/diff-regions/<LIN>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>platform/12/
information about query parameters and object properties. snapshot/changelists/<CHANGELIST>/entries/
<ID>?describe
GET <cluster-ip:port>/platform/12/snapshot/
changelists/<CHANGELIST>/entries?describe

System configuration API 107

Operation Method and URI
GET <cluster-ip:port>/platform/12/snapshot/
changelists/<CHANGELIST>/diff-regions/<LIN>?
describe

Snapshot repstates resource

Create or retrieve information about snapshot repstates.

Operation Method and URI

Retrieve all snapshot repstates. GET <cluster-ip:port>/platform/12/snapshot/
repstates

Retrieve a snapshot repstate. GET <cluster-ip:port>/platform/12/snapshot/

repstates/<REPSTATE>

Create a snapshot repstate. POST <cluster-ip:port>/platform/12/snapshot/

repstates/<REPSTATE>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/snapshot/
information about query parameters and object properties. repstates?describe
GET <cluster-ip:port>/platform/12/snapshot/
repstates/<REPSTATE>?describe

Snapshot settings resource

Modify or retrieve information about global snapshot settings.

Operation Method and URI

Retrieve the current snapshot settings. GET <cluster-ip:port>/platform/12/snapshot/
settings

Modify the current snapshot settings. PUT <cluster-ip:port>/platform/12/snapshot/

settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/snapshot/
information about query parameters and object properties. settings?describe

Snapshots API examples

You can see examples for some snapshots API requests.

Create a snapshot
You can create a snapshot.

Request example

POST /platform/12/snapshot/snapshots
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"name" : "admin_snap",
"path" : "/ifs/home/admin"
}

108 System configuration API

Response example

201 Created
Content-type: application/json

{
"created": 1589486376,
"expires": null,
"has_locks": false,
"id": 2,
"name": "admin_snap",
"path": "/ifs/home/admin",
"pct_filesystem": 6.816916993557243e-06,
"pct_reserve": 0.0,
"schedule": null,
"shadow_bytes": 0,
"size": 4096,
"state": "active",
"target_id": null,
"target_name": null
}

Modify a snapshot alias

You can modify a snapshot alias.

Request example

PUT /platform/12/snapshot/aliases/AdminSnapshot
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"name" : "InitialAdminSnapshot"
}

Response example
No message body is returned for this request.

204 No Content
Content-type: text/plain

NDMP backup and recovery

In OneFS, you can back up and recover file-system data through the Network Data Management Protocol (NDMP). From a
backup server, you can direct backup and recovery processes between a cluster and backup devices such as tape devices,
media servers, and virtual tape libraries (VTLs).
OneFS supports both three-way and two-way NDMP backup models.
Two-way NDMP backup is faster than the three-way NDMP backup. It is also the most efficient method in terms of cluster
resource consumption. However, a two-way NDMP backup requires that you attach one or more Backup Accelerator nodes to
the cluster.
In both the two-way and three-way NDMP backup models, file history data is transferred from the cluster to the backup server.
Before a backup begins, OneFS creates a snapshot of the targeted directory, then backs up the snapshot, which ensures that
the backup image represents a specific point in time.
You do not must activate a SnapshotIQ license on the cluster to perform NDMP backups. If you have activated a SnapshotIQ
license on the cluster, you can generate a snapshot through the SnapshotIQ tool, and then back up the same snapshot. If you
back up a SnapshotIQ snapshot, OneFS does not create another snapshot for the backup.
NOTE: If you are recovering SmartLock directories, Dell Technologies recommends that you do not specify autocommit
time periods for them.

System configuration API 109

You can also back up WORM domains through NDMP.

NDMP resources
You can retrieve, create, modify, or delete NDMP configurations and settings.

NDMP backup contexts

Retrieve information about NDMP backup contexts.

Operation Method and URI

Retrieve NDMP backup contexts. GET <cluster-ip:port>/platform/12/protocols/ndmp/
contexts/backup

Retrieve a specific NDMP backup context. GET <cluster-ip:port>/platform/12/protocols/ndmp/

contexts/backup/<ID>

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/ndmp/
which has information about query parameters contexts/backup?describe
and object properties.

NDMP BRE contexts

Retrieve information about backup restartable extension (BRE) contexts.

Operation Method and URI

Retrieve NDMP BRE contexts. GET <cluster-ip:port>/platform/12/protocols/ndmp/
contexts/bre

Retrieve a specific NDMP BRE context. GET <cluster-ip:port>/platform/12/protocols/ndmp/

contexts/bre/<ID>

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/ndmp/
which has information about query parameters contexts/bre?describe
and object properties.

NDMP restore contexts

Retrieve information about NDMP restore contexts.

Operation Method and URI

Retrieve NDMP restore contexts. GET <cluster-ip:port>/platform/12/protocols/ndmp/
contexts/restore

Retrieve a specific NDMP restore context. GET <cluster-ip:port>/platform/12/protocols/ndmp/

contexts/restore/<ID>

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/ndmp/
which has information about query parameters contexts/restore?describe
and object properties.

NDMP diagnostics
Retrieve or modify NDMP diagnostic information.

Operation Method and URI

Retrieve NDMP diagnostic information. GET <cluster-ip:port>/platform/12/protocols/ndmp/
diagnostics

110 System configuration API

Operation Method and URI
Modify NDMP diagnostic information. PUT <cluster-ip:port>/platform/12/protocols/ndmp/
diagnostics

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/ndmp/
which has information about query parameters diagnostics?describe
and object properties.

NDMP dumpdates
Retrieve or delete information about NDMP dump dates.

Operation Method and URI

Retrieve NDMP dump date specifics. GET <cluster-ip:port>/platform/12/protocols/ndmp/
dumpdates/<path*>

Delete NDMP dump date entries. DELETE <cluster-ip:port>/platform/12/protocols/ndmp/

dumpdates/<path*>

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/ndmp/
which has information about query parameters dumpdates/<path*>?describe
and object properties.

NDMP logs
Retrieve NDMP logs.

Operation Method and URI

Retrieve NDMP logs. GET <cluster-ip:port>/platform/12/protocols/ndmp/logs

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/ndmp/
which has information about query parameters logs?describe
and object properties.

NDMP sessions
Retrieve information about NDMP sessions.

Operation Method and URI

Retrieve NDMP session information. GET <cluster-ip:port>/platform/12/protocols/ndmp/
sessions

Retrieve information about a specific NDMP GET <cluster-ip:port>/platform/12/protocols/ndmp/

session. sessions/<SESSION-ID>

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/ndmp/
which has information about query parameters sessions?describe
and object properties.

NDMP DMA settings

Retrieve a list of supported data management application (DMA) vendors.

Operation Method and URI

Retrieve a list of NDMP DMAs. GET <cluster-ip:port>/platform/12/protocols/ndmp/
settings/dmas

System configuration API 111

Operation Method and URI
View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/ndmp/
which has information about query parameters settings/dmas?describe
and object properties.

NDMP global settings

Retrieve or modify NDMP global settings.

Operation Method and URI

Retrieve NDMP global settings. GET <cluster-ip:port>/platform/12/protocols/ndmp/
settings/global

Modify NDMP global settings. PUT <cluster-ip:port>/platform/12/protocols/ndmp/

settings/global

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/ndmp/
which has information about query parameters settings/global?describe
and object properties.

NDMP preferred IP preferences resources

Retrieve, modify, create, and delete preferred IP preferences.

Operation Method and URI

Retrieve a list of preferred IP preferences. GET <cluster-ip:port>/platform/12/protocols/
ndmp/settings/preferred-ips

Retrieve a single IP preference by ID. GET <cluster-ip:port>/platform/12/protocols/

ndmp/settings/preferred-ips/<ID>

Modify a preferred IP preference. PUT <cluster-ip:port>/platform/12/protocols/

ndmp/settings/preferred-ips/<ID>

Create a preferred IP preference. POST <cluster-ip:port>/platform/12/

protocols/ndmp/settings/preferred-ips

Delete a preferred IP preference. DELETE <cluster-ip:port>/platform/12/

protocols/ndmp/settings/preferred-ips/<ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/protocols/
information about query parameters and object properties. ndmp/settings/preferred-ips?describe
GET <cluster-ip:port>/platform/12/protocols/
ndmp/settings/preferred-ips/<ID>?describe

NDMP variable settings

Create, modify, view, or delete NDMP environment variable settings.

Operation Method and URI

Retrieve list of preferred NDMP environment GET <cluster-ip:port>/platform/12/protocols/ndmp/
variables. settings/variables/<path*>

Modify preferred NDMP environment variables. PUT <cluster-ip:port>/platform/12/protocols/ndmp/

settings/variables/<path*>

Create preferred NDMP environment variables. POST <cluster-ip:port>/platform/12/protocols/ndmp/

settings/variables/<path*>

112 System configuration API

Operation Method and URI
Delete preferred NDMP environment variables. DELETE <cluster-ip:port>/platform/12/protocols/ndmp/
settings/variables/<path*>

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/ndmp/
which has information about query parameters settings/variables/<path*>?describe
and object properties.

NDMP users
List, create, modify, or delete NDMP administrators.

Operation Method and URI

Retrieve list of NDMP administrators. GET <cluster-ip:port>/platform/12/protocols/ndmp/
users

Retrieve information about a specific NDMP GET <cluster-ip:port>/platform/12/protocols/ndmp/

administrator. users/<NAME>

Modify information about an NDMP administrator. PUT <cluster-ip:port>/platform/12/protocols/ndmp/

users/<NAME>

Create an NDMP administrator. POST <cluster-ip:port>/platform/12/protocols/ndmp/

users/<NAME>

Delete an NDMP administrator. DELETE <cluster-ip:port>/platform/12/protocols/ndmp/

users/<NAME>

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/protocols/ndmp/
which has information about query parameters users?describe
and object properties.

SyncIQ data replication overview

OneFS enables you to replicate data from one PowerScale cluster to another through the SyncIQ software module. Activate a
SyncIQ license on both PowerScale clusters before you can replicate data between them.
You can replicate data at the directory level while optionally excluding specific files and subdirectories from being replicated.
SyncIQ creates and references snapshots to replicate a consistent point-in-time image of a source directory. Metadata, such as
access control lists (ACL) and alternate data streams (ADS), are replicated along with data.
SyncIQ enables you to maintain a consistent replica of your data on another PowerScale cluster and to control the frequency of
data replication. For example, you could configure SyncIQ to back up data from your primary cluster to a secondary cluster once
a day at 10 PM. Depending on the size of your dataset, the first replication operation could take considerable time. After that,
however, replication operations would complete more quickly.
SyncIQ also offers automated failover and failback capabilities so that you can continue operations on the secondary
PowerScale cluster should your primary cluster become unavailable.

Sync resources
You can retrieve, create, modify, or delete resources for data replication with SyncIQ.

File matching patterns

You can apply the following file matching pattern to filter specific objects in SyncIQ.

<file_matching_pattern> := {
"or_criteria" : [
{
"and_criteria": [
<file_criterion>,

System configuration API 113

 <file_criterion>,
...
]
},
{
"and_criteria": [
<file_criterion>,
<file_criterion>,
...
]
},
...
]
}

<file_criterion> = {
"type": <string>,
"operator": <string>,
"value": {<string> | <integer>}
}

The following table defines available operators.

operator Description

== Equal

!= Does not equal

> Greater than

>= Greater than or equal

< Less than

<= Less than or equal

! Not

The following table defines available file criteria types.

Type Conditions

name Paired with operators "==" or "!=".

path Paired with operators "==" or "!=".

posix_regex_name Paired with operators "==" or "!=".

accessed_time No operator is required; every operation is set to "==".

The value must be in the following form: {<mm>/<dd>/
<yyyy> [<HH>:<mm>] | <integer> {days | weeks | months |
years} ago}

accessed_before No operator is required; every operation is set to "==".

The value must be in the following form: {<mm>/<dd>/
<yyyy> [<HH>:<mm>] | <integer> {days | weeks | months |
years} ago}

accessed_after No operator is required; every operation is set to "==".

114 System configuration API

Type Conditions

The value must be in the following form: {<mm>/<dd>/

<yyyy> [<HH>:<mm>] | <integer> {days | weeks | months |
years} ago}

birth_time No operator is required; every operation is set to "==".

The value must be in the following form: {<mm>/<dd>/
<yyyy> [<HH>:<mm>] | <integer> {days | weeks | months |
years} ago}

birth_before No operator is required; every operation is set to "==".

The value must be in the following form: {<mm>/<dd>/
<yyyy> [<HH>:<mm>] | <integer> {days | weeks | months |
years} ago}

birth_after No operator is required; every operation is set to "==".

The value must be in the following form: {<mm>/<dd>/
<yyyy> [<HH>:<mm>] | <integer> {days | weeks | months |
years} ago}

changed_time No operator is required; every operation is set to "==".

The value must be in the following form: {<mm>/<dd>/
<yyyy> [<HH>:<mm>] | <integer> {days | weeks | months |
years} ago}

changed_before No operator is required; every operation is set to "==".

The value must be in the following form: {<mm>/<dd>/
<yyyy> [<HH>:<mm>] | <integer> {days | weeks | months |
years} ago}

changed_after No operator is required; every operation is set to "==".

The value must be in the following form: {<mm>/<dd>/
<yyyy> [<HH>:<mm>] | <integer> {days | weeks | months |
years} ago}

size Paired with all operators except for "!".

The value must be in the following form: An integer, followed
by B, KB, MB, GB, or TB (such as 100B or 12TB).

file_type Paired with operators "==" or "!=".

The value must be in the following form: 'file', 'directory', or
'symlink'.

user_name Paired with operators "==" or "!=".

user_id Paired with operators "==" or "!=".

group_name Paired with operators "==" or "!=".

group_id Paired with operators "==" or "!=".

no_user Paired with operators "!".

no_group Paired with operators "!".

Does not require a value.

System configuration API 115

The following example shows a sync policy filter.

"file_matching_filter": {
"or_criteria" : [
{
"and_criteria": [
{
"type": "size",
"operator": ">=",
"value": "500000KB"
},
{
"type": "file_type",
"operator": "==",
"value": "file"
}
]
},
{
"and_criteria": [
{
"type": "posix_regex_name",
"operator": "==",
"value": "some_special_prefix_*"
}
]
},
{
"and_criteria": [
{
"type": "file_type",
"operator": "==",
"value": "symlink"
}
]
}
]
}

Sync license resource

Retrieve license information for SyncIQ.

Operation Method and URI

Get license information for SyncIQ. GET <cluster-ip:port>/platform/12/sync/
license

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. license?describe

Sync certificates server resource

Import, modify, list, view, or delete TLS server certificates.

Operation Method and URI

List all SyncIQ TLS server certificates. GET <cluster-ip:port>/platform/12/sync/
certificates/server

View a specific SyncIQ TLS server certificate. GET <cluster-ip:port>/platform/12/sync/

certificates/server/<SERVER>

Import a SyncIQ TLS server certificate. POST <cluster-ip:port>/platform/12/sync/

certificates/server

116 System configuration API

Operation Method and URI
Modify a SyncIQ TLS server certificate. PUT <cluster-ip:port>/platform/12/sync/
certificates/server/<SERVER>

Delete a SyncIQ TLS server certificate. DELETE <cluster-ip:port>/platform/12/sync/

certificates/server/<SERVER>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. certificates/server?describe
GET <cluster-ip:port>/platform/12/sync/
certificates/server/<SERVER>?describe

Sync certificates peer resource

Import, modify, list, view, or delete SyncIQ peer TLS certificates.

Operation Method and URI

List all trusted SyncIQ peer TLS certificates. GET <cluster-ip:port>/platform/12/sync/
certificates/peer

View a specific SyncIQ peer TLS certificate. GET <cluster-ip:port>/platform/12/sync/

certificates/peer/<PEER>

Import a trusted SyncIQ TLS certificate. POST <cluster-ip:port>/platform/12/sync/

certificates/peer

Modify a trusted SyncIQ TLS certificate. PUT <cluster-ip:port>/platform/12/sync/

certificates/peer/<PEER>

Delete a trusted SyncIQ TLS certificate. DELETE <cluster-ip:port>/platform/12/sync/

certificates/peer/<PEER>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. certificates/peer?describe
GET <cluster-ip:port>/platform/12/sync/
certificates/peer/<PEER>?describe

Sync jobs resource

Start, modify, or retrieve information about a SyncIQ replication job.

Operation Method and URI

Retrieve a list of all replication jobs. GET <cluster-ip:port>/platform/12/sync/
jobs

Retrieve the details of a replication job. GET <cluster-ip:port>/platform/12/sync/

jobs/<JOB>

Start a replication job. POST <cluster-ip:port>/platform/12/

sync/jobs

Modify an in-progress replication job. PUT <cluster-ip:port>/platform/12/sync/

jobs/<JOB>

Cancel all replication jobs. DELETE <cluster-ip:port>/platform/12/

sync/jobs

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. jobs?describe
GET <cluster-ip:port>/platform/12/sync/
jobs/<JOB>?describe

System configuration API 117

Sync policies resource
Create, modify, delete, or retrieve information about SyncIQ replication policies.

Operation Method and URI

Retrieve all replication policies. GET <cluster-ip:port>/platform/12/sync/
policies

Retrieve a replication policy. GET <cluster-ip:port>/platform/12/sync/

policies/<POLICY>

Create a replication policy. POST <cluster-ip:port>/platform/12/sync/

policies

Modify a replication policy. PUT <cluster-ip:port>/platform/12/sync/

policies/<POLICY>

Delete all replication policies. DELETE <cluster-ip:port>/platform/12/sync/

policies

Delete a replication policy. DELETE <cluster-ip:port>/platform/12/sync/

policies/<POLICY>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. policies?describe
GET <cluster-ip:port>/platform/12/sync/
policies/<POLICY>?describe

Sync policies reset resource

Reset the incremental state of a replication policy and force a full sync or copy. Post an empty object: {} to reset the policy.

Operation Method and URI

Reset a replication policy. POST <cluster-ip:port>/platform/12/sync/
policy/<POLICY>/reset

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. policy/<POLICY>/reset?describe

Sync reports resource

Retrieve SyncIQ reports and subreports.

Operation Method and URI

Retrieve all SyncIQ reports. GET <cluster-ip:port>/platform/12/sync/
reports

Retrieve a single SyncIQ report. GET <cluster-ip:port>/platform/12/sync/

reports/<REPORT>

Retrieve a list of SyncIQ subreports for a report. GET <cluster-ip:port>/platform/12/sync/

reports/<REPORT>/subreports

Retrieve a single SyncIQ subreport. GET <cluster-ip:port>/platform/12/sync/

reports/<REPORT>/subreports/<SUBREPORT-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. reports?describe
GET <cluster-ip:port>/platform/12/sync/
reports/<REPORT>?describe

118 System configuration API

Operation Method and URI
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. reports/<REPORT>/subreports?describe
GET <cluster-ip:port>/platform/12/
sync/reports/<REPORT>/subreports/<SUBREPORT-
ID>?describe

Sync reports rotate resource

Rotate the records in the database and periodically remove older reports from the system.

Operation Method and URI

Retrieve information about whether the rotation is running. GET <cluster-ip:port>/platform/12/sync/
reports-rotate

Force the reports in the database to rotate. POST <cluster-ip:port>/platform/12/sync/

reports-rotate

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. reports-rotate?describe

Sync target policies resource

Retrieve information about SyncIQ target replication policies.

Operation Method and URI

Retrieve all target replication policies. GET <cluster-ip:port>/platform/12/sync/
target/policies

Retrieve a target replication policy. GET <cluster-ip:port>/platform/12/sync/

target/policies/<policy-id>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. target/policies?describe

Sync target policies cancel resource

Cancels the most recent replication job for a replication policy from the target cluster.

Operation Method and URI

Cancel the most recent replication job. POST <cluster-ip:port>/platform/12/sync/
target/policies/<POLICY>/cancel

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. target/policies/<POLICY>/cancel?describe

SyncIQ target reports resource

Retrieve information about the SyncIQ reports and subreports running on a target cluster.

Operation Method and URI

Retrieve all replication target reports. GET <cluster-ip:port>/platform/12/sync/
target/reports

Retrieve a replication target report. GET <cluster-ip:port>/platform/12/sync/

target/reports/<REPORT>

System configuration API 119

Operation Method and URI
Retrieve all target subreports for a single report. GET <cluster-ip:port>/platform/12/sync/
target/reports/<REPORT>/subreports

Retrieve a single target subreport. GET

<cluster-ip:port>/platform/12/sync/target/
reports/<REPORT>/subreports/<SUBREPORT-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. target/reports?describe
GET <cluster-ip:port>/platform/12/sync/
target/reports/<REPORT>?describe

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. target/reports/<REPORT>/subreports?describe
GET
<cluster-ip:port>/platform/12/sync/target/
reports/<REPORT>/subreports/<SUBREPORT-ID>?
describe

Sync service policies resource

List, view, create, modify, or delete SyncIQ service replication policies.

Operation Method and URI

List all SyncIQ service replication policies. GET <cluster-ip:port>/platform/12/sync/
service/policies

View a specific SyncIQ service replication policy. GET <cluster-ip:port>/platform/12/sync/

service/policies/<POLICY>

Import a SyncIQ service replication policy. POST <cluster-ip:port>/platform/12/sync/

service/policies

Modify a SyncIQ service replication policy. PUT <cluster-ip:port>/platform/12/service/

policies/<POLICY>

Delete SyncIQ service replication policies. DELETE <cluster-ip:port>/platform/12/sync/

service/policies

Delete a specific SyncIQ service replication policy. DELETE <cluster-ip:port>/platform/12/sync/

service/policies/<POLICY>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. service/policies?describe
GET <cluster-ip:port>/platform/12/sync/
service/policies/<POLICY>?describe

Sync service policies reset resource

Reset a SyncIQ service replication policy incremental state, and force a full sync, or copy.

Operation Method and URI

Import a SyncIQ service replication policy. POST <cluster-ip:port>/platform/12/sync/
service/policies/<POLICY>/reset

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. service/policies/<POLICY>/reset?describe

120 System configuration API

Sync service target policies reset resource
View or break association with replication policies on the SyncIQ target.

Operation Method and URI

List all SyncIQ target service replication policies. GET <cluster-ip:port>/platform/12/sync/
service/target/policies

View a specific SyncIQ target service replication policy. GET <cluster-ip:port>/platform/12/sync/

service/target/policies/<POLICY>

Break association with a specific SyncIQ target service policy. DELETE <cluster-ip:port>/platform/12/sync/
service/target/policies/<POLICY>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. service/target/policies?describe
GET <cluster-ip:port>/platform/12/sync/
service/target/policies/<POLICY>?describe

Sync service target policies cancel resource

Cancel the most recent SyncIQ job for a service replication policy from the target.

Operation Method and URI

Cancel a SyncIQ job for a service replication policy from the POST <cluster-ip:port>/platform/12/sync/
target. service/target/policies/<POLICY>/cancel

View the detailed JSON schema for this resource, which has GET
information about query parameters and object properties. <cluster-ip:port>/platform/12/sync/service/
target/policies/<POLICY>/cancel?describe

Sync rules resource

Create, delete, or retrieve information about SyncIQ replication job performance rules. Rules can restrict the amount of network
bandwidth or files that are transferred per second for replication policies.

Operation Method and URI

Retrieve all replication job performance rules. GET <cluster-ip:port>/platform/12/sync/rules

Create a replication job performance rule. POST <cluster-ip:port>/platform/12/sync/

rules

Modify a replication job performance rule. PUT <cluster-ip:port>/platform/12/sync/

rules/<RULE>

Delete all replication job performance rules. DELETE <cluster-ip:port>/platform/12/sync/

rules/

Delete all replication job performance rules by type. DELETE <cluster-ip:port>/platform/12/sync/

rules?type=<STRING>

Delete a replication job performance rule. DELETE <cluster-ip:port>/platform/12/sync/

rules/<RULE>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. rules?describe
GET <cluster-ip:port>/platform/12/sync/
rules/<RULE>?describe

System configuration API 121

Sync settings resource
Modify or retrieve information about global SyncIQ settings.

Operation Method and URI

Retrieve global SyncIQ settings. GET <cluster-ip:port>/platform/12/sync/
settings

Modify global SyncIQ settings. PUT <cluster-ip:port>/platform/12/sync/

settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. settings?describe

NOTE: You can configure RPO alert time through preferred_rpo_alert property of SyncIQ settings. For example
when the preferred_rpo_alert is set to null, it sets preferences as Do not send RPO alerts. When the
preferred_rpo_alert is set to 172800, it sets preferences as Send RPO alerts after 2 days.

Sync advanced settings resource

Modify or retrieve information about advanced global SyncIQ settings.

Operation Method and URI

Retrieve advanced global SyncIQ settings. GET <cluster-ip:port>/platform/12/sync/
settings/advanced

Modify advanced global SyncIQ settings. PUT <cluster-ip:port>/platform/12/sync/

settings/advanced

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. settings/advanced?describe

Sync history CPU resource

Retrieve CPU performance data.

Operation Method and URI

Retrieve CPU performance data. GET <cluster-ip:port>/platform/12/sync/
history/cpu

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. history/cpu?describe

Sync history file resource

Retrieve information about OneFS replication job performance reports. These reports indicate the number of files per second
that are sent by replication policies at a given time.

Operation Method and URI

Get all replication job performance reports. GET <cluster-ip:port>/platform/12/sync/
history/file

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. history/file?describe

122 System configuration API

Sync history network resource
Retrieve information about OneFS replication job performance reports. These reports indicate the amount of network bandwidth
that is consumed by data replication policies at a given time.

Operation Method and URI

List network operations performance data. GET <cluster-ip:port>/platform/12/sync/
history/network

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. history/network?describe

Sync history worker resource

Retrieve worker performance data.

Operation Method and URI

Retrieve worker performance data. GET <cluster-ip:port>/platform/12/sync/
history/worker

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/sync/
information about query parameters and object properties. history/worker?describe

SyncIQ API examples

You can see examples for some SyncIQ API calls.

Start a replication job

Manually start a replication job on the system.

Request example

POST /platform/12/sync/jobs
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'id': 'testpol'
}

Response example

201 Created
Content-type: application/json,
Allow: 'GET, POST, HEAD'

{
"id":"testpol"
}

System configuration API 123

Modify a replication job
Pause, cancel, or restart a job.

Request example
You can only modify the state object property for a replication job. Options are pause, cancel, and restart.

PUT /platform/12/sync/jobs/testpol
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'state': cancel,
}

Response example

204 No Content
Content-type: text/plain,
Allow: 'GET, PUT'

Create a replication policy

You can create a replication policy on the file system.

Request example

POST /platform/12/sync/policies
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'log_level': 'fatal',
'name': 'myNewPolicy',
'schedule': 'every 3 weeks',
'source_root_path': '/ifs/data/sync2',
'target_path': '/ifs/data/sync/target2',
'action': 'copy',
'report_max_count': 144,
'source_exclude_directories': ['/ifs/data/sync2/exclude'],
'source_include_directories': ['/ifs/data/sync2/include'],
'target_host': 'localhost'
}

Response examples
In the following example, the request was successful and a replication policy ID is returned for the created object.

201 Created
Content-type: application/json,
Allow: 'DELETE, GET, POST, HEAD'

{
"id":"a33006f364842eefb629fc6b95c92559"
}

In following example, the replication policy was not created and an error was returned.

500 Internal Server Error

Content-type: application/json,
Allow: 'DELETE, GET, POST, HEAD'

{
"errors":[
{

124 System configuration API

 "code":"AEC_EXCEPTION",
"message":"duplicate policy <name,type> entry with id=\'(null)\',
name=\'myNewPolicy\'"
}
]
}

Modify a replication policy

You can modify a replication policy on the file system.

Request example

PUT /platform/12/sync/policies/myNewPolicy
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'target_compare_initial_sync': True,
'enabled': True,
'description': 'New policy',
'target_host': 'newHostname'
}

Response examples
The request was successful. No message body is returned for this request.

204 No Content
content-type: text/plain,
allow: 'DELETE, GET, PUT, HEAD'

In the following example, the policy was not modified and an error message was returned.

500 Internal Server Error

Content-type: application/json,
Allow: 'DELETE, GET, PUT, HEAD'

{
"errors":[
{
"code":"AEC_BAD_REQUEST",
"field":"source_network",
"message":"Flexnet subnet not found"
}
]
}

Reset a replication policy

Reset a replication policy and force a full sync and copy replication job.

Request example

POST /platform/12/sync/policy/testPolicy/reset
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Response example

201 Created
Content-type: application/json,
Allow: 'POST'

System configuration API 125

 "id":"5275f97ebb3892ed4a47f71de20d4609"
}

Force rotation for reports

Manually start rotation for the records in the database, which deletes reports that are older than the specified maximum
retention period.

Request example

POST /platform/12/sync/reports-rotate
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Response example

201 Created
Content-type: application/json,
Allow: 'DELETE, GET, POST, HEAD'

{
"id":"a33006f364842eefb629fc6b95c92559"
}

Cancel a target replication policy

You can cancel a replication policy from the target cluster.

Request example

POST /platform/12/sync/target/policies/testpol/cancel
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Response example

200 OK
Content-type: application/json,
Allow: 'DELETE, GET, PUT, HEAD'

{
"policies" :
[

{
"failover_failback_state" : "writes_disabled",
"id" : "021a24618064135c5df4c431fd132437",
"last_job_state" : "paused",
"last_source_coordinator_ip" : "127.0.0.1",
"last_update_from_source" : 1371769450,
"legacy_policy" : false,
"name" : "testpol",
"source_cluster_guid" : "005056300217c137c2512b163880cb4d843d",
"source_host" : "jgregory",
"target_path" : "/ifs/data/tgt"
}
]
}

126 System configuration API

Create a replication policy rule on the system
You can create a replication policy rule on the file system.

Request example

POST /platform/12/sync/rules
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'type': 'file_count',
'limit': 123,
'schedule':
{
'begin': '09:00',
'end': '17:00',
'monday': True,
'tuesday': True,
'friday': True,
'wednesday': True,
'thursday': True,
'sunday': False,
'saturday': False
}
}

Response example

201 Created
Content-type: application/json,
Allow: 'DELETE, GET, POST, HEAD'

{
"id":"fc-0"
}

Modify a replication policy rule

You can modify replication policy rules on the system.

Request example

PUT /platform/12/sync/rules/
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Response example

204 No Content
Content-type: text/plain,
Allow: 'DELETE, GET, PUT, POST'

Modify SyncIQ settings

You can modify the SyncIQ settings on the system.

Request example

PUT /platform/12/sync/settings
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

System configuration API 127

 {
'report_max_count': 1234,
'service': 'on'
}

Response example

204 No Content
Content-type: text/plain,
Allow: 'DELETE, GET, PUT, HEAD'

SmartLock overview
With the SmartLock software module, you can protect files on a PowerScale cluster from being modified, overwritten, or
deleted. To protect files in this manner, you must activate a SmartLock license.
With SmartLock, you can identify a directory in OneFS as a WORM domain. WORM stands for write once, read many. All files
within the WORM domain can be committed to a WORM state, meaning that those files cannot be overwritten, modified, or
deleted.
After a file is removed from a WORM state, you can delete the file. However, you can never modify a file that has been
committed to a WORM state, even after it is removed from a WORM state.
In OneFS, SmartLock can be deployed in one of two modes: compliance mode or enterprise mode.

SmartLock resources
You can retrieve, create, or modify SmartLock configurations and settings.

SmartLock domains resource

Create, modify, or retrieve information about a SmartLock domain.

Operation Method and URI

Retrieve all SmartLock domains. GET <cluster-ip:port>/platform/12/worm/
domains

Retrieve a SmartLock domain. GET <cluster-ip:port>/platform/12/worm/

domains/<domain>

Create a SmartLock domain. POST <cluster-ip:port>/platform/12/worm/

domains

Modify a SmartLock domain. PUT <cluster-ip:port>/platform/12/worm/

domains/<domain>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/worm/
information about query parameters and object properties. domains?describe
GET <cluster-ip:port>/platform/12/worm/
domains?describe

SmartLock settings resource

Modify or retrieve information about SmartLock global settings.

Operation Method and URI

Retrieve SmartLock global settings. GET <cluster-ip:port>/platform/12/worm/
settings

128 System configuration API

Operation Method and URI
Modify SmartLock global settings. PUT <cluster-ip:port>/platform/12/worm/
settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/worm/
information about query parameters and object properties. settings?describe

SmartLock API examples

You can see examples for some SmartLock API requests.

Create a SmartLock
You can create a SmartLock domain.

Request example

POST /platform/12/worm/domains
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"path":"/ifs/test/domain_test"
}

Response example

201 Created
Content-type: application/json

{
"id" : "224731515-4837484-928237-1003"
}

Modify a SmartLock
You can modify a SmartLock domain.

Request example

PUT /platform/12/worm/domains/domaintest
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"privileged_delete":"on"}

Response example
No message body is returned for this request.

204 No Content
Content-type: text/plain

System configuration API 129

Modify SmartLock settings
You can modify SmartLock settings.

Request example
In this example, you can set the compliance clock to the current system time. Do this task by sending a PUT request to this
resource with an empty JSON object {} for the cdate value. This cluster must be in compliance mode to set the compliance
clock.

PUT /platform/12/worm/domains/settings
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"cdate" : }

Response example
No message body is returned for this request.

204 No Content
Content-type: text/plain

Deduplication overview
SmartDedupe enables you to save storage space on your cluster by reducing redundant data. Deduplication maximizes the
efficiency of your cluster by decreasing the amount of storage that is required to store multiple files with identical blocks.
The SmartDedupe software module deduplicates data by scanning a PowerScale cluster for identical data blocks. Each block is
8 KB. If SmartDedupe finds duplicate blocks, SmartDedupe moves a single copy of the blocks to a hidden file called a shadow
store. SmartDedupe then deletes the duplicate blocks from the original files and replaces the blocks with pointers to the shadow
store.
Deduplication is applied at the directory level, targeting all files and directories underneath one or more root directories.
SmartDedupe not only deduplicates identical blocks in different files, it also deduplicates identical blocks within a single file.
Before you deduplicate a directory, you can get an estimate of the amount of space you can expect to save. After you begin
deduplicating a directory, you can monitor the amount of space that deduplication is saving in real time.
To enable deduplicating two or more files, the files must have the same disk pool policy ID and protection policy. If either or both
of these attributes differ between two or more identical files, or files with identical 8 K blocks, the files are not deduplicated.
Because it is possible to specify protection policies on a per-file or per-directory basis, deduplication can be further
affected. Consider the example of two files, /ifs/data/projects/alpha/logo.jpg and /ifs/data/projects/
beta/logo.jpg. Even if the logo.jpg files in both directories are identical, they would not be deduplicated if they have
different protection policies.
If you have activated a SmartPools license on your cluster, you can also specify custom file pool policies. These file pool policies
might result in identical files or files with identical 8 K blocks being stored in different node pools. Those files would have
different disk pool policy IDs and would not be deduplicated.
SmartDedupe also does not deduplicate files that are 32 KB or smaller, because doing so would consume more cluster resources
than the storage savings are worth. The default size of a shadow store is 2 GB. Each shadow store can contain up to 256,000
blocks. Each block in a shadow store can be referenced up to 32,000 times.

Deduplication resources
You can retrieve, create, modify, or delete SmartDedupe configurations and settings.

130 System configuration API

Deduplication summary resource
Retrieve summary information about deduplication jobs.

Operation Method and URI

Retrieve a summary of deduplication jobs. GET <cluster-ip:port>platform/12/dedupe/

dedupe-summary

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/dedupe/
information about query parameters and object properties. dedupe-summary?describe

Deduplication inline settings resource

Get and modify the inline deduplication settings.

Operation Method and URI

Get the inline deduplication settings. GET <cluster-ip:port>platform/12/dedupe/
inline/settings

Modify the inline deduplication settings. PUT <cluster-ip:port>/platform/12/dedupe/

inline/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/dedupe/
information about query parameters and object properties. inline/settings?describe

Deduplication settings resource

Modify or retrieve information about OneFS deduplication settings.

Operation Method and URI

Get deduplication settings. GET <cluster-ip:port>/platform/12/dedupe/
settings

Modify deduplication settings. PUT <cluster-ip:port>/platform/12/dedupe/

settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/dedupe/
information about query parameters and object properties. settings?describe

Deduplication reports resource

Retrieve information about deduplication jobs.

Operation Method and URI

Retrieve a report for all deduplication jobs. GET <cluster-ip:port>/platform/12/dedupe/
reports

Retrieve a report about a single deduplication job. GET <cluster-ip:port>/platform/12/dedupe/

reports/<id>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/dedupe/
information about query parameters and object properties. reports?describe
GET <cluster-ip:port>/platform/12/dedupe/
reports/<id>?describe

System configuration API 131

Deduplication API examples
You can see examples for some deduplication API calls.

Modify deduplication settings

You can modify deduplication settings on the cluster.

Request example

PUT /platform/12/dedupe/settings
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'paths': [
'/ifs/data/dedupeme1',
'/ifs/data/dedupeme2'
]
}

Response example

204 No Content
Content-type: 'text/plain,
Allow: 'GET, PUT, HEAD'

General cluster configuration

You can manage general OneFS settings and module licenses for the PowerScale cluster.
General cluster administration covers several areas. You can:
● Manage general settings such as cluster name, date and time, and email.
● Monitor the cluster status and performance, including hardware components.
● Configure how events and notifications are handled.
● Perform cluster maintenance such as adding, removing, and restarting nodes.
● Take backup of cluster configuration and restore the configuration in the same or different cluster.
Most management tasks are accomplished through both the web administration or command-line interface; however,
occasionally there are exceptions to that.

General cluster configuration resources

You can list, modify, create, and delete information regarding OneFS cluster configuration. You can take a backup of a cluster
configuration and restore it in the same or a different cluster.

Cluster configuration backup and restore resources

You can export and import specific cluster configurations to backup good configurations and restore them on another cluster to
re-create a functional cluster.

You can perform this action when you are:

● Taking a snapshot of the cluster configuration before trying something new
● Reverting quickly back to a configuration snapshot
● Provisioning automation

132 System configuration API

Cluster configuration backup resources
You can take a backup of a cluster configuration and view the list of configuration export tasks.

Operation Method and URI

Take a backup of cluster configuration. POST <cluster-ip-or-host-name>:<port>/
platform/12/config/exports

View the list of configuration export tasks. GET <cluster-ip-or-host-name>:<port>/

platform/12/config/exports

View a specific configuration export task. GET <cluster-ip-or-host-name>:<port>/

platform/12/config/exports/<id>

Take a backup of cluster configuration

Take a backup of cluster configuration to restore it on the same or different cluster.

Request example

POST /platform/config/exports

Response example

{
"task_id" : "fliu-9peydb2-20210223085519"
}

View the list of configuration export tasks

View the status of all exported tasks. Each task has a task id and other related information.

Request example

GET /platform/config/exports

Response example

{
"exports" :
[
{
"done" : "['http', 'quota', 'snapshot', 'nfs', 'smb', 's3', 'ndmp']",
"failed" : "['quota', 'snapshot']",
"id" : "fliu-9peydb2-20210223085519",
"message" : "Components: ['quota', 'snapshot'] are not licensed.",
"path" : "/ifs/data/Isilon_Support/config_mgr/backup/fliu-9peydb2-20210223085519",
"pending" : "[]",
"status" : "Failed"
},
{
"done" : "['http', 'quota', 'snapshot', 'nfs', 'smb', 's3', 'ndmp']",
"failed" : "[]",
"id" : "fliu-9peydb2-20210223085829",
"message" : "",
"path" : "/ifs/data/Isilon_Support/config_mgr/backup/fliu-9peydb2-20210223085829",
"pending" : "[]",
"status" : "Successful"
}

System configuration API 133

 ]
}

View a specific configuration export task

View a specific configuration export task by task id.

Request example

GET /platform/config/exports/<id>

where <id> is the task id of the export

Parameter:

"id" : "fliu-9peydb2-20210223085829"

Response example

{
"exports" :
[
{
"done" : "['http', 'quota', 'snapshot', 'nfs', 'smb', 's3', 'ndmp']",
"failed" : "[]",
"id" : "fliu-9peydb2-20210223085829",
"message" : "",
"path" : "/ifs/data/Isilon_Support/config_mgr/backup/fliu-9peydb2-20210223085829",
"pending" : "[]",
"status" : "Successful"
}
]
}

Cluster configuration restore resources

You can restore a cluster configuration and view the list of configuration import tasks.

Operation Method and URI

Restore a specific cluster configuration backup. POST <cluster-ip-or-host-name>:<port>/
platform/12/config/imports

View the list of configuration import tasks. GET <cluster-ip-or-host-name>:<port>/

platform/12/config/imports

View a specific configuration import task. GET <cluster-ip-or-host-name>:<port>/

platform/12/config/imports/<id>

Restore a specific cluster configuration backup

Restore a specific cluster configuration from the backup using the export id. After the import task is created, you get a task id
as a response.

Request example

POST /platform/config/imports

Parameter:

134 System configuration API

 "export_id" : "fliu-9peydb2-20210223085829"

Response example

{
"task_id" : "fliu-9peydb2-20210223090538"
}

View the list of configuration import tasks

View the status of all imported tasks. Each task has a task id and other related information.

Request example

GET /platform/config/imports

Response example

{
"imports" :
[
{
"done" : "['http', 'quota', 'snapshot', 'nfs', 'smb', 's3', 'ndmp']",
"export_id" : "fliu-9peydb2-20210223085829",
"failed" : "[]",
"id" : "fliu-9peydb2-20210223090538",
"message" : "",
"path" : "/ifs/data/Isilon_Support/config_mgr/restore/fliu-9peydb2-20210223090538",
"pending" : "[]",
"status" : "Successful"
},
{
"done" : "['http', 'quota', 'snapshot', 'nfs', 'smb', 's3', 'ndmp']",
"export_id" : "fliu-9peydb2-20210223085829",
"failed" : "[]",
"id" : "fliu-9peydb2-20210223090613",
"message" : "",
"path" : "/ifs/data/Isilon_Support/config_mgr/restore/fliu-9peydb2-20210223090613",
"pending" : "[]",
"status" : "Successful"
}
]
}

View a specific configuration import task

View a specific configuration import task by task id.

Request example

GET /platform/config/imports/<id>

where <id> is the task id of the import

Parameter:

"id" : "fliu-9peydb2-20210223090613"

System configuration API 135

Response example

{
"imports" :
[
{
"done" : "['http', 'quota', 'snapshot', 'nfs', 'smb', 's3', 'ndmp']",
"export_id" : "fliu-9peydb2-20210223085829",
"failed" : "[]",
"id" : "fliu-9peydb2-20210223090613",
"message" : "",
"path" : "/ifs/data/Isilon_Support/config_mgr/restore/fliu-9peydb2-20210223090613",
"pending" : "[]",
"status" : "Successful"
}
]
}

Cluster configuration resource

View general information about a cluster.

Operation Method and URI

View information about a cluster. GET <cluster-ip:port>/platform/12/cluster/
config

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. config?describe

Cluster configuration join mode resource

View or set the cluster join mode.

Operation Method and URI

View information about a cluster join mode. GET <cluster-ip:port>/platform/12/cluster/
config/join-mode

Modify information about a cluster join mode. PUT <cluster-ip:port>/platform/12/cluster/

config/join-mode

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. config/join-mode?describe

Cluster email resource

View or modify cluster email notification settings.

Operation Method and URI

View cluster email notification settings. GET <cluster-ip:port>/platform/12/cluster/
email

Modify cluster email notification settings. PUT <cluster-ip:port>/platform/12/cluster/

email

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. email?describe

136 System configuration API

Cluster identity resource
View or modify cluster information that displays at login.

Operation Method and URI

View login display information. GET <cluster-ip:port>/platform/12/cluster/
identity

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. identity?describe

Cluster internal networks resource

View or modify internal network settings.

Operation Method and URI

View information about a cluster internal network. GET <cluster-ip:port>/platform/12/cluster/
internal-networks

Modify information about a cluster internal network. PUT <cluster-ip:port>/platform/12/cluster/

internal-networks

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. internal-networks?describe

Cluster nodes resource

View the nodes on a cluster.

Operation Method and URI

View the nodes on a cluster. GET <cluster-ip:port>/platform/12/cluster/
nodes

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes?describe

Cluster add node resource

Add a node to a cluster.

Operation Method and URI

Add a node to a cluster. POST <cluster-ip:port>/platform/12/cluster/
add-node

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. add-node?describe

Cluster nodes available resource

View all the nodes that are available to add to a cluster.

Operation Method and URI

List all the nodes that are available to add to a cluster. GET <cluster-ip:port>/platform/12/cluster/
nodes-available

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes-available?describe

System configuration API 137

Cluster nodes LNN resource
View node information or modify one or more node settings.

Operation Method and URI

View node information. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>

Modify one or more node settings. PUT <cluster-ip:port>/platform/12/cluster/

nodes/<LNN>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>?describe

Cluster update LNN resource

Modify the list of current LNNs with respective new LNNs in the configuration.

Operation Method and URI

Modify list of current LNNs to include new LNNs. PUT <cluster-ip:port>/platform/12/cluster/
update-lnns

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. update-lnns?describe

Cluster nodes LNN drive config resource

View or modify a node drive subsystem XML configuration file.

Operation Method and URI

View a node's drive subsystem XML configuration file. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/driveconfig

Modify a node's drive subsystem XML configuration file. PUT <cluster-ip:port>/platform/12/cluster/

nodes/<LNN>/driveconfig

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/driveconfig?describe

Cluster nodes LNN drives resource

List the drives on the specified node.

Operation Method and URI

List the drives on the specified node. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/drives

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/drives?describe

Cluster nodes LNN drives purpose list resource

View a list of the purposes that can be applied to drives on the specified node.

Operation Method and URI

View a list of the purposes that can be applied to drives on GET <cluster-ip:port>/platform/12/cluster/
the specified node. nodes/<LNN>/drives-purposelist

138 System configuration API

Operation Method and URI
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/drives-purposelist?describe

Cluster nodes LNN drive ID resource

View information about a specific drive.

Operation Method and URI

View information about a specific drive. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/drives/<DRIVEID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/drives/<DRIVEID>?describe

Cluster nodes LNN drives add drive ID resource

Add drives to a node in a OneFS cluster.

Operation Method and URI

Add drives to a node. POST <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/drives/<DRIVEID>/add

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/drives/<DRIVEID>/add?describe

Cluster nodes LNN drives and drive ID firmware resource

View information about the firmware on the drives on a node.

Operation Method and URI

View information about the firmware on a drive. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/drives/<DRIVEID>/firmware

View the detailed JSON schema for this resource, which has GET
information about query parameters and object properties. <cluster-ip:port>/platform/12/cluster/nodes/
<LNN>/drives/<DRIVEID>/firmware?describe

Cluster nodes LNN drives and drive ID firmware update resource

View firmware update information for drives on this node.

Operation Method and URI

View firmware update information. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/drives/<DRIVEID>/firmware/update

Start a drive firmware update. POST <cluster-ip:port>/platform/12/cluster/

nodes/<LNN>/drives/<DRIVEID>/firmware/update

View the detailed JSON schema for this resource, which has GET <cluster-
information about query parameters and object properties. ip:port>/platform/12/cluster/nodes/<LNN>/
drives/<DRIVEID>/firmware/update?describe

System configuration API 139

Cluster nodes LNN drives and drive ID format resource
Format drives in a node on a OneFS cluster.

Operation Method and URI

Format a drive for use by OneFS. POST <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/drives/<driveid>/format

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/drives/<driveid>/format?describe

Cluster nodes LNN drives and drive ID purpose resource

Assign drives to specific use cases on a OneFS cluster.

Operation Method and URI

Assign a drive to a specific use case. POST <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/drives/<DRIVEID>/purpose

View the detailed JSON schema for this resource, which has GET
information about query parameters and object properties. <cluster-ip:port>/platform/12/cluster/nodes/
<LNN>/drives/<DRIVEID>/purpose?describe

Cluster nodes LNN drives and drive ID smartfail resource

Remove drives from a node on a OneFS cluster.

Operation Method and URI

Remove a drive from use by OneFS. POST <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/drives/<DRIVEID>/smartfail

View the detailed JSON schema for this resource, which has GET
information about query parameters and object properties. <cluster-ip:port>/platform/12/cluster/nodes/
<LNN>/drives<DRIVEID>/smartfail?describe

Cluster nodes LNN drives and drive ID stop fail resource

Stop smart failing drives in a OneFS cluster.

Operation Method and URI

Stop smartfailing a drive. POST <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/drives/<DRIVEID>/stopfail

View the detailed JSON schema for this resource, which has GET
information about query parameters and object properties. <cluster-ip:port>/platform/12/cluster/nodes/
<LNN>/drives/<DRIVEID>/stopfail?describe

Cluster nodes LNN drives and drive ID suspend resource

Temporarily remove drives from a OneFS cluster.

Operation Method and URI

Temporarily remove a drive from use by OneFS. POST <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/drives/<DRIVEID>/suspend

140 System configuration API

Operation Method and URI
View the detailed JSON schema for this resource, which has GET
information about query parameters and object properties. <cluster-ip:port>/platform/12/cluster/nodes/
<LNN>/drives/<DRIVEID>/suspend?describe

Cluster nodes LNN hardware resource

Retrieve node hardware identification information.

Operation Method and URI

View node hardware ID information. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/hardware

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/hardware?describe

Cluster nodes LNN internal IP address resource

View node internal IP address information.

Operation Method and URI

View internal IP address information for a node. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/internal-ip-address

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/internal-ip-address?describe

Cluster nodes LNN partitions resource

Retrieve node partition information.

Operation Method and URI

View node partition information. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/partition

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/partition?describe

Cluster nodes LNN reboot resource

Reboot a node specified by logical node number (LNN).

Operation Method and URI

Reboot a node specified by LNN. POST <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/reboot

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/reboot?describe

System configuration API 141

Cluster nodes LNN sensors resource
Retrieve node sensor information.

Operation Method and URI

View node sensor information. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/sensors

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/sensors?describe

Cluster nodes LNN shutdown resource

Shut down a node specified by logical node number (LNN).

Operation Method and URI

Shut down a node specified by LNN. POST <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/shutdown

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/shutdown?describe

Cluster nodes LNN sleds resource

Get detailed information for all sleds in this node.

Operation Method and URI

View detailed information for all sleds in this node. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/sleds

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/sleds?describe

Cluster nodes LNN sleds sledid resource

Get detailed information for the sled specified by <SLEDID>, or all sleds if <SLEDID> is all, in the node specified by <LNN>.

Operation Method and URI

View detailed information for one or all sleds on the node that GET <cluster-ip:port>/platform/12/cluster/
is specified by <LNN>. nodes/<LNN>/sleds/<SLEDID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/sleds/<SLEDID>?describe

Cluster nodes LNN state resource

Retrieve node state information by specified logical node number (LNN).

Operation Method and URI

View node state information by specified LNN. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/state

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/state?describe

142 System configuration API

Cluster nodes LNN state read-only resource
Retrieve or modify node read-only state information.

Operation Method and URI

View node read-only state information. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/state/readonly

Modify one or more node read-only state settings. PUT <cluster-ip:port>/platform/12/cluster/

nodes/<LNN>/state/readonly

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/state/readonly?describe

Cluster nodes LNN state service light resource

Retrieve or modify node service light state information.

Operation Method and URI

View node service light state information. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/state/servicelight

Modify one or more node service light state settings. PUT <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/state/servicelight

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/state/servicelight?describe

Cluster nodes LNN state smartfail resource

Retrieve or modify node smartfail state information.

Operation Method and URI

View node smartfail state information. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/state/smartfail

Modify the smartfail state of a node. PUT <cluster-ip:port>/platform/12/cluster/

nodes/<LNN>/state/smartfail

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/state/smartfail?describe

Cluster nodes LNN status

Retrieve node status information.

Operation Method and URI

View node status information. GET <cluster-ip:port>/platform/12/cluster/
nodes/<lnn>/status

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<lnn>/status?describe

System configuration API 143

Cluster nodes LNN status battery status resource
Retrieve node battery status information.

Operation Method and URI

View node battery status information. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/status/batterystatus

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/status/batterystatus?describe

Cluster nodes LNN status CPU status resource

Retrieve node CPU status information.

Operation Method and URI

Retrieve CPU status. POST <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/status/cpu

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/status/cpu?describe

Cluster nodes LNN status nonvolatile RAM status resource

Retrieve node nonvolatile RAM status information.

Operation Method and URI

Retrieve nonvolatile RAM status. POST <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/status/nvram

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/status/nvram?describe

Cluster nodes LNN status power supplies status resource

Retrieve node power supplies status information.

Operation Method and URI

Retrieve power supplies status. GET <cluster-ip:port>/platform/12/cluster/
nodes/<LNN>/status/powersupplies

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. nodes/<LNN>/status/powersupplies?describe

Local cluster nodes resource

List the nodes on the cluster.

Operation Method and URI

List the nodes on the cluster. GET <cluster-ip:port>/platform/12/local/
cluster/nodes

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/local/
information about query parameters and object properties. cluster/nodes?describe

144 System configuration API

Local cluster nodes LNN resource
Retrieve node settings by logical node number (LNN), or modify one or more node settings.

Operation Method and URI

List node settings by LNN. GET <cluster-ip:port>/platform/12/local/
cluster/nodes/<LNN>

Modify node settings by LNN. PUT <cluster-ip:port>/platform/12/local/

cluster/nodes/<LNN>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/local/
information about query parameters and object properties. cluster/nodes/<LNN>?describe

Local cluster nodes LNN drives resource

List the drives on a node, which is specified by logical node number (LNN).

Operation Method and URI

List drives on a node by LNN. GET <cluster-ip:port>/platform/12/local/
cluster/nodes/<LNN>/drives

List a specific drive on a node by LNN. GET <cluster-ip:port>/platform/12/local/

cluster/nodes/<LNN>/drives/<DRIVE>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/local/
information about query parameters and object properties. cluster/nodes/<LNN>/drives?describe
GET <cluster-ip:port>/platform/12/local/
cluster/nodes/<LNN>/drives/<DRIVE>?describe

Local cluster nodes LNN drive config resource

View or modify a local drive subsystem XML configuration file.

Operation Method and URI

View a node drive subsystem XML configuration file. GET <cluster-ip:port>/platform/12/local/
cluster/nodes/<LNN>/driveconfig

Modify a node drive subsystem XML configuration file. PUT <cluster-ip:port>/platform/12/local/

cluster/nodes/<LNN>/driveconfig

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/local/
information about query parameters and object properties. cluster/nodes/<LNN>/driveconfig?describe

Local cluster nodes LNN drives firmware resource

Retrieve firmware information for a specific drive on a node, specified by logical node number (LNN).

Operation Method and URI

Retrieve firmware information for a specific drive on a node GET <cluster-ip:port>/platform/12/local/cluster/nodes/
<LNN>/drive/<DRIVE>/firmware
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/local/cluster/nodes/
information about query parameters and object properties. <LNN>/drive/<DRIVE>/firmware?describe

System configuration API 145

Local cluster nodes LNN internal IP address resource
View internal IP addresses for a node.

Operation Method and URI

View internal IP addresses for a node. GET <cluster-ip:port>/platform/12/local/
cluster/nodes/<LNN>/internal-ip-address

View the detailed JSON schema for this resource, which has GET
information about query parameters and object properties. <cluster-ip:port>/platform/12/local/cluster/
nodes/<LNN>/internal-ip-address?describe

Cluster owner resource

Retrieve cluster contact information settings.

Operation Method and URI

View cluster contact information settings. GET <cluster-ip:port>/platform/12/cluster/
owner

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. owner?describe

Cluster file system statistics resource

Retrieve file system statistics.

Operation Method and URI

View file system statistics. GET <cluster-ip:port>/platform/12/cluster/
statfs

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. statfs?describe

Cluster time resource

Retrieve the current time as reported by each node, or modify cluster time settings.
NOTE: If NTP is configured for the cluster, the cluster time is automatically synchronized to the time reported by the
configured NTP servers.

Operation Method and URI

View the current time as reported by each node. GET <cluster-ip:port>/platform/12/cluster/
time

Set the cluster time. Time gets synchronized across nodes, PUT <cluster-ip:port>/platform/12/cluster/
but there can be slight drift. time

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. time?describe

146 System configuration API

Cluster time zone resource
View cluster time zone information, or set a new time zone for a cluster.

Operation Method and URI

View the cluster time zone. GET <cluster-ip:port>/platform/12/cluster/
timezone

Set a new time zone for a cluster. PUT <cluster-ip:port>/platform/12/cluster/

timezone

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. timezone?describe

Cluster time zone regions resource

List time zone regions.

Operation Method and URI

List time zone regions. GET <cluster-ip:port>/platform/12/cluster/
timezone/regions/<REGION>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. timezone/regions/<REGION>?describe

Cluster time zone settings resource

Retrieve or modify cluster time zone settings.

Operation Method and URI

View cluster time zone setting information. GET <cluster-ip:port>/platform/12/cluster/
timezone/settings

Modify one or more nodes read-only state settings. PUT <cluster-ip:port>/platform/12/cluster/

timezone/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. timezone/settings?describe

Local cluster time resource

View the current time on the local node.

Operation Method and URI

View the current time on the local node. GET <cluster-ip:port>/platform/12/local/
cluster/time

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/local/
information about query parameters and object properties. cluster/time?describe

Cluster version resource

Retrieve the OneFS version of each node on the cluster.

NOTE: The versions of OneFS should be the same on all nodes unless an upgrade is in progress.

System configuration API 147

Operation Method and URI
View the OneFS version on each node. GET <cluster-ip:port>/platform/12/cluster/
version

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. version

SSH settings resource

View or modify SSH settings.

Operation Method and URI

List the SSH settings. GET <cluster-ip:port>/platform/12/
protocols/ssh/settings

Modify SSH settings. PUT <cluster-ip:port>/platform/12/

protocols/ssh/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. protocols/ssh/settings?describe

IP address pools
Within a subnet, you can partition an external network interfaces a cluster into pools of IP address ranges. The pools enable you
to customize your storage network to serve different groups of users. You can configure subnets in IPv4 or IPv6.
You can associate IP address pools with a node, a group of nodes, or NIC ports. For example, you can set up one subnet for
storage nodes and another subnet for accelerator nodes. Similarly, you can allocate ranges of IP addresses on a subnet to
different teams, such as engineering and sales. These options help you create a storage topology that matches the demands of
your network.
In addition, network provisioning rules streamline the setup of external connections. After you configure the rules with network
settings, you can apply the settings to new nodes.
As a standard feature, the OneFS SmartConnect module balances connections among nodes. A round-robin policy with static
IP addresses and one IP address pool for each subnet. Activating a SmartConnect Advanced license adds features, such as
defining IP address pools to support multiple DNS zones.

Cluster external IP resource

Contains the external IP addresses for the cluster.

Operation Method and URI

Get external IP addresses for the cluster. GET <cluster-ip:port>/platform/12/cluster/
external-ips

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cluster/
information about query parameters and object properties. external-ips?describe

Structure of the file system

OneFS presents all the nodes in a cluster as a global namespace.
In the file system, directories are inode number links. An inode contains file metadata and an inode number, which identifies
location of a file. OneFS dynamically allocates inodes, and there is no limit on the number of inodes.
To distribute data among nodes, OneFS sends messages with a globally routable block address through the internal network of a
cluster. The block address identifies the node and the drive storing the block of data.
NOTE: The design of your data storage structure should be planned carefully. A well-designed directory optimizes cluster
performance and cluster administration.

148 System configuration API

File system settings character encodings resource
Modify or retrieve information about settings for character-encodings.

Operation Method and URI

Retrieve default character encodings settings for the cluster. GET <cluster-ip:port>/platform/12/
filesystem/settings/character-encodings

Modify the default character encodings settings for the PUT <cluster-ip:port>/platform/12/
cluster. filesystem/settings/character-encodings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/
information about query parameters and object properties. platform/12/filesystem/settings/character-
encodings?describe

File system settings compression resource

Modify or retrieve the file system settings for compression.

Operation Method and URI

Retrieve the settings for file system compression for the GET <cluster-ip:port>/platform/12/
cluster. filesystem/settings/compression

Modify the file system compression settings for the cluster. PUT <cluster-ip:port>/platform/12/
filesystem/settings/compression

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. filesystem/settings/compression?describe

File system settings access-time resource

Modify or retrieve information about settings for the file system access-time.

Operation Method and URI

Retrieve default access-time settings. GET <cluster-ip:port>/platform/12/
filesystem/settings/access-time

Modify the default access-time settings. PUT <cluster-ip:port>/platform/12/

filesystem/settings/access-time

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. filesystem/settings/access-time?describe

Licensing
All PowerScale software and hardware must be licensed through Dell Technologies Software Licensing Central (SLC).
A license file contains a record of your active software licenses and your cluster hardware. One copy of the license file is stored
in the SLC repository, and another copy of the license file is stored on your cluster. The license file on your cluster and the
license file in the SLC repository must match. The license file contains a record of the following:
● OneFS license
● Optional software module licenses
● Hardware information

Licensing resources
You can retrieve information about OneFS feature licenses, or install a new license key.

System configuration API 149

License licenses resource
Retrieve information about OneFS feature licenses, or install a license key.

Operation Method and URI

Retrieve license information for all licensable OneFS features. GET <cluster-ip>:<port>/platform/12/license/
licenses

Retrieve license information for a specific OneFS feature. GET <cluster-ip>:<port>/platform/12/license/

licenses/<NAME>

Install a new license key. POST <cluster-ip>:<port>/platform/12/

license/licenses

View the detailed JSON schema for this resource, which has GET <cluster-ip>:<port>/platform/12/license/
information about query parameters and object properties. licenses?describe
GET <cluster-ip>:<port>/platform/12/license/
licenses/<NAME>?describe

License EULA resource

Retrieve the OneFS end user license agreement (EULA) as plain text.

Operation Method and URI

Retrieve the OneFS EULA as plain text. GET <cluster-ip>:<port>/platform/12/license/
eula

View the detailed JSON schema for this resource, which has GET <cluster-ip>:<port>/platform/12/license/
information about query parameters and object properties. eula?describe

Security hardening
Security hardening is the process of configuring a system to reduce or eliminate as many security risks to support the Security
Technical Implementation Guides (STIGs).
When you apply a hardening profile on a PowerScale cluster, OneFS reads the security profile file and applies the configuration
that is defined in the profile to the cluster. If required, OneFS identifies configuration issues that prevent hardening on the
nodes. For example, the file permissions on a particular directory might not be set to the expected value, or the required
directories might be missing. When an issue is found, you can choose to allow OneFS to resolve the issue, or you can defer
resolution and fix the issue manually.
NOTE: The intention of the hardening profile is to support STIGs defined by the Defense Information Systems Agency
(DISA) and applicable to OneFS. The hardening profile only supports a subset of requirements that are defined by DISA in
STIGs. The hardening profile is meant to be primarily used in Federal accounts.
If you determine that the hardening configuration is not right for your system, OneFS allows you to revert the security hardening
profile. Reverting a hardening profile returns OneFS to the configuration before hardening.
You must have an active security hardening license and be logged in to the PowerScale cluster as the root user to apply
hardening to OneFS. To obtain a license, contact your PowerScale sales representative.

Hardening resources
Apply, resolve, revert, or retrieve information about hardening on a cluster.

150 System configuration API

Hardening apply resource
Apply hardening on a cluster.

Operation Method and URI

Apply hardening on a cluster. POST <cluster-ip:port>/platform/12/
hardening/apply

Hardening resolve resource

Resolve issues that are related to hardening that are encountered in the current cluster configuration.

Operation Method and URI

Resolve hardening issues on a cluster. POST <cluster-ip:port>/platform/12/
hardening/resolve

Hardening revert resource

Revert hardening on a cluster.

Operation Method and URI

Revert hardening on a cluster. POST <cluster-ip:port>/platform/12/
hardening/revert

Hardening state resource

Retrieve the state of the current hardening operation, if one is in progress.

NOTE: This is different from the hardening status resource, which retrieves the overall hardening status on the cluster.

Operation Method and URI

Retrieve the state (apply or revert) of the current hardening GET <cluster-ip:port>/platform/12/hardening/
operation. state

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/hardening/
information about query parameters and object properties. state?describe

Hardening status resource

Retrieve a message indicating whether the cluster is hardened. This also includes node-specific hardening status if hardening is
enabled on at least one node.

NOTE: This is different from the hardening state resource, which returns that state of a specific hardening operation.

Operation Method and URI

Retrieve a message indicating if a cluster is hardened. GET <cluster-ip:port>/platform/12/hardening/
status

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/hardening/
information about query parameters and object properties. status?describe

System configuration API 151

External key management for SEDs using KMIP
PowerScale can store data on Self-Encrypted Drives (SEDs). Such drives have encryption keys that are stored locally on nodes.
User can move these keys to some external key management server to store them safely.

KMIP server resources

Retrieve, create, modify, remove, and verify information about Key Management Interoperability Protocol (KMIP) servers.

Operation Method and URI

Create a KMIP server. You can configure only one POST <cluster-ip-or-host-name>:<port>/platform/12/
KMIP server. The client_cert file must have both keymanager/kmip/servers
certificate and client key in the same file.
Remove a KMIP server. A server cannot be DELETE <cluster-ip-or-host-name>:<port>/platform/12/
deleted when the KMIP feature is enabled. keymanager/kmip/servers/<id>

View the details of a specific server. GET <cluster-ip-or-host-name>:<port>/platform/12/

keymanager/kmip/servers/<id>

Get a list of available servers and the number of GET <cluster-ip-or-host-name>:<port>/platform/12/

servers. keymanager/kmip/servers/

Modify a KMIP server. PUT <cluster-ip-or-host-name>:<port>/platform/12/

keymanager/kmip/servers/<id>

Verify KMIP configuration. POST <cluster-ip-or-host-name>:<port>/platform/12/

keymanager/kmip/server/verify

Request query parameters

View the various query parameters for KMIP API requests.

Parameter Name Description Default Type Required

Id Unique KMIP server N/A string Yes
identifier
host KMIP server hostname N/A string Yes
ca_cert_path Certification Authority N/A string Yes
(CA) certificate used
to validate the server
connection during TLS
Mutual Authentication
with the external KMIP
server
client_cert_path Cluster client N/A string Yes
certificate and private
key that is used to
authenticate the cluster
during TLS Mutual
Authentication with the
external KMIP server
port KMIP server host port 5696 Integer No
client_cert_password Cluster client private N/A string No
key password
minimum_tls_version Minimum TLS version The default value can No
number for KTP. only be 1.0, 1.1 or 1.2.
Needed for servers like

152 System configuration API

Parameter Name Description Default Type Required
IBM SKLM that only
supports TLS 1.0

KMIP examples
View examples regarding selective KMIP API requests.

Verify KMIP configuration

Request example

POST /platform/12/keymanager/kmip/server/verify
Body:
{
"nodes" :
[
{
"id" : 1,
"lnn" : 1,
"message" : "Success",
"status" : true
}
],
"total" : 1
}

Response example

{
"client_cert_path": "/ifs/kmip_client_bundle.pem",
"minimum_tls_version": "1.2",
"host": "aimakmip.west.isilon.com",
"ca_cert_path": "/ifs/kmip_ca.pem"
}

View details of a specific server

Request example

GET platform/12/keymanager/kmip/servers/aimakmip

Response example

{
"servers" :
[

{
"ca_cert" :
{
"expiration_date" : 1780854384,
"fingerprint" : "77dca16aeaf912e41fd6aed1c6e579c5c6457d80ab2db115f63e862185c36c86",
"serial" : 0,
"subject" : "C=US, ST=Washington, L=Seattle, O=Isilon, OU=AIMA, CN=KMIP CA,
emailAddress="
},
"client_cert" :

System configuration API 153

 {
"expiration_date" : 1780869157,
"fingerprint" : "8c575e2e7b7019758f25781e7b1cf448e368dfe33f79e82a8912204706312b65",
"serial" : 9120,
"subject" : "C=US, ST=WA, L=Seattle, O=Isilon Engineering, OU=AIMA, CN=wctest,
[email protected]"
},
"host" : "aimakmip.west.isilon.com",
"id" : "aimakmip",
"minimum_tls_version" : "1.2",
"port" : 5696
}
]
}

Self-Encrypting Drive (SED) resources

Migrate and restore KMIP servers, and retrieve KMIP status information.

Operation Method and URI

Modify the feature enabled flag of the KMIP PUT <cluster-ip-or-host-name>:<port>/platform/12/
feature. keymanager/sed/settings

View the current KMIP settings. GET <cluster-ip-or-host-name>:<port>/platform/12/

keymanager/sed/settings

Start migration to server. This command does POST <cluster-ip-or-host-name>:<port>/platform/12/

nothing unless 'sed migrate local' has been called. keymanager/sed/migrate
Start restoration back to local. This command POST <cluster-ip-or-host-name>:<port>/platform/12/
does nothing unless 'sed migrate server' has been keymanager/sed/migrate
called.
Retry KMIP migration in the previous direction POST <cluster-ip-or-host-name>:<port>/platform/12/
for nodes that did not migrate due to errors. keymanager/sed/migrate
For example, if error occurred after migrate
with 'to_server=true', using 'sed/migrate' handler
with 'retry=true' will retry migration to
server. Similarly, if previous migration was
'to_server=false', retry tries to restore back to
local.
View the current KMIP status. Status supports GET <cluster-ip-or-host-name>:<port>/platform/12/
display options. keymanager/sed/status

View the current KMIP status for a specific node. GET <cluster-ip-or-host-name>:<port>/platform/12/
Status supports display options. keymanager/sed/status/<LNN>

SED API query parameters

View the various query parameters for SED API requests.

Parameter Name Description Default Type Required

kmip_enabled ‘true’ for kmip feature false boolean Yes
enabled, and ‘false’
otherwise. Having
feature that is enabled
does not start the
migration, but it allows
the 'sed migrate'
command to run and
migrate. When KMIP is
enabled, KMIP servers

154 System configuration API

Parameter Name Description Default Type Required
cannot be deleted.
Moreover, the feature
cannot be disabled if
there are nodes that
are not in 'LOCAL'
status.
to_server If ‘true’, migrates keys N/A boolean Yes
to server. If ‘false’,
restores keys to local.
Ignored and not
required when 'retry' is
set to 'true'.

retry If set to ‘true’, false boolean Yes

'sed migrate retry' is
triggered.

SED examples
View examples regarding selective SED API requests.

View KMIP settings

Request example

GET platform/12/keymanager/sed/settings

Response example

{
"settings" :
{
"kmip_enabled" : true,
"kmip_server" : "aimakmip",
"supported" : true
}
}

View KMIP status

Request example

GET platform/12/keymanager/sed/status

Response example

{
"nodes" :
[

System configuration API 155

 "error_msg" : "",
"id" : 1,
"lnn" : 1,
"location" : "Local",
"remote_key_id" : "",
"status" : "LOCAL"
},

{
"error_msg" : "",
"id" : 2,
"lnn" : 2,
"location" : "Local",
"remote_key_id" : "",
"status" : "LOCAL"
},

{
"error_msg" : "",
"id" : 3,
"lnn" : 3,
"location" : "Local",
"remote_key_id" : "",
"status" : "LOCAL"
},

{
"error_msg" : "",
"id" : 4,
"lnn" : 4,
"location" : "Local",
"remote_key_id" : "",
"status" : "LOCAL"
}
],
"total" : 4
}

Modify KMIP flag

Request example

PUT platform/12/keymanager/sed/settings

Body:

{
"kmip_enabled" : "true"
}

Response example

No content. Returns nothing.

Migrate keys to server

Request example

POST platform/12/keymanager/sed/migrate

Body:
{

156 System configuration API

 "to_server" : "true"
}

Response example

{
"migration_msg" : "Migration started. Please check status for progress."
}

Upgrading OneFS
Before upgrading the OneFS cluster, it is recommended to perform preupgrade checks to confirm that your OneFS cluster is
ready for an upgrade. These checks scan the current OneFS cluster and operating system for issues and compare the current
OneFS version with the new version to ensure that the cluster meets certain criteria, such as configuration compatibility (SMB,
LDAP, SmartPools), disk availability, and the absence of critical cluster events. Some preupgrade checks are optional, but it is
recommended to perform all preupgrade checks before upgrading.
If upgrading puts the cluster at risk, OneFS warns you, provides information about the risks, and prompts you to confirm
whether to continue the upgrade.
There are three options available for upgrading the OneFS cluster: parallel upgrades, rolling upgrades, or simultaneous upgrades.
For more information about how to plan, prepare, and perform an upgrade on your OneFS cluster, see the PowerScale OneFS
Upgrade Planning and Process Guide.

Upgrade cluster resources

View, modify, create, or delete information related to OneFS cluster upgrades.

Upgrade cluster resource

Retrieve cluster-wide OneFS upgrade status information.

Operation Method and URI

Retrieve upgrade status information for the cluster. GET <cluster-ip:port>/platform/12/upgrade/
cluster

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster?describe

Upgrade cluster pause resource

Pause a running upgrade process.

Operation Method and URI

Pause a running upgrade process. GET <cluster-ip:port>/platform/12/upgrade/
cluster/pause

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/pause?describe

System configuration API 157

Upgrade cluster resume resource
Resume a paused upgrade process.

Operation Method and URI

Resume a paused upgrade process. GET <cluster-ip:port>/platform/12/upgrade/
cluster/resume

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/resume?describe

Upgrade cluster upgrade resource

Add nodes to a running upgrade, or modify settings in order to start an upgrade.

Operation Method and URI

Add nodes to a running upgrade. POST <cluster-ip:port>/platform/12/upgrade/
cluster/upgrade

Modify settings for an upgrade. PUT <cluster-ip:port>/platform/12/upgrade/

cluster/upgrade

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/upgrade?describe

Upgrade cluster assess resource

Start an upgrade assessment for the cluster.

Operation Method and URI

Start an upgrade assessment. POST <cluster-ip:port>/platform/12/upgrade/
cluster/assess

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/assess?describe

Upgrade cluster commit resource

Commit the upgrade of a cluster.

Operation Method and URI

Commit the upgrade of a cluster. POST <cluster-ip:port>/platform/12/upgrade/
cluster/commit

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/commit?describe

Upgrade cluster add remaining nodes resource

Absorb any remaining or new nodes into the existing upgrade.

Operation Method and URI

Absorb remaining or new nodes into existing upgrade. POST <cluster-ip:port>/platform/12/upgrade/
cluster/add_remaining_nodes

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/add_remaining_nodes?describe

158 System configuration API

Upgrade cluster archive resource
Start an archive of an upgrade.

Operation Method and URI

Start an archive of an upgrade. POST <cluster-ip:port>/platform/12/upgrade/
cluster/archive

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/archive?describe

Upgrade cluster nodes resource

View information about nodes during an upgrade, rollback, or preupgrade assessment.

Operation Method and URI

View information about nodes during an upgrade, rollback, or GET <cluster-ip:port>/platform/12/upgrade/
preupgrade. assessment cluster/nodes

View information about a specific node during an upgrade or GET <cluster-ip:port>/platform/12/upgrade/

assessment. cluster/nodes/<lnn>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/nodes?describe
GET <cluster-ip:port>/platform/12/upgrade/
cluster/nodes/<lnn>?describe

Upgrade cluster nodes firmware status resource

View firmware status for a specific node.

Operation Method and URI

Retrieve firmware status for a specific node. GET <cluster-ip:port>/platform/12/upgrade/
cluster/nodes/<LNN>/firmware/status

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/nodes/<LNN>/firmware/status?describe

Upgrade cluster nodes patch synchronization resource

Retry all pending patch synchronization operations.

Operation Method and URI

Retry all pending patch synchronization operations. POST <cluster-ip:port>/platform/12/upgrade/
cluster/nodes/<LNN>/patch/sync

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/nodes/<LNN>/patch/sync?describe

Upgrade cluster firmware assess resource

Start a firmware upgrade assessment on the cluster.

Operation Method and URI

Start a firmware upgrade assessment. POST <cluster-ip:port>/platform/12/upgrade/
cluster/firmware/assess

System configuration API 159

Operation Method and URI
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/firmware/assess?describe

Upgrade cluster firmware progress resource

Retrieve cluster-wide firmware upgrade status information.

Operation Method and URI

Retrieve cluster-wide firmware upgrade status information. GET <cluster-ip:port>/platform/12/upgrade/
cluster/firmware/progress

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/firmware/progress?describe

Upgrade cluster firmware status resource

Retrieve the firmware status for the cluster.

Operation Method and URI

Retrieve firmware status for the cluster. GET <cluster-ip:port>/platform/12/upgrade/
cluster/firmware/status

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/firmware/status?describe

Upgrade cluster firmware upgrade resource

Upgrade firmware on a OneFS cluster.

Operation Method and URI

Start a firmware upgrade. POST <cluster-ip:port>/platform/12/upgrade/
cluster/firmware/upgrade

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/firmware/upgrade?describe

Upgrade cluster retry last action resource

Retry the previous upgrade action if the previous attempt failed.

Operation Method and URI

Retry the previous upgrade action. POST <cluster-ip:port>/platform/12/upgrade/
cluster/retry_last_action

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/retry_last_action?describe

Upgrade cluster rollback resource

Roll back the upgrade of a cluster.

Operation Method and URI

Roll back the upgrade of a cluster. POST <cluster-ip:port>/platform/12/upgrade/
cluster/rollback

160 System configuration API

Operation Method and URI
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/rollback?describe

Upgrade cluster rolling reboot resource

Perform a rolling reboot of the cluster.

Operation Method and URI

Perform a rolling reboot of the cluster. POST <cluster-ip:port>/platform/12/upgrade/
cluster/rolling-reboot

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/rolling-reboot?describe

Upgrade cluster patch resource

List, install, or delete patches.

Operation Method and URI

List all patches. GET <cluster-ip:port>/platform/12/upgrade/
cluster/patch/patches

View a single patch. GET <cluster-ip:port>/platform/12/upgrade/

cluster/patch/patches/<patch>

Install a patch. POST <cluster-ip:port>/platform/12/upgrade/

cluster/patch/patches

Uninstall a patch. DELETE <cluster-ip:port>/platform/12/

upgrade/cluster/patch/patches/<patch>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/patch/patches?describe
GET <cluster-ip:port>/platform/12/upgrade/
cluster/patch/patches/<patch>?describe

Upgrade cluster patch abort resource

Cancel the previous action performed by the patch system.

Operation Method and URI

Cancel the previous action performed by the patch system. POST <cluster-ip:port>/platform/12/upgrade/
cluster/patch/abort

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/patch/abort?describe

Upgrade cluster drain resources

View or modify the resources that affect drain-based upgrade processes, where nodes are not reboot until all SMB clients have
disconnected.

Operation Method and URI

Modify the sets of nodes that are assigned to the skip drain PUT <cluster-ip:port>/platform/12/upgrade/
and delay drain lists. cluster/drain

System configuration API 161

Operation Method and URI
Retrieve the sets of nodes that are assigned to the skip drain GET <cluster-ip:port>/platform/12/upgrade/
and delay drain lists. cluster/drain/list

Retrieve the cluster-wide drain timeout and drain alert timeout PUT <cluster-ip:port>/platform/12/upgrade/
values. cluster/drain/timeout

Modify the cluster-wide drain timeout and drain alert timeout GET <cluster-ip:port>/platform/12/upgrade/
values. cluster/drain/timeout

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. cluster/drain?describe

NOTE: The default drain-timeout value is -1, which is specified for upgrade to start without waiting for all the SMB
clients to be disconnected.

Cluster date and time

The Network Time Protocol (NTP) service is configurable manually, so you can ensure that all nodes in a cluster are
synchronized to the same time source.
The NTP method automatically synchronizes cluster date and time settings through an NTP server. Alternatively, you can set
the date and time reported by the cluster by manually configuring the service.
Windows domains provide a mechanism to synchronize members of the domain to a master clock running on the domain
controllers, so OneFS adjusts the cluster time to that of Active Directory with a service. If there are no external NTP servers
that are configured, OneFS uses the Windows domain controller as the NTP time server. When the cluster and domain time that
is become out of sync by more than 4 minutes, OneFS generates an event notification.
NOTE: If the cluster and Active Directory that is become out of sync by more than 5 minutes, authentication does not
work.

NTP resources
List, modify, create, or delete Network Time Protocol (NTP) configuration information.

NTP servers resource

Retrieve NTP servers; or create, modify, or delete NTP server entries.

Operation Method and URI

List all NTP servers. GET <cluster-ip:port>/platform/12/protocols/ntp/servers

Retrieve a specific NTP server. GET <cluster-ip:port>/platform/12/protocols/ntp/servers/

<SERVER-ID>

Create an NTP server entry. POST <cluster-ip:port>/platform/12/protocols/ntp/servers

Modify the key value for a specific NTP PUT <cluster-ip:port>/platform/12/protocols/ntp/servers/

server. <SERVER-ID>

Delete all NTP server entries. DELETE <cluster-ip:port>/platform/12/protocols/ntp/

servers

Delete a specific NTP server entry. DELETE <cluster-ip:port>/platform/12/protocols/ntp/

servers/<SERVER-ID>

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/protocols/ntp/servers?

resource, which has information about query describe
parameters and object properties.
GET <cluster-ip:port>/platform/12/protocols/ntp/servers/
<SERVER-ID>?describe

162 System configuration API

NTP settings resource
List or modify Network Time Protocol (NTP) settings information.

Operation Method and URI

List all NTP settings. GET <cluster-ip:port>/platform/12/protocols/ntp/settings

Modify NTP settings (all input fields are PUT <cluster-ip:port>/platform/12/protocols/ntp/settings

optional, but you must supply one or more).
View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/protocols/ntp/
resource, which has information about query settings?describe
parameters and object properties.

Managing SNMP settings

You can use SNMP to monitor cluster hardware and system information. You can configure settings through either the web
administration interface or the command-line interface.
The default SNMP v3 username (general) and password can be changed to anything from the CLI or the WebUI. The username
is only required when SNMP v3 is enabled and making SNMP v3 queries.
Configure a network monitoring system (NMS) to query each node directly through a static IPv4 address. If a node is configured
for IPv6, you can communicate with SNMP over IPv6.
The SNMP proxy is enabled by default, and the SNMP implementation on each node is configured automatically to proxy for all
other nodes in the cluster except itself. This proxy configuration allows the PowerScale Management Information Base (MIB)
and standard MIBs to be exposed seamlessly by using context strings for supported SNMP versions. This approach allows you
to query a node through another node by appending _node_<node number> to the community string of the query. For example,
snmpwalk -m /usr/share/snmp/mibs/ISILON-MIB.txt -v 2c -c 'I$ilonpublic_node_1' localhost
<nodename>.

SNMP settings resource

List or modify Simple Network Management Protocol (SNMP) settings.

Operation Method and URI

List SNMP settings. GET <cluster-ip:port>/platform/12/protocols/snmp/
settings

Modify SNMP settings (all input fields are PUT <cluster-ip:port>/platform/12/protocols/snmp/

optional, but you must supply one or more). settings

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/protocols/snmp/

resource, which has information about query settings?describe
parameters and object properties.

Hardware
You can update certain information about PowerScale hardware ports and tapes through the OneFS system configuration API.

Hardware resources
You can list, modify, or delete information about ports and tapes, and you can rescan tape devices.

System configuration API 163

Upgrade hardware start resource
Start the hardware upgrade process of a specified type on a specified node pool.

Operation Method and URI

Start hardware upgrade process. POST <cluster-ip:port>/platform/12/upgrade/
hardware/start

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. hardware/start?describe

Upgrade hardware status resource

View the status of hardware upgrades in progress.

Operation Method and URI

View hardware upgrade status. GET <cluster-ip:port>/platform/12/upgrade/
hardware/status

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/
information about query parameters and object properties. hardware/status?describe

Upgrade hardware stop resource

Stop a hardware upgrade that is in progress.

Operation Method and URI

Stop a hardware upgrade process POST <cluster-ip:port>/platform/12/upgrade/hardware/stop
View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/upgrade/hardware/stop?
information about query parameters and object properties. describe

Fibre Channel ports resource

Retrieve or modify information about Fibre Channel ports in PowerScale hardware.

Operation Method and URI

List Fibre Channel ports. GET <cluster-ip>:<port>/platform/12/
hardware/fcports

Retrieve one Fibre Channel port. GET <cluster-ip>:<port>/platform/12/

hardware/fcports/<PORTt>

Change information about Fibre Channel ports. PUT <cluster-ip>:<port>/platform/12/

hardware/fcports/<PORT>

View the detailed JSON schema for this resource, which has GET <cluster-ip>:<port>/platform/12/
information about query parameters and object properties. hardware/fcports?describe
GET <cluster-ip>:<port>/platform/12/
hardware/fcports/<PORT>?describe

164 System configuration API

Hardware tapes resource
List, modify, rescan, or remove tape or media changer devices.

Operation Method and URI

List tape and media changer devices. GET <cluster-ip>:<port>/platform/12/
hardware/tapes

Modify tape and media changer devices. PUT GET <cluster-ip>:<port>/platform/12/

hardware/tapes/<NAME*>

Rescan tape and media changer devices. POST <cluster-ip>:<port>/platform/12/

hardware/tape/<NAME*>

Remove tape and media changer devices. DELETE PUT <cluster-ip>:<port>/platform/12/

hardware/tape/<NAME*>

View the detailed JSON schema for this resource, which has GET <cluster-ip>:<port>/platform/12/
information about query parameters and object properties. hardware/tapes?describe
GET <cluster-ip>:<port>/platform/12/
hardware/tapes/<NAME*>?describe

File pools
File pools are sets of files that you define to apply policy-based control of the storage characteristics of your data.
The initial installation of OneFS places all files in the cluster into a single file pool, which is subject to the default file pool policy.
SmartPools enables you to define additional file pools, and create policies that move files in these pools to specific node pools
and tiers.
File pool policies match specific file characteristics (such as file size, type, date of last access or a combination of these and
other factors). Then, it defines specific storage operations for files that match them. The following examples demonstrate a few
ways that you can configure file pool policies:
● You can create a file pool policy for a specific file extension that requires high availability.
● You can configure a file pool policy to store that type of data in a storage pool that provides the fastest reads or read/
writes.
● You can create another file pool policy to evaluate last accessed date. You can use this pool to store older files in storage
pool that is best suited for archiving for historical or regulatory purposes.

File pool resources

You can retrieve, create, modify, or delete file pool configurations and settings.

File pool default policy resource

Modify or retrieve information about the default file pool policy.

Operation Method and URI

Retrieve information about the default file pool policy. GET <cluster-ip:port>/platform/12/filepool/
default-policy

Modify the default file pool policy. PUT <cluster-ip:port>/platform/12/filepool/

default-policy

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/filepool/
information about query parameters and object properties. default-policy?describe

System configuration API 165

File pool policies resource
Create, modify, delete, or retrieve information about file pool policies.

Operation Method and URI

Retrieve information about all file pool policies. GET <cluster-ip:port>/platform/12/filepool/
policies

Retrieve information about a file pool policy. GET <cluster-ip:port>/platform/12/filepool/

policies/<POLICY-NAME>

Create a file pool policy. POST <cluster-ip:port>/platform/12/filepool/

policies

Modify a file pool policy. PUT <cluster-ip:port>/platform/12/filepool/

policies/<POLICY-NAME>

Delete a file pool policy. DELETE <cluster-ip:port>/platform/12/

filepool/policies/<POLICY-NAME>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/filepool/
information about query parameters and object properties. policies?describe
GET <cluster-ip:port>/platform/12/filepool/
policies/<POLICY-NAME>?describe

File pool templates resource

Retrieve information about OneFS file pool policy templates.

Operation Method and URI

Retrieve information about file pool policy templates. GET <cluster-ip:port>/platform/12/filepool/
templates

Retrieve information about a file pool policy template. GET <cluster-ip:port>/platform/12/filepool/

templates/<TEMPLATE-NAME>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/filepool/
information about query parameters and object properties. templates?describe
GET <cluster-ip:port>/platform/12/filepool/
templates/<TEMPLATE-NAME>?describe

File pools API examples

You can see examples for some file pools API requests.

Create a file pool policy

You can create a file pool policy.

Request example

POST /platform/12/filepool/policies
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{'file_matching_pattern':
{'or_criteria':
[
{'and_criteria':
[
{'operator': '==', 'type': 'path', 'value': '/ifs/data/vms'}

166 System configuration API

 ]
}
]
},
'name': 'mirror_vms',
'actions':
[
{
'action_param': '8x',
'action_type': 'set_requested_protection'
}
]
}

Response example

201 Created
Content-type: application/json

{
"id" : "mirror_vms"
}

Modify a file pool policy

You can modify a file pool policy.

Request example
In the following example, "vms_mirror" is the ID of the file pool policy.

PUT /platform/12/filepool/policies/vms_mirror
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"action_param":"false"
"action_type":"set_requested_protection"
}

Response example
No message body is returned for this request.

204 No Content
Content-type: text/plain,
Allow: 'GET, PUT, HEAD'

Modify the default file pool policy

You can modify the default file pool policy.

Request example

PUT /platform/12/filepool/policies/
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"action_param":"random"
"action_type":"set_data_access_pattern"
}

System configuration API 167

Response example
No message body is returned for this request.

204 No Content
Content-type: text/plain,
Allow: 'GET, PUT, HEAD'

Storage pools overview

OneFS organizes different node types into separate node pools. You can configure node pool membership to include node types
that you specify. You can also add node types to, and remove node types from, existing node pools. You can organize these
node pools into logical tiers of storage. By activating a SmartPools license, you can create file pool policies that store files in
these tiers automatically, based on criteria that you specify.
Without an active SmartPools license, OneFS manages all node pools as a single pool of storage. File data and metadata are
striped across the entire cluster so that data is protected, secure, and readily accessible. All files belong to the default file pool
and are governed by the default file pool policy. In this mode, OneFS provides functions such as autoprovisioning, virtual hot
spare (VHS), global namespace acceleration (GNA), L3 cache, and storage tiers.
When you activate a SmartPools license, additional functions become available, including custom file pool policies and spillover
management. With a SmartPools license, you can manage your dataset with more granularity to improve the performance of
your cluster.
The following table summarizes storage pool functions based on whether a SmartPools license is active.

Function Inactive SmartPools license Active SmartPools license

Automatic storage pool provisioning Yes Yes
Virtual hot spare Yes Yes
SSD strategies Yes Yes
L3 cache Yes Yes
Tiers Yes Yes
GNA Yes Yes
File pool policies No Yes
Spillover management No Yes

Storage pools resources

You can retrieve, create, modify, or delete system storage pool settings and configurations.

Storage pool settings resource

Modify or retrieve information about storage pools.

Operation Method and URI

Retrieve storage pool settings. GET <cluster-ip:port>/platform/12/
storagepool/settings

Modify storage pool settings. PUT <cluster-ip:port>/platform/12/

storagepool/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. storagepool/settings?describe

168 System configuration API

Storage pools tiers resource
Create, delete, or retrieve information about storage pool tiers.

Operation Method and URI

Retrieve a list of all tiers. GET <cluster-ip:port>/platform/12/
storagepool/tiers

Retrieve a single tier. GET <cluster-ip:port>/platform/12/

storagepool/tiers/<NAME or ID>

Create a tier. POST <cluster-ip:port>/platform/12/

storagepool/tiers

Delete all tiers. DELETE <cluster-ip:port>/platform/12/

storagepool/tiers

Delete a single tier. DELETE <cluster-ip:port>/platform/12/

storagepool/tiers/<NAME or ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. storagepool/tiers?describe

Storage pools node pools resource

Create, modify, delete, or retrieve information about node pools.

Operation Method and URI

Retrieve information for all node pools. GET <cluster-ip:port>/platform/12/
storagepool/nodepools

Retrieve information for a single node pool. GET <cluster-ip:port>/platform/12/

storagepool/nodepools/<POOL NAME or ID>

Create a node pool. POST <cluster-ip:port>/platform/12/

storagepool/nodepools

Modify a node pool. PUT <cluster-ip:port>/platform/12/

storagepool/nodepools/<POOL NAME or ID>

Delete a manually managed node pool. DELETE <cluster-ip:port>/platform/12/

storagepool/nodepools/<POOL NAME or ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. storagepool/nodepools?describe
GET <cluster-ip:port>/platform/12/
storagepool/nodepools/<POOL NAME or ID>?
describe

Storage pools resource

Retrieve information about storage pools. You can supply a toplevels argument to filter out node pools within tiers.

Operation Method and URI

Retrieve information for all storage pools. GET <cluster-ip:port>/platform/12/
storagepool/storagepools

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. storagepool/storagepools?describe

System configuration API 169

Storage pools suggested protection resource
Retrieve information about the suggested protection policy for a storage pool.

Operation Method and URI

Retrieve information about the suggested protection policy. GET <cluster-ip:port>/platform/12/
storagepool/suggested_protection/<NID>

View the detailed JSON schema for this resource, which has GET
information about query parameters and object properties. <cluster-ip:port>/platform/12/storagepool/
suggested_protection/<NID>?describe

Storage pool compatibilities SSD active resource

Create, delete, modify, or view active SSD compatibilities.

Operation Method and URI

Retrieve a list of active SSD compatibilities. GET <cluster-ip:port>/platform/12/
storagepool/compatibilities/ssd/active

Retrieve an SSD compatibility by ID. GET <cluster-ip:port>/

platform/12/storagepool/compatibilities/ssd/
active/<COMPATIBILITY-ID>

Create an SSD compatibility. POST <cluster-ip:port>/platform/12/

storagepool/compatibilities/ssd/active

Modify an SSD compatibility. PUT <cluster-ip:port>/

platform/12/storagepool/compatibilities/ssd/
active/<COMPATIBILITY-ID>

Delete an SSD compatibility. DELETE <cluster-ip:port>/

platform/12/storagepool/compatibilities/ssd/
active/<COMPATIBILITY-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/
information about query parameters and object properties. platform/12/storagepool/compatibilities/ssd/
active?describe
GET <cluster-ip:port>/
platform/12/storagepool/compatibilities/ssd/
active/<COMPATIBILITY-ID>?describe

Storage pool compatibilities SSD available resource

View a list of available SSD compatibilities.

Operation Method and URI

Retrieve a list of available SSD compatibilities. GET <cluster-ip:port>/platform/12/
storagepool/compatibilities/ssd/available

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/
information about query parameters and object properties. platform/12/storagepool/compatibilities/ssd/
available?describe

170 System configuration API

Storage pool compatibilities class available resource
View a list of available class compatibilities.

Operation Method and URI

Retrieve a list of available class compatibilities. GET <cluster-ip:port>/platform/12/
storagepool/compatibilities/class/available

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. storagepool/compatibilities/class/available?
describe

Storage pool compatibilities class active resource

Create, delete, or retrieve information about a storage pool compatibility.

Operation Method and URI

Retrieve all storage pool compatibilities. GET <cluster-ip:port>/platform/12/
storagepool/compatibilities/class/active

Retrieve a storage pool compatibility by ID. GET

<cluster-ip:port>/platform/12/storagepool/
compatibilities/class/active/<ID>

Create a storage pool compatibility. POST <cluster-ip:port>/platform/12/

storagepool/compatibilities/class/active

Delete a storage pool compatibility by ID. DELETE

<cluster-ip:port>/platform/12/storagepool/
compatibilities/class/active/<ID>

View the detailed JSON schema for this resource, which has GET
information about query parameters and object properties. <cluster-ip:port>/platform/12/storagepool/
compatibilities/class/active?describe
GET
<cluster-ip:port>/platform/12/storagepool/
compatibilities/class/active/<ID>?describe

Storage pool status resource

Retrieves the heath status of the overall OneFS pool system.

Operation Method and URI

Retrieve the status of the OneFS pool system. GET <cluster-ip:port>/platform/12/
storagepool/status

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. storagepool/status?describe

Storage pools API examples

You can see examples for some storage pools API calls.

System configuration API 171

Modify storage pool settings
You can modify the global storage pool settings on the system.

Request example
Specify at least one property in the request.

PUT /platform/12/storagepool/settings
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'global_namespace_acceleration_enabled': false,
'automatically_manage_protection': 'all'
}

Response example
No message body is returned for this request.

204 NO CONTENT
Content-type: text/plain,
Allow: 'GET, PUT, HEAD'

Create a tier
Create a tier on the system.

Request example

POST /platform/12/storagepool/tiers
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'name': 'myTier'
}

Response example

201 CREATED
Content-type: application/json,
Allow: 'GET, POST, HEAD, DELETE'

{
"id":"myTier"
}

Modify a tier
Modify a tier.

Request example
When you modify a set of nodes that belong to a tier, you should set the tier property on that node pool through the /
platform/12/storagepool/nodepools URI.

PUT /platform/12/storagepool/tiers/myTier
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

172 System configuration API

 "name": myTier
}

PUT /platform/12/storagepool/nodepools
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
"tier": myTier
}

Response example
No message body is returned for this request.

204 NO CONTENT
Content-type: application/json,
Allow: 'GET, POST, PUT, DELETE'

Create a node pool

Create and manually manage a node pool.

Request example
Specify a minimum of three LNNs. After these nodes are added to the newly created node pool and removed from their current
node pool, the number of nodes in the original node pool must either be 0 or greater than 2.

POST /platform/12/storagepool/nodepools
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'name': 'myPool',
'lnns': [2, 3, 1]
}

Response example

201 CREATED
Content-type: application/json,
Allow: 'GET, POST, HEAD, DELETE'

{
"id":"myPool"
}

Modify a node pool

You can modify a node pool on the system.

Request example
Specify at least one property in the body. Also, you can only specify LNNs for manually managed node pools and you should
specify a minimum of three LNNs when modifying a manually managed node pool. If nodes are moved to a new node pool and
removed from their current node pool, the number of nodes in the original node pool must either be 0 or greater than 2.

PUT /platform/12/storagepool/nodepools/myPool
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{
'tier': 'myTier',
'name': 'myNewPoolName'
}

System configuration API 173

Response example
No message body is returned for this request.

204 No Content
Content-type: application/json,
Allow: 'GET, POST, PUT, DELETE'

CloudPools
CloudPools extends the capabilities of OneFS by enabling you to specify data to be moved to lower-cost cloud storage.
CloudPools can seamlessly connect to Dell EMC EMC-based cloud storage systems and to popular third-party providers,
Amazon S3, Google, and Microsoft Azure.
CloudPools is a licensed module that is built on the SmartPools file pool policy framework, which gives you granular control
of file storage on your cluster. CloudPools extends this file storage control to one or more cloud repositories, which act as
additional tiers of OneFS storage.
Prior to the introduction of CloudPools, SmartPools enabled the grouping of nodes into storage pools that are called node
pools, and the classification of node pools as different storage tiers. SmartPools includes a policy framework that allows you to
segregate files into logical groups called file pools, and to store those file pools in specific storage tiers.
CloudPools expands the SmartPools framework by treating a cloud repository as an additional storage tier. This enables you to
move older or seldom-used data to cloud storage and free up space on your cluster.
As with SmartPools, you define files to be stored in the cloud by creating file pool policies. These policies use file matching
criteria to determine which file pools are to be moved to the cloud.

CloudPools resources
List, create, modify, or delete CloudPools information.

CloudPools pools resource

View, create, modify, or delete pools.

Operation Method and URI

List all pools. GET <cluster-ip:port>/platform/12/cloud/
pools

Retrieve information about a specific pool. GET <cluster-ip:port>/platform/12/cloud/

pools/<POOL>

Create a pool. POST <cluster-ip:port>/platform/12/cloud/

pools

Modify a pool. PUT <cluster-ip:port>/platform/12/cloud/

pools/<POOL>

Delete a pool. DELETE <cluster-ip:port>/platform/12/cloud/

pools/<POOL>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cloud/
information about query parameters and object properties. pools?describe
GET <cluster-ip:port>/platform/12/cloud/
pools/<POOL>?describe

174 System configuration API

CloudPools access resource
View, create, or delete cluster identifiers for cloud access.

Operation Method and URI

List all accessible cluster identifiers. GET <cluster-ip:port>/platform/12/cloud/
access

List cloud access information for a specific cluster. GET <cluster-ip:port>/platform/12/cloud/

access/<GUID>

Add a cluster to the identifier list. POST <cluster-ip:port>/platform/12/cloud/

access

Delete cloud access. DELETE <cluster-ip:port>/platform/12/cloud/

access/<GUID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cloud/
information about query parameters and object properties. access?describe
GET <cluster-ip:port>/platform/12/cloud/
access/<GUID>?describe

CloudPools account resource

View, modify, create, or delete cloud account information.

Operation Method and URI

List all cloud accounts. GET <cluster-ip:port>/platform/12/cloud/
accounts

View a specific cloud account. GET <cluster-ip:port>/platform/12/cloud/

accounts/<ACCOUNT-ID>

Create a cloud account. POST <cluster-ip:port>/platform/12/cloud/

accounts

Modify a cloud account. PUT <cluster-ip:port>/platform/12/cloud/

accounts/<ACCOUNT-ID>

Delete a cloud account. DELETE <cluster-ip:port>/platform/12/cloud/

accounts/<ACCOUNT-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cloud/
information about query parameters and object properties. accounts?describe
GET <cluster-ip:port>/platform/12/cloud/
accounts/<ACCOUNT-ID>?describe

CloudPools TLS client certificates resource

List, import, view, modify, or delete a CloudPools TLS client certificate.

Operation Method and URI

List all cloud TLS client certificates. GET <cluster-ip:port>/platform/12/cloud/
certificates

View a specific cloud TLS client certificate. GET <cluster-ip:port>/platform/12/cloud/

certificates/<CERTIFICATE-ID>

Create a cloud TLS client certificate. POST <cluster-ip:port>/platform/12/cloud/

certificates

System configuration API 175

Operation Method and URI
Modify a cloud TLS client certificate. PUT <cluster-ip:port>/platform/12/cloud/
certificates/<CERTIFICATE-ID>

Delete a cloud TLS client certificate. DELETE <cluster-ip:port>/platform/12/cloud/

certificates/<CERTIFICATE-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cloud/
information about query parameters and object properties. certificates?describe
GET <cluster-ip:port>/platform/12/cloud/
certificates/<CERTIFICATE-ID>?describe

CloudPools jobs resource

View, modify, or create CloudPools jobs.

Operation Method and URI

List all CloudPools jobs. GET <cluster-ip:port>/platform/12/cloud/jobs

View a specific CloudPools job. GET <cluster-ip:port>/platform/12/cloud/

jobs/<JOB-ID>

Create a CloudPools job. POST <cluster-ip:port>/platform/12/cloud/

jobs

Modify a CloudPools job. PUT <cluster-ip:port>/platform/12/cloud/

jobs/<JOB-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cloud/
information about query parameters and object properties. jobs?describe
GET <cluster-ip:port>/platform/12/cloud/
jobs/<JOB-ID>?describe

CloudPools job files resource

Retrieve files associated with a CloudPools job.

Operation Method and URI

List files associated with a specific CloudPools job. GET <cluster-ip:port>/platform/12/cloud/
jobs-files/<JOB-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cloud/
information about query parameters and object properties. jobs-files/<JOB-ID>?describe

CloudPools network proxy resourceCloudPools network proxy resource

View, create, modify, or delete network proxy information.

Operation Method and URI

List all cloud network proxies. GET <cluster-ip:port>/platform/12/cloud/
proxies

View a specific cloud network proxy. GET <cluster-ip:port>/platform/12/cloud/

proxies/<PROXY-ID>

Create a cloud network proxy. POST <cluster-ip:port>/platform/12/cloud/

proxies

Modify a cloud network proxy. PUT <cluster-ip:port>/platform/12/cloud/

proxies/<PROXY-ID>

176 System configuration API

Operation Method and URI
Delete a cloud network proxy. DELETE <cluster-ip:port>/platform/12/cloud/
proxies/<PROXY-ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cloud/
information about query parameters and object properties. proxies?describe
GET <cluster-ip:port>/platform/12/cloud/
proxies/<PROXY-ID> ?describe

CloudPools settings resource

View or modify cloud settings.

Operation Method and URI

List all cloud settings. GET <cluster-ip:port>/platform/12/cloud/
settings

Modify cloud settings. PUT <cluster-ip:port>/platform/12/cloud/

settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cloud/
information about query parameters and object properties. settings?describe

CloudPools encryption key resource

Request creation of a new master encryption key for cloud pool encryption.

Operation Method and URI

Create an encryption key. POST <cluster-ip:port>/platform/12/cloud/
settings/encryption_key

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cloud/
information about query parameters and object properties. settings/encryption_key?describe

CloudPools end user license agreement resource

View, accept, or revoke end user license agreement (EULA) telemetry information.

Operation Method and URI

View telemetry collection EULA acceptance information. GET <cluster-ip:port>/platform/12/cloud/
settings/reporting_eula

Accept telemetry collection EULA. POST <cluster-ip:port>/platform/12/cloud/

settings/reporting_eula

Revoke acceptance of telemetry collection EULA. DELETE <cluster-ip:port>/platform/12/cloud/

settings/reporting_eula

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/cloud/
information about query parameters and object properties. settings/reporting_eula?describe

System configuration API 177

SmartQuotas overview
The SmartQuotas module is an optional quota-management tool that monitors and enforces administrator-defined storage limits.
Using accounting and enforcement quota limits, reporting capabilities, and automated notifications, SmartQuotas manages
storage use, monitors disk storage, and issues alerts when disk-storage limits are exceeded.
Quotas help you manage storage usage according to criteria that you define. Quotas are used for tracking—and sometimes
limiting—the amount of storage that a user, group, or directory consumes. Quotas help ensure that a user or department does
not infringe on the storage that is allocated to other users or departments. In some quota implementations, writes beyond the
defined space are denied, and in other cases, a simple notification is sent.
NOTE: Do not apply quotas to /ifs/.ifsvar/ or its subdirectories. If you limit the size of the /ifs/.ifsvar/
directory through a quota, and the directory reaches its limit, jobs such as File-System Analytics fail. A quota blocks older
job reports from being deleted from the /ifs/.ifsvar/ subdirectories to make room for newer reports.

The SmartQuotas module requires a separate license. For more information about the SmartQuotas module or to activate the
module, contact your Dell Technologies sales representative.

Quotas resources
You can retrieve, create, modify, or delete SmartQuotas configurations and settings.

Quota license resource

Retrieve license information for the SmartQuotas feature.

Operation Method and URI

Retrieve license information for SmartQuotas. GET <cluster-ip:port>/platform/12/quota/
license

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/quota/
information about query parameters and object properties. license?describe

Quota summary resource

Retrieve summary information about quotas.

Operation Method and URI

Retrieve summary information about quotas. GET <cluster-ip:port>/platform/12/quota/quotas-
summary

View the detailed JSON schema for this resource, which GET <cluster-ip:port>/platform/12/quota/quotas-
has information about query parameters and object summary?describe
properties.

Quota quotas notification rules resource

Create, modify, delete, or retrieve information about notification rules for a quota.

Operation Method and URI

Retrieve all notification rules for a quota. GET <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-ID>/
notifications

Retrieve a notification rule for a quota. GET <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-ID>/

notifications/<notification-id>

Create notification rules for a quota. POST <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-ID>/

notifications

178 System configuration API

Operation Method and URI
Create empty override notification rules PUT <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-ID>/
for a quota. notifications

Modify notification rules for a quota. PUT <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-ID>/

notifications/<notification-id>

Delete all notification rules for a quota. DELETE <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-

ID>/notifications

Delete notification rules for a quota. DELETE <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-

ID>/notifications/<notification-id>

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-ID>/

resource, which has information about notifications?describe
query parameters and object properties.
GET <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-ID>/
notifications/<notification-id>?describe

Quotas resource
Create, modify, delete, or retrieve information about file system quotas.

Operation Method and URI

Retrieve all quotas. GET <cluster-ip:port>/platform/12/quota/quotas

Retrieve one quota. GET <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-

ID>

Create a quota. POST <cluster-ip:port>/platform/12/quota/quotas

Modify a quota. PUT <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-

ID>

Delete all quotas. DELETE <cluster-ip:port>/platform/12/quota/quotas

Delete a quota. DELETE <cluster-ip:port>/platform/12/quota/quotas/

<QUOTA-ID>

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/quota/quotas?

resource, which has information about query describe
parameters and object properties.
GET <cluster-ip:port>/platform/12/quota/quotas/<QUOTA-
ID>?describe

Example request for retrieve all quotas

List all or matching quotas. It can also be used to retrieve quota state from existing reports. For any query argument not
supplied, the default behavior is returned all.

GET /platform/quota/quotas

Example response for retrieve all quotas

"quotas": [

"container": false,

"efficiency_ratio": 0.6644405405460209,

"enforced": false,

"id": "gAEDAAEAAAAAAAAAAAAAQAEAAAAAAAAA",

System configuration API 179

 "include_snapshots": false,

"linked": false,

"notifications": "default",

"path": "/ifs/test",

"persona": null,

"ready": true,

"reduction_ratio": 1.000002479553223,

"thresholds": {

"advisory": null,

"advisory_exceeded": false,

"advisory_last_exceeded": null,

"hard": null,

"hard_exceeded": false,

"hard_last_exceeded": null,

"percent_advisory": null,

"percent_soft": null,

"soft": null,

"soft_exceeded": false,

"soft_grace": null,

"soft_last_exceeded": null

},

"thresholds_on": "fslogicalsize",

"type": "directory",

"usage": {

"applogical": 10485760,

"applogical_ready": true,

"fslogical": 10485786,

"fslogical_ready": true,

"fsphysical": 15781376,

"fsphysical_ready": true,

"inodes": 2,

"inodes_ready": true,

"physical": 15781376,

"physical_data": 10485760,

"physical_data_ready": true,

"physical_protection": 5242880,

"physical_protection_ready": true,

180 System configuration API

 "physical_ready": true,

"shadow_refs": 0,

"shadow_refs_ready": true

],

"resume": null

Quota reports resource

Create, delete, or retrieve information about quota reports.

Operation Method and URI

Retrieve all quota reports. GET <cluster-ip:port>/platform/12/quota/reports

Retrieve a quota report. GET <cluster-ip:port>/platform/12/quota/reports/

<REPORT-ID>?contents

Create a quota report. POST <cluster-ip:port>/platform/12/quota/reports/

<REPORT-ID>?contents

Delete a quota report. DELETE <cluster-ip:port>/platform/12/quota/reports/

<REPORT-ID>

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/quota/reports?
which has information about query parameters and describe
object properties.
GET <cluster-ip:port>/platform/12/quota/reports/
<REPORT-ID>?describe

Quota about reports resource

Retrieve metadata for individual quota reports.

Operation Method and URI

Retrieve metadata about a report. GET <cluster-ip:port>/platform/12/quota/reports/
<REPORT-ID>/about

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/quota/reports/

resource, which has information about query <REPORT-ID>/about?describe
parameters and object properties.

Quota report settings resource

Modify or retrieve information about quota report settings.

Operation Method and URI

Retrieve quota report settings. GET <cluster-ip:port>/platform/12/quota/
settings/reports

Modify quota report settings. PUT <cluster-ip:port>/platform/12/quota/

settings/reports

System configuration API 181

Operation Method and URI
View the detailed JSON schema for this resource, which GET <cluster-ip:port>/platform/12/quota/
has information about query parameters and object settings/reports?describe
properties.

Quota default notifications settings resource

Create, modify, delete, or retrieve information about default quota notification settings.

Operation Method and URI

List default global notification settings. GET <cluster-ip:port>/platform/12/quota/settings/
notifications

View a specific global notification setting. GET <cluster-ip:port>/platform/12/quota/settings/

notifications/<NOTIFICATION-ID>

Create global notification settings. POST <cluster-ip:port>/platform/12/quota/settings/

notifications

Modify a default global notification settings. PUT <cluster-ip:port>/platform/12/quota/settings/

notifications/<NOTIFICATION-ID>

Delete global notification settings. DELETE <cluster-ip:port>/platform/12/quota/settings/

notifications

Delete a specific global notification setting. DELETE <cluster-ip:port>/platform/12/quota/settings/

notifications/<NOTIFICATION-ID>

View the detailed JSON schema for this GET <cluster-ip:port>/platform/12/quota/settings/

resource, which has information about query notifications?describe
parameters and object properties.
GET <cluster-ip:port>/platform/12/quota/settings/
notifications/<NOTIFICATION-ID>?describe

Quota mappings settings resource

Create, modify, delete, or retrieve information about quota notification email-mapping rules.

Operation Method and URI

Retrieve quota email-mapping settings. GET <cluster-ip:port>/platform/12/quota/settings/
mappings

Create quota email-mapping settings. POST <cluster-ip:port>/platform/12/quota/settings/

mappings/<DOMAIN>

Modify quota email-mapping setting. PUT <cluster-ip:port>/platform/12/quota/settings/

mappings/<DOMAIN>

Delete all quota email-mapping settings. DELETE <cluster-ip:port>/platform/12/quota/

settings/mappings

Delete a quota email-mapping setting. DELETE <cluster-ip:port>/platform/12/quota/

settings/mappings/<DOMAIN>

View the detailed JSON schema for this resource, GET <cluster-ip:port>/platform/12/quota/settings/
which has information about query parameters and mappings?describe
object properties.
GET <cluster-ip:port>/platform/12/quota/settings/
mappings/<DOMAIN>?describe

182 System configuration API

Common Anti-Virus Agent (CAVA)
Common Anti-Virus Agent (CAVA) provides an anti-virus solution for PowerScale systems. CAVA uses third-party anti-virus
software to identify and eliminate known viruses. Common Event Enabler (CEE) provides a framework for the CAVA agent.
CEE, CAVA, and a third-party anti-virus engine are installed on Windows machines. CAVA accesses node files through SMB
shares, and supports zone-specific file filters, job definitions, and job schedules.

Common anti-virus agent resources

You can retrieve, create, and modify file filters, jobs, and anti-virus server configurations.

AVScan filters resource

View and modify AVScan anti-virus settings for zones.

Operation Method and URI

List AVScan settings for zones. GET <cluster-ip:port>/platform/12/avscan/
settings

List AVScan settings for a zone. GET <cluster-ip:port>/platform/12/avscan/

settings/<ZONE>

Modify AVScan settings for a zone. PUT <cluster-ip:port>/platform/12/avscan/

settings/<ZONE>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/avscan/
information about query parameters and object properties. settings?describe
GET <cluster-ip:port>/platform/12/avscan/
settings/<ZONE>?describe

Avscan jobs resource

Retrieve all anti-virus jobs and settings, create anti-virus jobs, and delete all anti-virus jobs. Retrieve, modify, and delete an
anti-virus job.

Operation Method and URI

Retrieve avscan jobs and settings. GET <cluster-ip:port>/platform/12/avscan/
jobs

Retrieve avscan settings for a job. GET <cluster-ip:port>/platform/12/avscan/

jobs/<JOB>

Create avscan jobs. POST <cluster-ip:port>/platform/12/avscan/

jobs/

Modify an avscan job. PUT <cluster-ip:port>/platform/12/avscan/

jobs/<JOB>

Delete all avscan jobs. DELETE <cluster-ip:port>/platform/12/avscan/

jobs

Delete an avscan job. DELETE <cluster-ip:port>/platform/12/avscan/

jobs/<JOB>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/avscan/
information about query parameters and object properties. jobs?describe
GET <cluster-ip:port>/platform/12/avscan/
jobs/<JOB>?describe

System configuration API 183

Avscan nodes LNN status
Retrieve anti-virus status of a node.

Operation Method and URI

Retrieve anti-virus status. GET <cluster-ip:port>/platform/12/avscan/
nodes/<LNN>/status

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/avscan/
information about query parameters and object properties. nodes/<LNN>/status?describe

Avscan servers resource

Retrieve all anti-virus servers and settings, create anti-virus servers, and delete all anti-virus servers. Retrieve, modify, and
delete an anti-virus server.

Operation Method and URI

Retrieve avscan servers and settings. GET <cluster-ip:port>/platform/12/avscan/
servers

Retrieve avscan settings for a server. GET <cluster-ip:port>/platform/12/avscan/

servers/<SERVER>

Create avscan servers. POST <cluster-ip:port>/platform/12/avscan/

servers/

Modify an avscan server. PUT <cluster-ip:port>/platform/12/avscan/

servers/<SERVER>

Delete all avscan servers. DELETE <cluster-ip:port>/platform/12/avscan/

servers

Delete an avscan server. DELETE <cluster-ip:port>/platform/12/avscan/

servers/<SERVER>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/avscan/
information about query parameters and object properties. servers?describe
GET <cluster-ip:port>/platform/12/avscan/
servers/<SERVER>?describe

Avscan settings resource

Retrieve and modify anti-virus settings.

Operation Method and URI

Retrieve anti-virus settings. GET <cluster-ip:port>/platform/12/avscan/
settings

Modify anti-virus settings. PUT <cluster-ip:port>/platform/12/avscan/

settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/avscan/
information about query parameters and object properties. settings?describe

ICAP anti-virus
You can scan the files that you store on a PowerScale cluster for system viruses and other security threats by integrating with
third-party scanning services through the Internet Content Adaptation Protocol (ICAP).
OneFS sends files through ICAP to a server running third-party anti-virus scanning software. These servers are seen as ICAP
servers. ICAP servers scan files for viruses.

184 System configuration API

After an ICAP server scans a file, it informs OneFS of whether the file is a threat. If a threat is detected, OneFS informs system
administrators by creating an event, displaying near real-time summary information, and documenting the threat in an anti-virus
scan report. You can configure OneFS to request that ICAP servers attempt to repair infected files. You can also configure
OneFS to protect users against potentially dangerous files by truncating or quarantining infected files.
Before OneFS sends a file to be scanned, it ensures that the scan is not redundant. If a file has already been scanned and has
not been modified, OneFS will not send the file to be scanned unless the virus database on the ICAP server has been updated
since the last scan.

NOTE: Anti-virus scanning is available only if all nodes in the cluster are connected to the external network.

Antivirus resources
Retrieve, create, modify, or delete antivirus configurations and settings.

Anti-virus policies resource

Create, modify, delete, or retrieve information about anti-virus policies.

Operation Method and URI

Retrieve all anti-virus policies. GET <cluster-ip:port>/platform/12/antivirus/
policies

Create an anti-virus policy. POST <cluster-ip:port>/platform/12/

antivirus/policies

Delete all anti-virus policies. DELETE <cluster-ip:port>/platform/12/

antivirus/policies

Retrieve an anti-virus policy. GET <cluster-ip:port>/platform/12/antivirus/

policies/<policy-name>

Modify an anti-virus policy. PUT <cluster-ip:port>/platform/12/antivirus/

policies/<policy-name>

Delete an anti-virus policy. DELETE <cluster-ip:port>/platform/12/

antivirus/policies/<policy-name>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/antivirus/
information about query parameters and object properties. policies?describe
GET <cluster-ip:port>/platform/12/antivirus/
policies/<policy-name>?describe

Anti-virus quarantine resource

Retrieve or modify information about the quarantine status of files in the /ifs directory tree.

Operation Method and URI

Get anti-virus quarantine information. GET <cluster-ip:port>/platform/12/antivirus/
quarantine/<path>

Modify anti-virus quarantine information. PUT <cluster-ip:port>/platform/12/antivirus/

quarantine/<path>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/antivirus/
information about query parameters and object properties. quarantine/<path>?describe

System configuration API 185

Anti-virus scan report resource
View or delete information about anti-virus scans.

Operation Method and URI

List all anti-virus scan reports. GET <cluster-ip:port>/platform/12/antivirus/
reports/scans

View a specific anti-virus scan report. GET <cluster-ip:port>/platform/12/antivirus/

reports/scans/<ID>

Delete anti-virus scan reports, and any threat reports DELETE <cluster-ip:port>/platform/12/
associated with those scans. antivirus/reports/scans

Delete a specific anti-virus scan report, and any threat reports DELETE <cluster-ip:port>/platform/12/
associated with the scan. antivirus/reports/scans<ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/antivirus/
information about query parameters and object properties. reports/scans?describe
GET <cluster-ip:port>/platform/12/antivirus/
reports/scans/<ID>?describe

Anti-virus threat reports resource

List all anti-virus threat reports, or view a specific report.

Operation Method and URI

List all anti-virus threat reports. GET <cluster-ip:port>/platform/12/antivirus/
reports/threats

View a specific anti-virus threat report. GET <cluster-ip:port>/platform/12/antivirus/

reports/threats/<ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/antivirus/
information about query parameters and object properties. reports/threats?describe
GET <cluster-ip:port>/platform/12/antivirus/
reports/threats/<ID>?describe

Anti-virus scan resource

Enable a client to run an anti-virus scan on a single file.

Operation Method and URI

Manually scan a file. POST <cluster-ip:port>/platform/12/
antivirus/scan/

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/antivirus/
information about query parameters and object properties. scan/?describe

Anti-virus servers resource

List, create, modify, or delete all anti-virus servers or one anti-virus server entry.

Operation Method and URI

List all anti-virus servers. GET <cluster-ip:port>/platform/12/antivirus/
servers

Create an anti-virus server. POST <cluster-ip:port>/platform/12/

antivirus/servers

186 System configuration API

Operation Method and URI
Delete all anti-virus servers. DELETE <cluster-ip:port>/platform/12/
antivirus/servers

View an anti-virus server entry. GET <cluster-ip:port>/platform/12/antivirus/

servers/<ID>

Modify an anti-virus server entry. PUT <cluster-ip:port>/platform/12/antivirus/

servers/<ID>

Delete an anti-virus server entry. DELETE <cluster-ip:port>/platform/12/

antivirus/servers/<ID>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/antivirus/
information about query parameters and object properties. servers?describe
GET <cluster-ip:port>/platform/12/antivirus/
servers/<ID>?describe

Anti-virus settings resource

View or modify anti-virus settings.

Operation Method and URI

List anti-virus settings. GET <cluster-ip:port>/platform/12/antivirus/
settings

Modify anti-virus settings. PUT <cluster-ip:port>/platform/12/antivirus/

settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/antivirus/
information about query parameters and object properties. settings?describe

Performance
This chapter documents the performance-related resource handlers for the OneFS system configuration API.

Performance settings resource

Retrieve and configure performance settings.

Operation Method and URI

Retrieve all performance settings. GET <cluster-ip:port>/platform/12/
performance/settings

Modify performance settings. PUT <cluster-ip:port>/platform/12/

performance/settings

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. performance/settings?describe

Performance datasets resource

List, create, modify, or delete performance metric datasets.
A dataset is a set of metrics for which performance statistics are collected. For a list of available metrics, see the /
performance/metrics API resource.

System configuration API 187

Operation Method and URI
List performance datasets. GET <cluster-ip:port>/platform/12/
performance/datasets

View a specific performance dataset. GET <cluster-ip:port>/platform/12/

performance/datasets/<DATASET>

Modify a performance dataset. PUT <cluster-ip:port>/platform/12/

performance/datasets/<DATASET>

Create a performance dataset. POST <cluster-ip:port>/platform/12/

performance/datasets

Delete a specific performance dataset. DELETE <cluster-ip:port>/platform/12/

performance/datasets/<DATASET>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. performance/datasets?describe
GET <cluster-ip:port>/platform/12/
performance/datasets/<DATASET>?describe

Performance datasets filters resource

List, create, modify, or delete performance dataset filters.

Operation Method and URI

List performance dataset filters. GET <cluster-ip:port>/platform/12/
performance/datasets/<DATASET>/filters

View a specific performance dataset filter. GET <cluster-ip:port>/

platform/12/performance/datasets/<DATASET>/
filters/<FILTER>

Modify a performance dataset filter. PUT <cluster-ip:port>/

platform/12/performance/datasets/<DATASET>/
filters/<FILTER>

Create a performance dataset filter. POST <cluster-ip:port>/platform/12/

performance/datasets/<DATASET>/filters

Delete a specific performance dataset. DELETE <cluster-ip:port>/

platform/12/performance/datasets/<DATASET>/
filters/<FILTER>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/
information about query parameters and object properties. platform/12/performance/datasets/<DATASET>/
filters?describe
GET <cluster-ip:port>/
platform/12/performance/datasets/<DATASET>/
filters/<FILTER>?describe

Performance datasets workloads resource

List, create, modify, or delete performance dataset workloads.

Operation Method and URI

List performance dataset workloads. GET <cluster-ip:port>/platform/12/
performance/datasets/<DATASET>/workloads

View a specific performance dataset workload. GET <cluster-ip:port>/

platform/12/performance/datasets/<DATASET>/
workloads/<WORKLOAD>

188 System configuration API

Operation Method and URI
Modify a performance dataset workload. PUT <cluster-ip:port>/
platform/12/performance/datasets/<DATASET>/
workloads/<WORKLOAD>

Create a performance dataset workload. POST <cluster-ip:port>/platform/12/

performance/datasets/<DATASET>/workloads

Delete a specific performance workload. DELETE <cluster-ip:port>/

platform/12/performance/datasets/<DATASET>/
workloads/<WORKLOAD>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/
information about query parameters and object properties. platform/12/performance/datasets/<DATASET>/
workloads?describe
GET <cluster-ip:port>/
platform/12/performance/datasets/<DATASET>/
workloads/<WORKLOAD>?describe

Performance metrics resource

List performance metrics for a dataset, or view a specific metric.

Operation Method and URI

List performance metrics. GET <cluster-ip:port>/platform/12/
performance/metrics

View a specific performance dataset workload. GET <cluster-ip:port>/platform/12/

performance/metrics/<METRIC>

View the detailed JSON schema for this resource, which has GET <cluster-ip:port>/platform/12/
information about query parameters and object properties. performance/metrics?describe
GET <cluster-ip:port>/platform/12/
performance/metrics/<METRIC>?describe

System configuration API 189

 4
File system access API
You can access files and directories on a cluster programmatically through the OneFS API, similar to the way you can access
files and directories through SMB or NFS protocols.

Topics:
• File system access API overview
• Troubleshooting
• File system access operations
• Code samples for file system access

File system access API overview

You can access files and directories on a cluster programmatically through the OneFS API, like you can access files and
directories through SMB or NFS protocols.
Through the OneFS API, you can perform the types of file system operations that are listed in the following table.

Operation Description
Access points Identify and configure access points and obtain protocol
information.
Directory List directory content; get and set directory attributes; delete
directories from the file system.
File View, move, copy, and delete files from the file system.
Access control Manage user rights; set ACL or POSIX permissions for files
and directories.
Query Search and tag files
SmartLock Allow retention dates to be set on files; commit a file to a
WORM state.

Also, you can create an external client or application to access the OneFS API in any major language, such as C, C++, Python,
Java, or .net.

Common response headers

You may see the following response headers when you send a request to the namespace.

Name Description Type

Content-length Provides the length of the body message in the response. Integer

Connection Provides the state of connection to the server. String

Date Provides the date when the object store last responded. HTTP-date

Server Provides platform and version information about the server that responded String
to the request.

x-isi-ifs-target-type Provides the resource type. This value can be a container or an object. String

190 File system access API

Common request headers
When you send a request to the OneFS API, you can access data through customized headers along with standard HTTP
headers.
The following table provides information about common HTTP request headers:

Name Description Type Required

Authorization Specifies the authentication signature. String Yes

Content-length Specifies the length of the message body. Integer Conditional

Date Specifies the current date according to the HTTP-date No. A client should only send a
requestor. Date header in a request that
includes an entity-body, such
as in PUT and POST requests.
A client without a clock must
not send a Date header in a
request.

x-isi-ifs-spec-version Specifies the protocol specification version. The String Conditional

client specifies the protocol version, and the
server determines if the protocol version is
supported. You can test backwards compatibility
with this header.

x-isi-ifs-target-type Specifies the resource type. For PUT operations, String Yes, for PUT operations.
this value can be container or object. For
Conditional, for GET
GET operations, this value can be container,
operations.
object, or any, or this parameter can be
omitted.

Common namespace attributes

The following system attributes are common to directories and files in the namespace.

Attribute Description Type

name Specifies the name of the object. String

size Specifies the size of the object in bytes. Integer

block_size Specifies the block size of the object. Integer

blocks Specifies the number of blocks that compose the object. Integer

last_modified Specifies the time when the object data was last modified in HTTP date/time format. HTTP date

create_time Specifies the date when the object data was created in HTTP date/time format. HTTP date

access_time Specifies the date when the object was last accessed in HTTP date/time format. HTTP date

change_time Specifies the date when the object was last changed (including data and metadata String
changes) in HTTP date/time format.

type Specifies the object type, which can be one of the following values: container, object, String
pipe, character_device, block_device, symbolic_link, socket, or whiteout_file.

mtime_val Specifies the time when the object data was last modified in UNIX Epoch format. Integer

File system access API 191

Attribute Description Type

btime_val Specifies the time when the object data was created in UNIX Epoch format. Integer

atime_val Specifies the time when the object was last accessed in UNIX Epoch format. Integer

ctime_val Specifies the time when the object was last changed (including data and metadata Integer
changes) in UNIX Epoch format.

owner Specifies the user name for the owner of the object. String

group Specifies the group name for the owner of the object. String

uid Specifies the UID for the owner. Integer

gid Specifies the GID for the owner. Integer

mode Specifies the UNIX mode octal number. String

id Specifies the object ID, which is also the INODE number. Integer

nlink Specifies the number of hard links to the object. Integer

is_hidden Specifies whether the file is hidden or not. Boolean

Troubleshooting
You can troubleshoot failed requests to the namespace by resolving common errors and viewing activity logs.

Common error codes

The following example shows the common JSON error format:

{
"errors":[
{
"code":"<Error code>",
"message":"<some detailed error msg>"
}
]
}

The following table shows the descriptions for common error codes.

Error Code Description HTTP status

AEC_TRANSIENT The specified request returned a transient 200 OK
error code that is treated as OK.
AEC_BAD_REQUEST The specified request returned a bad 400 Bad Request
request error.
AEC_ARG_REQUIRED The specified request requires an 400 Bad Request
argument for the operation.
AEC_ARG_SINGLE_ONLY The specified request requires only a 400 Bad Request
single argument for the operation.
AEC_UNAUTHORIZED The specified request requires user 401 Unauthorized
authentication.

192 File system access API

Error Code Description HTTP status
AEC_FORBIDDEN The specified request was denied by the 403 Forbidden
server. Typically, this response includes
permission errors on OneFS.
AEC_NOT_FOUND The specified request has a target object 404 Not Found
that was not found.
AEC_METHOD_NOT_ALLOWED The specified request sent a method that 405 Method Not Allowed
is not allowed for the target object.
AEC_NOT_ACCEPTABLE The specified request is unacceptable. 406 Not Acceptable
AEC_CONFLICT The specified request has a conflict that 409 Conflict
prevents the operation from completing.
AEC_PRE_CONDITION_FAILED The specified request has failed a 412 Precondition failed
precondition.
AEC_INVALID_REQUEST_RANGE The specified request has requested a 416 Requested Range not
range that cannot be satisfied. Satisfiable
AEC_NOT_MODIFIED The specified request was not modified. 304 Not Modified
AEC_LIMIT_EXCEEDED The specified request exceeded the limit 403 Forbidden
set on the server side.
AEC_INVALID_LICENSE The specified request has an invalid 403 Forbidden
license.
AEC_NAMETOOLONG The specified request has an object name 403 Forbidden
size that is too long.
AEC_SYSTEM_INTERNAL_ERROR The specified request has failed because 500 Internal Server Error
the server encountered an unexpected
condition.

Activity Logs
Activity logs capture server and object activity, and can help identify problems. The following table shows the location of
different types of activity logs.

Server Logs Object Daemon Log Generic Log

● /var/log/<server>/ /var/log/isi_object_d.log /var/log/message
webui_httpd_error.log
● /var/log/<server>/
webui_httpd_access.log
For <server>, type the path to the
server directory. For example: /apache2.

File system access operations

You can make requests through the OneFS API to perform operations on the file system.

File system access API 193

Access points
You can access the file system namespace through an access point. Root users can create an access point on the namespace,
and initially only the root user has privileges for that access point. The root user can create an access control list (ACL) to
provide read privileges for additional users.
Root users can create an access point on the namespace, and initially only the root user has privileges for that access point. The
root user can create an access control list (ACL) to provide read privileges for additional users.
The root user can also grant write privileges to users, but nonroot users with write privileges are unable to reconfigure the path
of an existing access point.
Also, each file or directory in an access point has its own permissions, so even if a user has privileges for an access point, the
user must still be given permissions for each file and directory.

Configure a user accounts for read privileges

Configure user accounts with read privileges before users can access an access point. User access privileges (such as read,
write, or read/write) for files and directories that are under an access point are governed by the OneFS system ACLs and
permissions. Users privileges to an access point can be modified, however, the read privilege must be given to a user, or the
user cannot access the access point.

Steps
1. Create a user account by running the following command, where user1 is the new user account name:

isi auth users create user1 --password user1 --home-directory /ifs/home/user1 --

password-expires no

2. Grant users read-privilege to a OneFS access point through by applying the PUT method to the URI.
In the following example, user1 is granted access to the ifs-ap1 access point by modifying the ACL read-privilege on the
access point.

PUT /namespace/ifs-ap1?acl&nsaccess=true HTTP/1.1

Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==
Host: 10.245.107.17:8080
Content-Type:application/json
Content-Length: 140
{"authoritative":"acl", "acl":[{"trustee": {"name":"user1","type":"user"},
"accesstype":"allow", "accessrights":["file_read"], "op":"add"}]}'

Create a namespace access point

Creates a namespace access point in the file system. Only root users can create or change namespace access points.

Request syntax

PUT /namespace/<access_point> HTTP/1.1

Host <hostname>[:<port>]
Content-Length: <length>
Date: <date>
Authorization: <signature>

{
"path" : "<absolute_filesystem_path>"
}

NOTE:

The path to the namespace access point must begin at /ifs, which is the root directory of the OneFS file system.

194 File system access API

Request query parameters
There are no query parameters for this request.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
No message body is returned upon success.

Example request
The following request creates an access point named 'accesspoint1' on the namespace.

PUT /namespace/accesspoint1 HTTP/1.1

Host my_cluster:8080
Date: Fri, 15 Mar 2013 21:51:50 GMT
Content-Type: text/xml

{
"path": "/ifs/home/"
}

Example response

HTTP/1.1 200 OK
Date: Fri, 15 Mar 2013 21:51:50 GMT
Server: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0
mod_fastcgi/2.4.6
Allow: DELETE, GET, HEAD, POST, PUT
x-isi-ifs-spec-version: 1.0
Vary: Accept-Encoding
Content-Encoding: gzip
Keep-Alive: timeout=15, max=335
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

Get namespace access points

Retrieves the namespace access points available for the authenticated user.

Request syntax

GET /namespace/ HTTP/1.1

Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

File system access API 195

Request query parameters
There are no query parameters for this request.

Request headers
This call sends common request headers.

Response header
This call returns common response headers.

Response body
An array of namespace access points is output in JSON. Only the access points that the user has privileges for are returned.

Example request
This example retrieves a list of all access points for the namespace on this cluster by the root user.

GET /namespace/ HTTP/1.1

Host my_cluster:8080
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 200 OK
Allow: GET, HEAD
Connection: Keep-Alive
Content-Type: application/json
Date: Mon, 25 Mar 2013 20:31:33 GMT
Keep-Alive: timeout=15, max=499
Server: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0
mod_fastcgi/2.4.6
Transfer-Encoding: chunked
x-isi-ifs-spec-version: 1.0

{
"namespaces": [
{
"name": "user1",
"path": "/ifs/home/user1"
},
{
"name": "ifs",
"path": "/ifs/"
}
]
}

196 File system access API

Get or set an access control list for a namespace access point
Retrieves or sets the access control list for a namespace access point.

Request syntax

GET /namespace/<access_point>?acl&nsaccess=true HTTP/1.1

Host <hostname>[:<port>]
Content-Length: <length>
Date: <date>
Authorization: <signature>

PUT /namespace/<access_point>?acl&nsaccess=true HTTP/1.1

Host <hostname>[:<port>]
Content-Length: <length>
Date: <date>
Authorization: <signature>

Request query parameters

Parameter Description Default Type Required

Name
acl This parameter is a functional keyword that does N/A N/A Yes
not have a value.
nsaccess Indicates that the operation is on the access N/A Boolean Yes
point instead of the store path. This value must
be set to true. If set to false or left blank,
the request behaves similarly to a GET or PUT
operation.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
The access control list for the namespace access point is returned for the GET operation.
No message body is returned upon success for the PUT operation.

Example request 1
In this example, the GET operation retrieves the access control list from the namespace.

GET /namespace/ifs-ap1?acl&nsaccess=true HTTP/1.1

Host: my_cluster:8080
Authorization: <key>

File system access API 197

Example response 1

HTTP/1.1 200 OK
Date: Mon, 25 Mar 2013 18:42:16 GMT
x-isi-ifs-spec-version: 1.0
Transfer-Encoding: chunked
Content-Type: application/json

{
"acl":[
{
"accessrights":[
"file_read"
],
"accesstype":"allow",
"inherit_flags":[

],
"trustee":{
"id":"UID:2000",
"name":"user1",
"type":"user"
}
}
],
"authoritative":"acl",
"group":{
"id":"GID:0",
"name":"wheel",
"type":"group"
},
"mode":"0060",
"owner":{
"id":"UID:0",
"name":"root",
"type":"user"
}
}

Example request 2
In this example, the request sets an access control list for the access point.

PUT /namespace/ifs-ap1?acl&nsaccess=true HTTP/1.1

Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==
Host: 10.245.107.17:8080
Content-Type:application/json
Content-Length: 140

{
"authoritative":"acl",
"acl":[
{
"trustee":{
"name":"user1",
"type":"user"
},
"accesstype":"allow",
"accessrights":[
"file_read"
],
"op":"add"
}
]
}

198 File system access API

Example response 2

HTTP/1.1 200 OK
Date: Mon, 25 Mar 2013 17:24:55 GMT
Transfer-Encoding: chunked
Content-Type: text/plain
x-isi-ifs-spec-version: 1.0

Get version information for the namespace access protocol

Retrieves the protocol versions that are supported for the current namespace access server.

Request syntax

GET /namespace/?versions HTTP/1.1

Host <hostname>[:<port>]
Content-Length: <length>
Date: <date>
Authorization: <signature>

Request query parameters

Parameter Description Default Type Required

name
versions This parameter is a functional keyword that does N/A N/A Yes
not have a value.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
An array of version strings that are supported by the current namespace API server is output in JSON.

Example request
This example retrieves a list of all versions that are supported for the namespace access server.

GET /namespace/?versions HTTP/1.1

Host my_cluster:8080
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization:<signature>

Example response
This example shows that the namespace access server supports only version 1.0.

HTTP/1.1 200 OK
Date: Thu, 22 Sep 2011 12:00:00 GMT

File system access API 199

 Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

{"versions": ["1.0"]}

Delete a namespace access point

Deletes a namespace access point. Only root users can delete namespace access points. Also, the deletion of a namespace
access point does not delete the namespace resource that the access point references.

Request syntax

DELETE /namespace/<access_point> HTTP/1.1

Host <hostname>[:<port>]
Content-Length: <length>
Date: <date>
Authorization: <signature>

Request query parameters

There are no query parameters for this request.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
No message body is returned upon success.

Example request
This example shows the delete operation for an access point that is named 'user1.'

DELETE /namespace/user1 HTTP/1.1

Host my_cluster:8080
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 200 OK
Date: Thu, 22 Sep 2011 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

200 File system access API

Directory operations
You can perform directory operations on the namespace.

Create a directory
Creates a directory with a specified path.

Request syntax

PUT /namespace/<access_point>/<container_path>[?recursive=<boolean>][?
overwrite=<boolean>] HTTP/1.1
Host <hostname>[:<port>]
Content-Length: <length>
Date: <date>
Authorization: <signature>
x-isi-ifs-target-type: container

Request query parameters

Parameter Description Default Type Required

Name
recursive Creates intermediate folders recursively, when False Boolean No
set to true.
overwrite Deletes and replaces the existing user attributes True Boolean No
and ACLs of the directory with user-specified
attributes and ACLS from the header, when set
to true. Returns an error if the directory exists,
when set to false. If the directory does not exist,
the directory is created and set with the user-
specified attributes and ACLs from the header. If
no ACLs are set in the header, the default mode
is set to 0700.

Request headers

Header Name Description Default Type Required

x-isi-ifs-access- Specifies a predefined ACL value or POSIX mode 0700 (read, String No
control with a string. If this parameter is not provided, write, and start
the mode for the directory is set to 0700 by with owner
default. permissions)
x-isi-ifs-node- Specifies the OneFS node pool name. When set N/A String No
pool-name to ANY, OneFS selects the pool for the directory.
Only users with root access can set this header.
x-isi-ifs-attr- Specifies extended user attributes on the N/A String No
<attr_name> directory. The attributes names are stored in
upper case, and all dashes (-) are converted to
underscores (_).

Response headers
This call returns common response headers.

File system access API 201

Response body
No message body is returned upon success.

Example request
This request creates a directory on the namespace named 'folder1/folder2'.

PUT /namespace/ifs/folder1/folder2/?recursive=true HTTP/1.1

Host my_cluster:8080
x-isi-ifs-target-type: container
Content-Length: <length>
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 200 OK
Date: Thu, 22 Sep 2011 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

Get the attributes for a directory with the HEAD method

Retrieves the attribute information for a specified directory without transferring the contents of the directory. Attributes that
can be displayed are returned only as headers, such as x-isi-ifs-<name>=<value>.

Request syntax

HEAD /namespace/<access_point>/<container_path> HTTP/1.1

Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

Request query parameters

There are no query parameters for this request.

Request headers

Header Name Description Default Type Required

If-Modified-Since Returns directory content only if the directory None HTTP date No
was modified since the specified time. If no
directory content was modified, a 304 message
is returned.
If-Unmodified- Returns directory content only if the directory None HTTP date No
Since was not modified since the specified time. If
there is no unmodified directory content, a
412 message is returned to indicate that the
precondition failed.

202 File system access API

Response headers

Header Name Description Default Type Required

Content- Provides the content encoding that was applied None String No
Encoding to the object content, so that decoding can be
applied when retrieving the content.
Content-Type Provides a standard MIME-type description of binary/octet- String No
the content format. stream
x-isi-ifs-attr- Provides the extended attributes that were set None String No
<attr_name> in the message header. The attribute names
are stored in uppercase, and all dashes (-) are
converted to underscores (_).
x-isi-ifs-missing- Provides the number of attributes that cannot be None String No
attr displayed in the HTTP header. Missing attributes
can be retrieved through the following operation:
GET the extended attributes of a directory.
x-isi-ifs-access- Provides the access mode for the directory in None String No
control octal notation.

Response body
No message body is returned upon success.

Example request

HEAD /namespace/ifs/my_folder/ HTTP/1.1

Host my_cluster:8080
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 200 OK
Date: Thu, 22 Sep 2011 12:00:00 GMT
Connection: close
Server: Apache2/2.2.19
Last-Modified: Wed, 21 Sep 2011 12:00:00 GMT
x-isi-ifs-access-control: 0600
x-isi-ifs-attr-color: red
x-isi-ifs-missing-attr: 1
x-isi-ifs-spec-version: 1.0
x-isi-ifs-target-type: container
Vary: Accept-Encoding
Content-Encoding: gzip
Content-Type: text/xml; charset=UTF-8

Get the extended attributes of a directory

Retrieves the attribute information for a specified directory with the metadata query argument.

Request syntax

GET /namespace/<access_point>/<container_path>?metadata HTTP/1.1

Host <hostname>[:<port>]

File system access API 203

 Date: <date>
Authorization: <signature>

Request query parameters

Parameter Description Default Type Required

Name
metadata This parameter is a functional keyword and does N/A N/A Yes
not have a value.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
The object attribute information is returned in JSON format.

{
"attrs":[
{
"name":"<key_name>",
"value":"<key_value>",
"namespace":"<namespace_value>"
},
...
]
}

NOTE:

The namespace parameter is optional. When this parameter is missing, the attribute is considered to be a system defined
attribute. When <namespace_value> is set to user, the attribute is considered a user-defined attribute.

Example request

GET /namespace/ifs/my_folder/?metadata HTTP/1.1

Host my_cluster:8080
Content-Length : <length>
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 200 OK
Date: Thu, 22 Sep 2011 12:00:00 GMT
Content-Length: <Length>
Content-Type: application/JSON
Connection: close
Server: Apache2/2.2.19

{
"attrs":[
{
"name":"is_hidden",

204 File system access API

 "value":false
},
{
"name":"size",
"value":96
},
{
"name":"block_size",
"value":8192
},
{
"name":"blocks",
"value":4
},
{
"name":"last_modified",
"value":"Fri, 23 Mar 2012 16:32:42 GMT"
},
{
"name":"change_time",
"value":"Fri, 23 Mar 2012 16:32:42 GMT"
},
{
"name":"access_time",
"value":"Fri, 23 Mar 2012 16:32:42 GMT"
},
{
"name":"create_time",
"value":"Wed, 21 Mar 2012 22:06:23 GMT"
},
{
"name":"mtime_val",
"value":1332520362
},
{
"name":"ctime_val",
"value":1332520362
},
{
"name":"atime_val",
"value":1332520362
},
{
"name":"btime_val",
"value":1332367583
},
{
"name":"owner",
"value":"root"
},
{
"name":"group",
"value":"wheel"
},
{
"name":"uid",
"value":0
},
{
"name":"gid",
"value":0
},
{
"name":"id",
"value":2
},
{
"name":"nlink",
"value":6
},
{
"name":"type",
"value":"container"

File system access API 205

 },
{
"name":"mode",
"value":511
}
]
}

Get the contents of a directory

Retrieves a list of files and subdirectories from a directory.

Request syntax

GET /namespace/<access_point>/<container_path>[?<query>] HTTP/1.1

Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

NOTE:

The query argument is optional and can include the parameters in the following table.

Request query parameters

Parameter Description Default Type Required

Name
detail Specifies which object attributes are displayed. None String No
If the detail parameter is excluded, only the
name of the object is returned. You can specify
multiple attribute names in CSV format. If you set
this value to default, the following attributes are
included: name, size, owner, last_modified, type,
group, and mode.
limit Specifies the maximum number of objects to 1000 Integer No
send to the client. You can set the value to a
negative number to retrieve all objects. Also, you
can specify the maximum number of objects to
return when sorting directory entries by opening
a secure shell (SSH) connection to any node in
the cluster, logging in, and running the following
command:

isi_gconfig -t oapi
max_sort_dir_sz=<integer>

resume Specifies a token to return in the JSON result None String No

to indicate when there is a next page. The client
can include the resume token to access the next
page.
sort Specifies one or more attributes to sort on None String No
the directory entries. You can specify multiple
attributes by separating the attributes with a
comma, such as name, size, last_modified. When
sorting is on, the maximum number of objects
returned is 1000. The entries are sorted in the
order that the attributes appear in the list, from
left to right.

206 File system access API

Parameter Description Default Type Required
Name
dir Specifies the sort direction. This value can None String No
be either ascending (ASC) or descending
(DESC).
type Specifies the object type to return, which None String No
can be one of the following values: container,
object, pipe, character_device, block_device,
symbolic_link, socket, or whiteout_file.
hidden Specifies if hidden objects are returned. None Boolean No

Request headers

Header Name Description Default Type Required

If-Modified-Since Returns directory content only if the directory None HTTP date No
was modified since the specified time. If no
directory content was modified, a 304 message
is returned.
If-Unmodified- Returns directory content only if the directory None HTTP date No
Since was not modified since the specified time. If
there is no unmodified directory content, a
412 message is returned to indicate that the
precondition failed.

Response headers

Header Name Description Default Type Required

Content- Provides the content encoding that was applied None String No
Encoding to the object content, so that decoding can be
applied when retrieving the content.
Content-Type Provides a standard MIME-type description of application/json String No
the content format.
x-isi-ifs-attr- Provides the extended attributes that were set in None String No
<attr_name> the message header.
x-isi-ifs-missing- Provides the number of attributes that cannot be None Integer No
attr displayed in the HTTP header.
x-isi-ifs-access- Provides the POSIX mode in octal notation. None String No
control

Response body
An array of objects in the directory is output in JSON format.

Example request
The following request returns the contents of a directory named 'folder1/folder2'.

GET /namespace/folder1/folder2 HTTP/1.1

Host my_cluster:8080
Content-Length: <length>
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

File system access API 207

Example response

HTTP/1.1 200 OK
Date: Thu, 22 Sep 2011 12:00:00 GMT
Content-Type: application/JSON
Connection: close
Server: Apache2/2.2.19

{
"children":[
{
"name":"cover"
},
{
"name":"f2"
},
{
"name":"cover.txt"
},
{
"name":"cover8"
}
]
}

Request example 2
This request returns object details for the directory named 'folder1/folder2'.

GET /namespace/folder1/folder2/?limit=500&detail=default HTTP/1.1

Host my_cluster:8080
Content-Length: 0
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Response example 2

HTTP/1.1 200 OK
Date: Thu, 22 Sep 2011 12:00:00 GMT
Content-Type: application/JSON
Connection: close

{
"resume":"<the_resume_token>",
"children":[
{
"last_modified":"Fri, 18 Nov 2011 22:45:31 GMT",
"name":"cover",
"size":24,
"type":"object",

},
{
"last_modified":"Fri, 18 Nov 2011 20:01:04 GMT",
"name":"f2",
"size":4,
"type":"object",

},
{
"last_modified":"Fri, 18 Nov 2011 22:45:40 GMT",
"name":"finance",
"size":0,
"type":"container",

208 File system access API

 ]
}

Copy a directory
Recursively copies a directory to a specified destination path. Symbolic links are copied as regular files.

Request syntax

PUT /namespace/<access_point>/<container_path> HTTP/1.1

x-isi-ifs-copy-source: /namespace/<access_point>/<source_path>
Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

Request query parameters

Parameter Description Default Type Required

Name
overwrite Specifies if the existing file should be overwritten False Boolean No
when a file with the same name exists.
merge Specifies if the contents of a directory should be False Boolean No
merged with an existing directory with the same
name.
continue Specifies whether to continue the copy operation False Boolean No
on remaining objects when there is a conflict or
error.

Request headers

Header Name Description Default Type Required

x-isi-ifs-copy- Specifies the full path to the source directory. None String Yes
source The source and destination must share the same
access point.
x-isi-ifs-mode- Copies the file/dir mode, ownership, ACL, and None String Yes
mask timestamps information along with file data

Response headers
This call returns common response headers.

Response body
No message body is returned upon success.
For this operation, the HTTP status code 200 OK does not always indicate a complete success. If the response body contains a
JSON message, the operation has partially failed, and the error message is reported in a structured JSON array.
If the server fails to initiate a copy due to an error (such as an invalid copy source), an error is returned. If the server initiates
the copy, and then fails, "copy_errors" are returned in structured JSON format.
Because the copy operation is synchronous, the client cannot stop an ongoing copy or check the status of a copy
asynchronously.

File system access API 209

Example request 1

PUT /namespace/ifs/dest1/ / HTTP/1.1

x-isi-ifs-copy-source: /namespace/ifs/src1/
Host my_cluster:8080
Content-Length: <length>
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Example response 1

HTTP/1.1 200 Ok
Date: Thu, 22 Sep 2011 12:00:00 GMT
Server: Apache2/2.2.19
Content-Encoding: gzip
x-isi-ifs-spec-version: 1.0
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

Example request 2
In this example, the directory 'src1' contains files {f1, f2, f3, f4} and the directory 'dest1' exists and contains files {f1, f2}.

PUT /namespace/ifs/dest1/?merge=true&continue=true HTTP/1.1

x-isi-ifs-copy-source: /namespace/ifs/src1/
Host my_cluster:8080
Content-Length: <length>
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Example response 2

HTTP/1.1 200 OK
Date: Thu, 22 Sep 2011 12:00:00 GMT
Server: Apache2/2.2.19
x-isi-ifs-spec-version: 1.0
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: application/json

{
"copy_errors":[
{
"source":"/ap1/src1/f1",
"target":"/ap1/dest1/f1",
"error_src":"target side",
"message":"target exists(not copied)",

},
{
"source":"/ap1/src1/f2",
"target":"/ap1/dest1/f2",
"error_src":"target side",
"message":"target exists(not copied)"
}
],

210 File system access API

Move a directory
Moves a directory from an existing source to a new destination path.

Request syntax

POST /namespace/<access_point>/<container_path> HTTP/1.1

x-isi-ifs-set-location: /namespace/<access_point>/<dest_path>
Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

Request query parameters

There are no query parameters for this request.

Request headers

Header Name Description Default Type Required

x-isi-ifs-set- Specifies the full path for the destination None String Yes
location directory. The source and destination directories
must be in the same access point.

Response headers
This call returns common response headers.

Response body
No message body is returned upon success.

Example request

POST /namespace/ifs/folder1/folder2/ HTTP/1.1

x-isi-ifs-set-location: /namespace/ifs/dest1/dest2/
Host my_cluster:8080
Content-Length: <length>
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 204 No Content

Date: Thu, 22 Sep 2011 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

File system access API 211

Delete a directory
Deletes the directory at the specified path.

Request syntax

DELETE /namespace/<access_point>/<container_path>[?recursive=<Boolean>] HTTP/1.1

Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

Request query parameters

Parameter Description Default Type Required

Name
recursive Deletes directories recursively, when set to true. False Boolean No
Returns an error if you attempt to delete a
directory that is not empty, when set to false.
When the recursive parameter is set to
true, and there is an error deleting a child, the
operation continues to delete other children. Only
the last error is returned.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
No message body is returned upon success.

Example request

DELETE /namespace/folder1/folder2 HTTP/1.1

Host my_cluster:8080
Content-Length: <length>
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 204 No Content

Date: Thu, 22 Sep 2011 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

212 File system access API

Set attributes on a directory
Sets attributes on a specified directory with the metadata query argument. You can also set attributes with a header when the
directory is created with the header format x-isi-ifs-<name>=<value>.

Request syntax

PUT /namespace/<access_point>/<container_path>?metadata HTTP/1.1

Host <hostname>[:<port>]
Content-Length : <length>
Content-Type : application/JSON
Date: <date>
Authorization: <signature>

{
"action":"<action_value>",
"attrs":[
{
"name":"<key_name>",
"value":"<key_value>",
"namespace":"<namespace_value>",
"op":"<operation_value>"
},
...
]
}

NOTE:

You can omit attribute values or enter "" for the value.

Request query parameters

Parameter Description Default Type Required

Name

metadata The metadata argument must be placed at the N/A String No

first position of the argument list in the URI.

Request body parameters

Parameter Description Default Type Required

Name

action The values for the <action_value> field update String No

are replace or update. Note that the
<action_value> field operates in conjunction with
the <operation_value> field.
To modify the existing attributes, set
both <action_value> and<operation_value> to
update.
To delete the existing attributes,
set <action_value> to update and
<operation_value> to delete.
To remove all extended attributes first,
and then replace the attributes with the
values that are specified in the attrs
parameter, set <action_value> to replace.

File system access API 213

Parameter Description Default Type Required
Name

When <action_value> is set to replace, the

<operation_value> field is ignored.

op The values for the <operation_value> field are update String No

update or delete. The <operation_value> field
is only applicable when <action_value> is set to
update.

namespace Specifies the namespace that is associated with user String No

the attributes set for the directory. The only
supported value for this parameter is user.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
No message body is returned upon success.

Example request

PUT /namespace/ifs/my_folder/?metadata HTTP/1.1

Host my_cluster:8080
Content-Length : <length>
Date: <date>
Authorization: <signature>

{
"action":"replace",
"attrs":[
{
"name":"Manufacture",
"value":"Foo",
"namespace":"user"
}
]
}

Example response

HTTP/1.1 200 OK
Date: Wed, 20 Mar 2013 17:19:15 GMT
Server: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0
mod_fastcgi/2.4.6
Allow: DELETE, GET, HEAD, POST, PUT
x-isi-ifs-spec-version: 1.0
Vary: Accept-Encoding
Content-Encoding: gzip
Keep-Alive: timeout=15, max=500
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

214 File system access API

File operations
You can perform file operations on the namespace.

Create a file object

Creates a file object with a given path. The file is either successfully created in whole, or no file is created at all. Partial files
cannot be created.

Request syntax

PUT /namespace/<access_point>/<file_path>[?overwrite=<Boolean>] HTTP/1.1

Host <hostname>[:<port>]
Content-Length : <length>
Date: <date>
Authorization: <signature>

[Message Body]

Request query parameters

Parameter Description Default Type Required

Name
overwrite If the overwrite parameter is set to true, True Boolean No
the preset user attributes and ACLs of the file
are deleted and replaced with the user-specified
attributes and ACLs from the header. If the
overwrite parameter is set to false and the file
exists, an error message is returned. If the file
does not exist, the file is created and set with
the user-specified attributes and ACLs from the
header.

Request headers

Header Name Description Default Type Required

Content- Specifies the content encoding that was applied None String No
Encoding to the object content, so that decoding can be
applied when retrieving the content.
Content-Type Specifies a standard MIME-type description of binary/octet- String Conditional
the content format. stream
x-isi-ifs-target- Specifies the resource type. This value can be None String Yes.
type container or object.
The value must
be set to 'object.'

x-isi-ifs-access- Specifies a predefined ACL value or POSIX mode 0600 (read, write String No
control with a string in octal string format. with owner
permissions).
x-isi-ifs-attr- Specifies the extended attributes that were set None String No
<attr_name> in the message header. The attributes names
are stored in upper case, and all dashes (-) are
converted to underscores (_).

File system access API 215

Response headers
This call returns common response headers.

Response body
No message body is returned upon success.

Example request

PUT /namespace/ifs/my_folder/picture.jpg HTTP/1.1

Host my_cluster:8080
x-isi-ifs-target-type: object
Content-Type: image/jpeg
Content-Length: 65536
Date: Thu Sep 22 16:06:32 GMT 2011
Authorization: <signature>

[Byte Streams of pictue.jpg]

Example response

HTTP/1.1 201 Created

Date: Thu, 22 Sep 2011 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

Get the contents of a file

Retrieves the contents of a file from a specified path.

Request syntax

GET /namespace/<access_point>/<file_path> HTTP/1.1

Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>
Range: bytes=<byte_range>

Request query parameters

There are no query parameters for this request.

Request headers

Header Name Description Default Type Required

Range Returns the specified range bytes of an object. None String No
Only the basic range is supported. The format is
defined as:

first-byte-pos "-" last-byte-pos

216 File system access API

Header Name Description Default Type Required

The first-byte-pos value in a byte-range-spec

gives the byte-offset of the first byte in a range.
The last-byte-pos value gives the byte-offset
of the last byte in the range; that is, the byte
positions that are specified are inclusive. Byte
offsets start at zero.

If-Modified-Since Returns only files that were modified since the None HTTP date No
specified time. If no files were modified since this
time, a 304 message is returned.
If-Unmodified- Returns only files that were not modified since None HTTP date No
Since the specified time. If there are no unmodified
files since this time, a 412 message is returned
to indicate that the precondition failed.

Response headers

Header Name Description

Content-Encoding Provides the content encoding that was applied to the object content, so that decoding
can be applied when retrieving the content.
Content-Type Provides a standard MIME-type description of the content format.
x-isi-ifs-attr-<attr_name> Provides the extended attributes that were set in the message header when the file was
created.
x-isi-ifs-missing-attr Provides the number of attributes that cannot be displayed in the HTTP header.
x-isi-ifs-access-control Provides the access mode for the file in octal number format.

Response body
No message body is returned upon success.

Example request

GET /namespace/ifs/my_folder/picture.jpg HTTP/1.1

Host my_cluster:8080
Date: Thu Sep 22 16:06:32 GMT 2011
Authorization: <signature>

Example response

HTTP/1.1 200 OK
Date: Thu Sep 22 16:06:32 GMT 2011
Content-Length: 54380
Content-Type: image/jpeg
Connection: close
Server: Apache2/2.2.19

[54380 bytes of data]

File system access API 217

Copy a file
Copies a file to the specified destination path.

Request syntax

PUT /namespace/<access_point>/<file_path>[?overwrite=<Boolean>] HTTP/1.1

x-isi-ifs-copy-source: /namespace/<access_point>/<source_path>
Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

Request query parameters

Parameter Description Default Type Required

Name
overwrite Specifies if the existing file should be overwritten False Boolean No
when a file with the same name exists.

Request headers

Header Name Description Default Type Required

x-isi-ifs-copy- Specifies the full path of the source. N/A String Yes
source
The source and destination paths must be in the
same access point.

Response headers
This call returns common response headers.

Response body
No message body is returned upon success. For this operation, the HTTP status code 200 OK may not indicate a complete
success.
If the response body contains a JSON message, the operation has partially failed. If the server fails to initiate a copy due to
an error (such as an invalid copy source), an error is returned. If the server initiates the copy, and then fails, "copy_errors"
are returned in structured JSON format. Because the copy operation is synchronous, the client cannot stop an ongoing copy
operation or check the status of a copy operation asynchronously.

Example request 1
This example shows a successful copy.

PUT /namespace/ifs/folder1/myfile HTTP/1.1

x-isi-ifs-copy-source: /namespace/ifs/source1/myfile
Host my_cluster:8080
Content-Length: <length>
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

218 File system access API

Example response 1

HTTP/1.1 200 Ok
Date: Thu, 22 Sep 2011 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

Example request 2
This example shows a failed copy, where the file is not overwritten.

PUT /namespace/accesspoint1/directory1/file2_copy HTTP/1.1

Host 10.245.105.110:8080
x-isi-ifs-copy-source: /namespace/accesspoint1/directory1/file2
Date: Wed, 20 Mar 2013 21:33:55 GMT
Authorization: <signature>

Example response 2

HTTP/1.1 200 OK
Date: Wed, 20 Mar 2013 21:33:55 GMT
Server: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0
mod_fastcgi/2.4.6
Allow: DELETE, GET, HEAD, POST, PUT
x-isi-ifs-spec-version: 1.0
Keep-Alive: timeout=15, max=500
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: application/json

{
"copy_errors":[
{
"error_src":"target side",
"message":"target exists(not copied)",
"source":"/accesspoint1/directory1/file2",
"target":"/accesspoint1/directory1/file2_copy"
}
],
"success":false
}

Move a file
Moves a file to a destination path that does not yet exist.

Request syntax

POST /namespace/<access_point>/<file_path> HTTP/1.1

x-isi-ifs-set-location: /namespace/<access_point>/<dest_path>
Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

Request query parameters

There are no query parameters for this request.

File system access API 219

Request headers

Header Name Description Default Type Required

x-isi-ifs-set- Specifies the full path of the destination file. The None String Yes
location source and destination paths must be in the same
access point.
If the x-isi-ifs-set-location hovers over a file
name that is different than the source file name,
the user can rename the file.

Response headers
This call returns common response headers.

Response body
No message body is returned upon success.

Example request

POST /namespace/ifs/folder1/myfile HTTP/1.1

x-isi-ifs-set-location: /namespace/ifs/dest1/myfile
Host my_cluster:8080
Content-Length: <length>
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 204 Non Content

Date: Thu, 22 Sep 2011 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

Delete a file
Deletes the specified file.

Request syntax

DELETE /namespace/<access_point>/<file_path> HTTP/1.1

Host <hostname>[:<port>]
Date:<date>
Authorization: <signature>

Request query parameters

There are no query parameters for this request.

Request headers
This call sends common request headers.

220 File system access API

Response headers
This call returns common response headers.

Response body
No message body is returned upon success.

Example request

DELETE /namespace/ifs/my_folder/test.txt HTTP/1.1

Host my_cluster:8080
Content-Length: <length>
Date: Thu, 22 Sep 2011 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 204 No Content

Date: Thu, 22 Sep 2011 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

Clone a file
Clone a file to the destination path. If the parameter is set as a snapshot name, the file is cloned from that snapshot.

Request syntax

PUT /namespace/<access_point>/<file_path>[?<clone>][&<snapshot>][&<overwrite>] HTTP/1.1

x-isi-ifs-copy-source: <source_file_path>
Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

Request query parameters

Parameter Description Default Type Required

Name
clone Set this parameter to true in order to clone a file. False Boolean No
snapshot Specifies a snapshot name to clone the file from. N/A String No
If a snapshot name is not given, a temporary
snapshot is created. The temporary snapshot is
deleted after the cloning operation is complete.
overwrite Specifies if an existing file should be overwritten False Boolean No
by a new file with the same name.

File system access API 221

Request headers

Header Name Description Default Type Required

x-isi-ifs-copy- Specifies the full path of the source. N/A String Yes
source
The source and destination paths must be in the
same access point.

Response headers
This call returns common response headers.

Response body
No response body is returned upon success.

Example request

PUT /namespace/ifs/folder1/myfile?clone=true HTTP/1.1

x-isi-ifs-copy-source: /namespace/ifs/source1/myfile
Host my_cluster:8080
Content-Length : 0
Date: <date>
Authorization: <signature>

Example response

HTTP/1.1 200 OK
Date: Thu, 21 Mar 2013 14:33:29 GMT
Content-Length: 0
Connection: close

Set attributes on a file

Sets attributes on a specified file with the metadata query argument through the JSON body. You can also set attributes with a
header when the file is created through a header with the format: x-isi-ifs-<name>=<value>.

Request syntax

PUT /namespace/<access_point>/<file_path>?metadata HTTP/1.1

Host <hostname>[:<port>]
Content-Length : <length>
Content-Type : application/JSON
Date: <date>
Authorization: <signature>

{
"action":"<action_value>",
"attrs":[
{
"name":"<key_name>",
"value":"<key_value>",
"namespace":"<namespace_value>",
"op":"<operation_value>"
},
...

222 File system access API

 ]
}

NOTE:

You can modify only the <content_type> and user specified attributes. All other system attributes are ignored.

Request query parameters

Parameter Description Default Type Required

Name
metadata The metadata argument must be placed at the N/A String No
first position of the argument list in the URI.

Request body parameters

Parameter Description Default Type Required

Name
action The values for the <action_value> field are update String No
replace or update. The <action_value>
field operates in conjunction with the
<operation_value> field.
To modify the existing attributes, set both
<action_value> and <operation_value> fields to
update.
To delete the existing attribute, set
the <action_value> field to update and
<operation_value> to delete.
To remove all extended attributes first
and then replace the attributes with the
values that are specified in the attrs
parameter, set <action_value> to replace.
When <action_value> is set to replace, the
<operation_value> field is ignored.

op The values for the <operation_value> field are update String No

update or delete. The <operation_value> field
is only applicable when <action_value> is set to
update.

namespace Specifies the value for the namespace that user String No
the attribute associates with a directory. This
parameter must be set to user if the attributes
are specified by users.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
No response body is returned upon success.

File system access API 223

Example request

PUT /namespace/accesspoint1/my_folder/mytest.txt?metadata HTTP/1.1

Host my_cluster:8080
Content-Length : <length>
Date: <date>
Authorization: <signature>

{
"action":"replace",
"attrs":[
{
"name":"Manufacture",
"value":"Foo",
"namespace":"user"
},
{
"name":"user.Material",
"value":"Steel",
"namespace":"user"
}
]
}

Example response

HTTP/1.1 200 OK
Date: Thu, 21 Mar 2013 14:33:29 GMT
Server: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0
mod_fastcgi/2.4.6
Allow: DELETE, GET, HEAD, POST, PUT
x-isi-ifs-spec-version: 1.0
Vary: Accept-Encoding
Content-Encoding: gzip
Keep-Alive: timeout=15, max=500
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: text/plain

Get the attributes for a file with the HEAD method

Retrieves the attribute information for a specified file. Attributes are returned as headers only if they can be displayed.

Request syntax

HEAD /namespace/<access_point>/<file_path> HTTP/1.1

Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

Request query parameters

There are no query parameters for this request.

224 File system access API

Request headers

Header Name Description Default Type Required

If-Modified-Since Returns only file content that was modified None HTTP date No
since the specified time. If no file content was
modified, a 304 message is returned.
If-Unmodified- Returns only file content that was not modified None HTTP date No
Since since the specified time. If there is no unmodified
file content, a 412 message is returned to indicate
that the precondition failed.

Response headers

Header Name Description Default Type Required

Content- Provides the content encoding that was applied None String No
Encoding to the object content, so that decoding can be
applied when retrieving the content.
Content-Type Provides a standard MIME-type description of binary/octet- String No
the content format. stream
x-isi-ifs-attr- Provides the extended attributes that were set in None String No
<attr_name> the message header.
x-isi-ifs-missing- Provides the number of attributes that cannot be None Integer No
attr displayed in the HTTP header.
The missing attributes can be retrieved through
the operation: GET extended attributes of a file
operation.

x-isi-ifs-access- Provides a predefined ACL value or POSIX mode 0700 String No

control with a string, such as private, private_read,
public_read, public_read_write, or public.

Response body
No message body is returned upon success.

Example request

HEAD /namespace/ifs/my_folder/picture.jpg HTTP/1.1

Host my_cluster:8080
Date: Thu Sep 22 16:06:32 GMT 2011
Authorization: <signature>

Example response

HTTP/1.1 200 OK
Date: Thu Sep 22 16:06:32 GMT 2011
Server: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0
mod_fastcgi/2.4.6
Allow: DELETE, GET, HEAD, POST, PUT
Last-Modified: Wed, 20 Mar 2013 18:16:17 GMT
x-isi-ifs-access-control: 0600
x-isi-ifs-attr-color: red
x-isi-ifs-missing-attr: 1
x-isi-ifs-spec-version: 1.0
x-isi-ifs-target-type: object

File system access API 225

Get the extended attributes of a file
Retrieves the attribute information for a specified file with the metadata query argument.

Request syntax

GET /namespace/<access_point>/<file_path>?metadata HTTP/1.1

Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

Request query parameters

Parameter Description Default Type Required

Name
metadata The metadata argument must be placed at the N/A String No
first position of the argument list in the URI.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
The object attribute information is returned in JSON format.

{
"attrs":[
{
"name":"<key_name>",
"value":"<key_value>",
"namespace":"<namespace_value>"
},
...
]
}
}

NOTE:

The namespace parameter is optional. When this parameter is missing, the attribute is considered to be a system defined
attribute. When the <namespace_value> field is set to user, the attribute is considered a user-defined attribute.

Example request

GET /namespace/accesspoint1/directory1/file1?metadata HTTP/1.1

Host: 10.245.105.110:8080
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:19.0) Gecko/20100101 Firefox/19.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Cookie: _SID_=20130321154838-cffed57ca0a91f15a7dca80fc88ed0a8;
isisessid=7651c367-71d1-4ff1-9dd0-1eee09a4b03d; legacy=1; ys-lastStatusDashView=n%3A1;
ys-monitoringView=s%3ALIVE; ys-monitoringData=s%3AAVG

226 File system access API

 Connection: keep-alive
Cache-Control: max-age=0

Example response

HTTP/1.1 200 Ok
Date: Thu, 21 Mar 2013 19:58:11 GMT
Server: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0
mod_fastcgi/2.4.6
Allow: DELETE, GET, HEAD, POST, PUT
x-isi-ifs-spec-version: 1.0
Keep-Alive: timeout=15, max=436
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: application/json

{
"attrs": [
{
"name": "content_type",
"value": "text/xml; charset=UTF-8"
},
{
"name": "is_hidden",
"value": false
},
{
"name": "size",
"value": 27
},
{
"name": "block_size",
"value": 8192
},
{
"name": "blocks",
"value": 52
},
{
"name": "last_modified",
"value": "Wed, 20 Mar 2013 18:16:17 GMT"
},
{
"name": "change_time",
"value": "Wed, 20 Mar 2013 18:16:17 GMT"
},
{
"name": "access_time",
"value": "Wed, 20 Mar 2013 18:16:17 GMT"
},
{
"name": "create_time",
"value": "Wed, 20 Mar 2013 18:16:17 GMT"
},
{
"name": "mtime_val",
"value": 1363803377
},
{
"name": "ctime_val",
"value": 1363803377
},
{
"name": "atime_val",
"value": 1363803377
},
{
"name": "btime_val",
"value": 1363803377
},

File system access API 227

 {
"name": "owner",
"value": "root"
},
{
"name": "group",
"value": "wheel"
},
{
"name": "uid",
"value": 0
},
{
"name": "gid",
"value": 0
},
{
"name": "id",
"value": 4300276817
},
{
"name": "nlink",
"value": 1
},
{
"name": "type",
"value": "object"
},
{
"name": "mode",
"value": "0600"
},
{
"name": "Manufacture",
"namespace": "user",
"value": "Foo"
},
{
"name": "user.Material",
"namespace": "user",
"value": "Steel"
}
]
}

Access control lists

You can configure access control lists (ACLs) or permissions modes for namespace directories and files.
For detailed information on access control lists, see the OneFS Administration Guide.

Access control personas

Personas are a union of a user ID (UID), name, and type. Personas represent users and groups for access control list (ACL)
operations.
The JSON format for personas is:

{
"id":"<ID>",
"name":"<name>",
"type":"<type>"
}

228 File system access API

Where

<ID>: <"USER" | "GROUP" | "SID" | "UID" | "GID"> : <the ID string>

<name>: <the normal user name in a string>
<type>: <user, group, or wellknown>

For PUT operations, you can specify either the ID or both the name and type. The ID value takes precedence when all fields are
available.

Access rights for directories

The following table lists the access rights for directories.

Access rights Functionality

list The right to list entries
add_file The right to create a file in the directory
add_subdir The right to create a subdirectory
delete_child The right to delete children, including read-only files
traverse The right to access files in subdirectories
dir_read_attr The right to read directory attributes
dir_write_attr The right to write directory attributes
dir_read_ext_attr The right to read extended directory attributes
dir_write_ext_attr The right to write extended directory attributes
dir_gen_read The right to list entries, read attributes, read extended attributes, and read access control lists.
dir_gen_write The right to create files, create subdirectories, write attributes, write extended attributes, and read
access control lists.
dir_gen_execute The right to access files in subdirectories, and read access lists.
dir_gen_all Includes the rights that are specified in dir_gen_read, dir_gen_write, dir_gen_execute, delete_child,
std_read_dac, std_write_dac, std_write_owner, and std_delete.

Access rights for files

The following table lists the access rights for files.

Access rights Functionality

file_read The right to read file data.
file_write The right to write file data.
append The right to append to a file.
Run The right to run a file.
file_read_attr The right to read file attributes.
file_write_attr The right to write file attributes.
file_read_ext_attr The right to read extended file attributes.
file_write_ext_attr The right to write extended file attributes.
file_gen_read The right to read files, read attributes, read extended attributes, and read access control lists.
file_gen_write The right to write to the file, append to the file, write file attributes, write extended file attributes, and
read access control lists.

File system access API 229

Access rights Functionality
file_gen_execute The right to run files, and read access control lists.
file_gen_all Includes the rights that are specified by file_gen_read, file_gen_write, file_gen_execute, std_read_dac,
std_write_dac, std_write_owner, and std_delete.

Access rights for files and directories

The following table describes the access rights for both files and directories.

Access rights Functionality

std_read_dac The right to read the access control list of the directory or file.
std_write_dac The right to write the access control list of the directory or file.
std_write_owner The right to change the owner of the directory or file.
std_delete The right to delete the current directory or file.
modify Includes the following access rights for a directory: add_file, add_subdir, dir_write_ext_attr,
dir_write_attr, delete_child, std_delete, std_write_dac and std_write_owner.
Includes the following access rights for a file: file_write, append, file_write_ext_attr, file_write_attr,
std_delete, std_write_dac and std_write_owner.

Inherited access rights

The following table lists the inheritance flags for directories and subdirectories. Inheritance flags specify the access rights
inherited by the children of a directory.

Inheritance Flags Functionality

object_inherit Only files inherit access rights from their parent directory.
container_inherit Only directories inherit access rights from their parent directory.
no_prop_inherit Stops the propagation of inherited rights for directories and files.
inherit_only Access rights do not apply for the current directory, but are applied to subdirectories and files when
they are inherited.
inherited_ace Indicates that the access control list of the current directory or file was inherited from a parent
directory or file.

Get the ACL of a directory

Retrieves the access control list of the directory for the authenticated user.

Request syntax

GET /namespace/<access_point>/<container_path>/<container_name>?acl HTTP/1.1

Host: <hostname>[:<port>]
Date: <date>
Authorization: <signature>

230 File system access API

Request query parameters

Parameter Description Default Type Required

Name
acl The acl argument must be placed at the first N/A String Yes
position of the argument list in the URI.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body

HTTP/1.1 200 OK
Date: Tue, 22 May 2012 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

{
"owner":{
"id":"<owner id>",
"name":"<owner name>",
"type":"<type>"
},
"group":{
"id":"<group id>",
"name":"<group name>",
"type":"<type>"
},
"authoritative":"acl"|"mode",
"mode":"<POSIX mode>",
"acl":[
{
"trustee":{
"id":"<trustee id>",
"name":"<trustee name>",
"type":"<trustee type>"
},
"accesstype":"allow" | "deny",
"accessrights":"<accessrights_list>",
"inherit_flags":"<inherit_flags_list>"
}
]
}

Response body parameters

Parameter Name Description

owner Provides the JSON object for the owner persona.
group Provides the JSON object for the group persona of the owner.
authoritative Can be set to acl or mode.
If the directory has access rights set, then this field is returned as acl.
If the directory has POSIX permissions set, then this field is returned as mode.

File system access API 231

Parameter Name Description
mode Provides the POSIX mode.
acl Provides the JSON array of access rights.
access type Can be set to allow or deny.
allow: Allows access to the directory based on the access rights set for the trustee.
deny: Denies access to the directory based on the access rights set for the trustee.

access rights Provides the list of access rights that are defined for the directory.
inherit_flags Provides the inherit flags set for the directory.

Example request

GET /namespace/ifs/dir1/dir2/dir?acl HTTP/1.1

Host: my_cluster:8080
Date: Tue, 22 May 2012 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 200 OK
Date: Tue, 22 May 2012 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

{
"owner":{
"id":"UID:0",
"name":"root",
"type":"user"
},
"group":{
"id":"GID:0",
"name":"wheel",
"type":"group"
},
"authoritative":"acl",
"mode":"0722",
"acl":[
{
"trustee":{
"id":"UID:2001",
"name":"foo1",
"type":"user"
},
"accesstype":"allow",
"accessrights":[
"dir_gen_read",
"dir_gen_write"
],
"inherit_flags":[
"container_inherit"
]
},
{
"trustee":{
"id":"GID:23",
"name":"group1",
"type":"group"
},
"accesstype":"allow",
"accessrights":[

232 File system access API

 "dir_gen_read"
]
}
]
}

Get the ACL of a file

Retrieves the access control list of the file for the authenticated user.

Request syntax

GET /namespace/<access_point>/<container_path>/<file_name>?acl HTTP/1.1

Host: <hostname>[:<port>]
Date: <date>
Authorization: <signature>

Request query parameters

Parameter Description Default Type Required

Name
acl The acl argument must be placed at the first N/A String Yes
position of the argument list in the URI.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body

HTTP/1.1 200 OK
Date: Tue, 22 May 2012 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

{
"owner":{
"id":"<owner id>",
"name":"<owner name>",
"type":"<type>"
},
"group":{
"id":"<group id>",
"name":"<group name>",
"type":"<type>"
},
"authoritative":"acl"|"mode",
"mode":"<POSIX mode>",
"acl":[
{
"trustee":{
"id":"<trustee id>",
"name":"<trustee name>",
"type":"<trustee type>"

File system access API 233

 },
"accesstype":"allow"|"deny",
"accessrights":"<accessrights_list>",
"inherit_flags":"<inherit_flags>"
}
]
}

Response body parameters

Parameter Name Description

owner Provides the JSON object for the owner persona.
group Provides the JSON object for the group persona of the owner.
authoritative Can be set to acl or mode.
If the directory has access rights set, then this field is returned as acl.
If the directory has POSIX permissions set, then this field is returned as mode.

acl Provides the JSON array of access rights.

access type Can be set to allow or deny.
allow: Allows access to the file based on the access rights set for the trustee.
deny: Denies access to the file based on the access rights set for the trustee.

access rights Provides the list of access rights that are defined for the file.
inherit_flags Provides the inherit flags set for the file.

Example request

GET /namespace/ifs/dir1/dir2/file1?acl HTTP/1.1

Host: my_cluster:8080
Date: Tue, 22 May 2012 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 200 OK
Date: Thu, 12 Jan 2011 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

{
"owner":{
"id":"UID:0",
"name":"root",
"type":"user"
},
"group":{
"id":"GID:0",
"name":"wheel",
"type":"group"
},
"authoritative":"acl",
"mode":"0022",
"acl":[
{
"trustee":{
"id":"UID:2000",
"name":"foo2",

234 File system access API

 "type":"user"
},
"accesstype":"allow",
"accessrights":[
"file_gen_read",
"file_gen_write"
]
},
{
"trustee":{
"id":"GID:1001",
"name":"group2",
"type":"group"
},
"accesstype":"allow",
"accessrights":[
"file_gen_read"
]
}
]
}

Set the ACL for a directory when the directory is created

Sets the access control list for a directory by setting the headers when the directory is created.

Request syntax

PUT /namespace/<access_point>/<container_path>/<container_name> HTTP/1.1

Host: <hostname>[:<port>]
Content-Length: <length>
Date: <date>
Authorization: <signature>
x-isi-ifs-access-control : "private_read" | "private" | "public_read" |
"public_read_write" | "public" | "<POSIX mode>"

NOTE:

The attribute x-isi-ifs-access-control can be set to a predefined ACL value or to a POSIX mode in octal string. If this header
is not specified, the directory mode is set to 0700 by default when the directory is created.

Predefined ACL value Access rights Access rights displayed

private_read The directory owner has the following rights: list Directory owner: "access rights":
entries, read attributes, read extended attributes, ["dir_gen_read","dir_gen_execute","std_write_d
access files in subdirectories, read access control ac"],"inherit_flags":[]
list, and write access control list.
private The directory owner has the following rights: list Directory owner:"access rights":
entries, read attributes, read extended attributes, ["dir_gen_all"],"inherit_flags":[]
read access control list, create files, create
subdirectories, write attributes, write extended
attributes, access files in subdirectories, delete
children (including read-only files), change owner,
write access control list, and delete current
directory.
public_read The directory owner has the following rights: list Directory owner: "access rights":
entries, read attributes, read extended attributes, ["dir_gen_all"],"inherit_flags":[]
read access control list, create files, create
All users: "access rights":
subdirectories, write attributes, write extended
["dir_gen_read","dir_gen_execute"],"inherit_flag
attributes, access files in subdirectories, delete
s":[]
children (including read-only files), change owner,
write the access control list, and delete current
directory.

File system access API 235

Predefined ACL value Access rights Access rights displayed

All users have the following rights: list entries,

read attributes, read extended attributes, read
access control lists, and access files in
subdirectories.

public_read_write The directory owner has the following rights: list Directory owner: "access rights":
entries, read attributes, read extended attributes, ["dir_gen_all"],"inherit_flags":[]
read access control list, create files, create
All users: "access rights":
subdirectories, write attributes, write extended
["dir_gen_read","dir_gen_write","dir_gen_execu
attributes, access files in subdirectories, delete
te"],"inherit_flags":[]
children (including read-only files), change owner,
write the access control list, and delete current
directory.
All users have the following rights: list entries,
read attributes, read extended attributes,
read access control lists, create files, create
subdirectories, write attributes, write extended
attributes, and access files in subdirectories.

public All users have the following rights: list entries, All users: "access rights":
read attributes, read extended attributes, ["dir_gen_all"],"inherit_flags":[]
read access control list, create files, create
subdirectories, write attributes, write extended
attributes, access files in subdirectories, delete
children (including read-only files), change owner,
write access control list, and delete current
directory.

The POSIX mode is an absolute mode that is constructed from the sum of one or more octal numbers that are listed in the
following table.

Octal Description
number
4000 The set-user-ID-on-execution bit. Executable files with this bit have their UID set to the UID of the file owner.
2000 The set-group-ID-on-execution bit. Executable files with this bit have their GID set to the GID of the file owner.
1000 The sticky bit.
0400 Allows read by owner.
0200 Allows write by owner.
0100 For files, allows execution by owner. For directories, allows directory queries by owner.
0040 Allows read by group members.
0020 Allows write by group members.
0010 For files, allows execution by group members. For directories, allows directory queries by group members.
0004 Allows read by others.
0002 Allows write by others.
0001 For files, allows execution by others. For directories, allows directory queries by others.

Request query parameters

There are no query parameters for this request.

236 File system access API

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
There is no message body for this response.

Example request

PUT /namespace/ifs/dir1/dir2/dir HTTP/1.1

Host: my_cluster:8080
Content-Length: <length>
Date: Tue, 22 May 2012 12:00:00 GMT
Authorization: <signature>
x-isi-ifs-access-control: "public_read"

Example response

HTTP/1.1 200 OK
Date: Tue, 22 May 2012 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

Set the ACL for a file when the file is created

Sets the access control list for a file by setting the headers when the file is created.

Request syntax

PUT /namespace/<access_point>/<container_path>/<file_name> HTTP/1.1

Host: <hostname>[:<port>]
Content-Length: <length>
Date: <date>
Authorization: <signature>
x-isi-ifs-access-control : "private_read" | "private" | "public_read" |
"public_read_write" | "public" | "<POSIX mode>"

NOTE:

The attribute x-isi-ifs-access-control can be set to a predefined ACL value or to POSIX mode with octal string. By default,
the mode for the file is set to 0600.

Predefined ACL value Access rights Access rights displayed

private_read The file owner has the following rights: read files, File owner: "accessrights":
read attributes, read extended attributes, read ["file_gen_read","file_gen_execute","std_write
access control lists, run files, and write access _dac"],"inherit_flags":[]
control list.
private The file owner has the following rights: read file, File owner:"accessrights":
read attributes, read extended attributes, read ["file_gen_all"],"inherit_flags":[]
access control list, write to the file, append to

File system access API 237

Predefined ACL value Access rights Access rights displayed
the file, write file attributes, write extended file
attributes, run file, write, or modify the access
control list, change owner, and delete current file.
public_read The file owner has the following rights: read file, File owner: "accessrights":
read attributes, read extended attributes, read ["file_gen_all"],"inherit_flags":[]
access control list, write to the file, append to
All users: "accessrights":
the file, write file attributes, write extended file
["file_gen_read","file_gen_execute"],"inherit_f
attributes, run file, write, or modify the access
lags":[]
control list, change owner, and delete current file.
All users have the following rights: read files, read
attributes, read extended attributes, read access
control lists, and run files.

public_read_write The file owner has the following rights: read file, File owner: "accessrights":
read attributes, read extended attributes, read ["file_gen_all"],"inherit_flags":[]
access control list, write to the file, append to
All users: "accessrights":
the file, write file attributes, write extended file
["file_gen_read","file_gen_write","file_gen_ex
attributes, run file, write/modify the access control
ecute"],"inherit_flags":[]
list, change owner, and delete current file.
All users have the following rights: read files, read
attributes, read extended attributes, read access
control lists, write to the file, append to the file,
write file attributes, write extended file attributes,
and run files.

public All users have the following rights: read file, read All users: "accessrights":
attributes, read extended attributes, read access ["file_gen_all"],"inherit_flags":[]
control list, write to the file, append to the file,
write file attributes, write extended file attributes,
run file, write/modify the access control list,
change owner, and delete current file.

The POSIX mode is an absolute mode, which consists of an octal number that is constructed from the sum of one or more octal
numbers that are listed in the following table.

Octal Description
number
4000 The set-user-ID-on-execution bit. Executable files with this bit have their uid set to the uid of the file owner.
2000 The set-group-ID-on-execution bit. Executable files with this bit have their gd set to the gid of the file owner.
1000 The sticky bit.
0400 Allows read by owner.
0200 Allows write by owner.
0100 For files, allows execution by owner. For directories, allows directory queries by owner.
0040 Allows read by group members.
0020 Allows write by group members.
0010 For files, allows execution by group members. For directories, allows directory queries by group member.
0004 Allows read by others.
0002 Allows write by others.
0001 For files, allows execution by others. For directories, allows directory queries by others.

238 File system access API

Request query parameters
There are no query parameters for this request.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
There is no message body for this response.

Example request

PUT /namespace/ifs/dir1/dir2/file HTTP/1.1

Host: my_cluster:8080
Content-Length: <length>
Date: Tue, 22 May 2012 12:00:00 GMT
Authorization: <signature>
x-isi-ifs-access-control: "public_read"

Example response

HTTP/1.1 200 OK
Date: Tue, 22 May 2012 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

Set the ACL of a directory

Sets the access control list of the directory.

Request syntax

PUT /namespace/<access_point>/<container_path>/<container_name>?acl HTTP/1.1

Host: <hostname>[:<port>]
Content-Length: <length>
Date: <date>
Authorization: <signature>

{
"owner":{
"id":"<owner id>",
"name":"<owner name>",
"type":"<type>"
},
"group":{
"id":"<group id>",
"name":"<group name>",
"type":"<type>"
},
"authoritative":"acl"|"mode",
"mode":"<POSIX mode>",

File system access API 239

 "action":"<action_value>",
"acl":[
{
"trustee":{
"id":"<trustee id>",
"name":"<trustee name>",
"type":"<trustee type>"
},
"accesstype":"allow"|"deny",
"accessrights":"<accessrights_list>",
"inherit_flags":"<inherit_flags_list>",
"op":"<operation_value>"
}
]
}

Request query parameters

Parameter Description Default Type Required

Name
acl The acl argument must be placed at the first N/A String Yes
position of the argument list in the URI.

Request body parameters

Parameter Description Default Type Required

Name
owner Specifies the JSON object for the owner N/A JSON object No
persona. You should only specify the owner
persona if you want to change the owner of the
target.
group Specifies the JSON object for the group persona N/A JSON object No
of the owner. You should only specify the group
persona if you want to change the group of the
target.
authoritative The authoritative field is mandatory and can take N/A String Yes
the value of either acl or mode.
acl: You can modify the owner, group
personas, or access rights for the directory by
setting the authoritative field to acl and by
setting <action_value> to update. When the
authoritative field is set to acl, access rights
are set for the directory from the acl structure.
Any value specified for the mode parameter is
ignored.
NOTE: When the authoritative field is
set to acl, the default value for the
<action_value> field is replace. If the
<action_value> field is set to replace, the
system replaces the existing access rights
of the directory with the access rights
specified in the acl structure. If the acl
structure is empty, the existing access rights
are deleted and default access rights are
provided by the system. The default access
rights for directories are read access control

240 File system access API

Parameter Description Default Type Required
Name

list (‘std_read_dac’) and write access control

list (‘std_write_dac’) for the owner.
mode: You can modify the owner and group
personas by setting the authoritative field to
mode. When the authoritative field is set
to mode, POSIX permissions are set on the
directory. The <action_value> field and acl
structure are ignored. If mode is set on a
directory that already has access rights or if
access rights are set on a directory that already
has POSIX permissions set, the result of the
operation varies based on the Global ACL Policy.

mode Specifies the POSIX mode. 0700 for Octal number, No

directories specified as a
string
0600 for files

action The <action_value> field is applied when the replace String No

authoritative field is set to acl. You can set
the <action_value> field to either update or
replace.
When set to update, the existing access control
list of the directory is modified with the access
control entries specified in the acl structure of
the JSON body.
When set to replace, the entire access control
list is deleted and replaced with the access
control entries specified in the acl structure of
the JSON body.
Additionally, when set to replace, the acl
structure is optional. If the acl structure is left
empty, the entire access control list is deleted
and replaced with the system set default access
rights. The default access rights for directories
are read access control list (‘ std_read_dac’) and
write access control list (‘ std_write_dac’) for
the owner.

acl Specifies the JSON array of access rights. N/A JSON object Conditional.
Mandatory when
the
<action_value>
field is set to
update; optional
when the
<action_value>
is set to
replace

accesstype Can be set to allow or deny. N/A String Yes, unless the
<action_value>
allow: Allows access to the directory based on
field is set to
the access rights set for the trustee. replace and
deny: Denies access to the directory based on the acl
the access rights set for the trustee. structure is
empty.

File system access API 241

Parameter Description Default Type Required
Name
accessrights Specifies the access right values defined for the N/A List of string Conditional
directory. values
Mandatory when
the
<action_value>
field is set to
update and the
<operation_value
> field is set to
either add or
replace and
the <inherit_
flags_list> field is
unspecified.
Optional when
the
<action_value>
is set to update
and the
<operation_value
> field is set to
delete, or
when the
<action_value>
field is set to
replace.

inherit_flags Specifies the inherit flag values for directories. N/A List of string Conditional
values
op The <operation_value> field is applied when the add, when String No
<action_value> field is set to update. You <action_value>
can set the <operation_value> field to add, is set to
replace, or delete. If no <operation_value> update.
field is specified, the default value is add.
add: Creates an access control entry (ACE) if
an ACE is not already present for a trustee and
trustee access type. If an entry is already present
for that trustee and trustee access type, this
operation appends the access rights list to the
current ACE for that trustee and trustee access
type.
delete: Removes the access rights list provided
from the existing ACE for a trustee and trustee
access type. If the input access rights list is
empty , the entire ACE that corresponds to the
trustee and trustee access type is deleted.
replace: Replaces the entire ACE for the
trustee and trustee access type with the input
access rights list.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

242 File system access API

Response body
There is no message body for this response.

Example request 1
This sample sets the ACL of a directory.

PUT /namespace/ifs/dir1/dir2/dir?acl HTTP/1.1

Host: my_cluster:8080
Content-Length: <length>
Date: Tue, 22 May 2012 12:00:00 GMT
Authorization: <signature>
Content-Type: application/json

{
"authoritative":"acl",
"action":"update",
"acl":[
{
"trustee":{
"id":"UID:1001",
"name":"user23",
"type":"user"
},
"accesstype":"allow",
"accessrights":[
"std_write_dac"
],
"inherit_flags":[
"object_inherit",
"inherit_only"
],
"op":"add"
},
{
"trustee":{
"id":"GID:1210",
"name":"group12",
"type":"group"
},
"accesstype":"allow",
"accessrights":[],
"op":"delete"
}
]
}

Example response 1

HTTP/1.1 200 OK
Date: Tue, 22 May 2012 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

Example request 2
This sample replaces the existing ACL of the directory with the access control entries that are specified in the acl structure. If
the acl structure is empty, the existing ACL is replaced with default system values. The directory owner has default read and
write access to the access control list.

PUT /namespace/ifs/dir1/dir2/dir?acl HTTP/1.1

Host: my_cluster:8080
Content-Length: <length>

File system access API 243

 Date: Tue, 22 May 2012 12:00:00 GMT
Authorization: <signature>
Content-Type: application/json

{
"owner":{
"id":"UID:2001",
"name":"foo1",
"type":"user"
},
"group":{
"id":"GID:0",
"name":"wheel",
"type":"group"
},
"authoritative":"acl",
"action":"replace",
"acl":[]
}

Example response 2

HTTP/1.1 200 OK
Date: Tue, 22 May 2012 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

Set the ACL of a file

Sets the access control list of a file.

Request syntax

PUT /namespace/<access_point>/<container_path>/<file_name>?acl HTTP/1.1

Host: <hostname>[:<port>]
Content-Length: <length>
Date: <date>
Authorization: <signature>
x-isi-ifs-target-type: object
Content-Type: application/json

{
"owner":{
"id":"<owner id>",
"name":"<owner name>",
"type":"<type>"
},
"group":{
"id":"<group id>",
"name":"<group name>",
"type":"<type>"
},
"authoritative":"acl"|"mode",
"mode":"<POSIX mode>",
"action":"<action_value>",
"acl":[
{
"trustee":{
"id":"<trustee id>",
"name":"<trustee name>",
"type":"<trustee type>"
},
"accesstype":"allow"|"deny",
"accessrights":"<accessrights_list>",

244 File system access API

 "op":"<operation_value>"
}
]
}

Request query parameters

Parameter Description Default Type Required

Name
acl The acl argument must be placed at the first N/A String Yes
position of the argument list in the URI.

Request body parameters

Parameter Description Default Type Required

Name
owner Specifies the JSON object for the owner N/A JSON object No
persona. You should only specify the owner or
group persona if you want to change the owner
or group of the target.
group Specifies the JSON object for the group persona N/A JSON object No
of the owner. You should only specify the owner
or group persona if you want to change the
owner or group of the target.
authoritative The authoritative field is mandatory and can take N/A String Yes
the value of either acl or mode.
acl: You can modify the owner, group
personas, or access rights for the file by
setting the authoritative field to acl and by
setting <action_value> to update. When the
authoritative field is set to acl, access rights
are set for the file from the acl structure. Any
value that is specified for the mode parameter is
ignored.
NOTE:
When the authoritative field is set to acl,
the default value for the <action_value> field
is replace. If the <action_value> field is
set to replace, the system replaces the
existing access rights of the file with the
access rights that are specified in the acl
structure. If the acl structure is empty, the
existing access rights are deleted and default
access rights are provided by the system.
The default access rights for files are read
access control list (‘std_read_dac’) and write
access control list (‘std_write_dac’) for the
owner.
mode: You can modify the owner and group
personas by setting the authoritative field to
mode. When the authoritative field is set to
mode, POSIX permissions are set on the file.
The <action_value> field and acl structure are
ignored. If mode is set on a file that already has

File system access API 245

Parameter Description Default Type Required
Name

access rights or if access rights are set on a

file that already has POSIX permissions set, the
result of the operation varies based on the Global
ACL Policy.

mode Specifies the POSIX mode. 0700 for Octal number, No

directories which is specified
as a string
0600 for files

action The <action_value> field is applied when the replace String No

authoritative field is set to acl. You can set
the <action_value> field to either update or
replace. The default value is replace.
When set to update, the existing access control
list of the file is modified with the access control
entries that are specified in the acl structure of
the JSON body.
When set to replace, the entire access control
list is deleted and replaced with the access
control entries that are specified in the acl
structure of the JSON body.
Also, when set to replace, the acl structure is
optional. If the acl structure is left empty, the
entire access control list is deleted and replaced
with the system set default access rights. The
default access rights for files are read access
control list (‘ std_read_dac’) and write access
control list (‘ std_write_dac’) for the owner.

acl Specifies the JSON array of access rights. N/A JSON object Conditional
Mandatory when
the
<action_value>
field is set to
update and
optional when
the
<action_value>
field is set to
replace.

accesstype Can be set to allow or deny. N/A String Yes, unless the
<action_value>
allow: Allows access to the file based on the
field is set to
access rights set for the trustee. replace and
deny: Denies access to the file based on the the acl
access rights set for the trustee. structure is
empty.
accessrights Specifies the access right values that are defined N/A List of string Conditional
for the file. values
Mandatory when
the
<action_value>
field is set to
update and the
<operation_value
>field is set to
either add or

246 File system access API

Parameter Description Default Type Required
Name

replace, and
when the
<inherit_flags_lis
t> field is
unspecified.
Optional when
the
<action_value>
field is set to
update and the
<operation_value
> is set to
delete.

inherit_flags Specifies the inherit flag values for the file. N/A List of string Conditional
values
Either the
<accessrights_lis
t> or
<inherit_flags_lis
t> must be
specified when
the
<action_value>
field is set to
update and the
<operation_value
> field is set to
add or
replace.

op The <operation_value> field is applied when the add, when the String No
<action_value> field is set to update. You <action_value>
can set the <operation_value> field to add, field is set to
replace, or delete. If no <operation_value> update
field is specified, the default value is add.
add: Creates an access control entry (ACE) if
an ACE is not already present for a trustee and
trustee access type. If an entry is already present
for that trustee and trustee access type, this
operation appends the access rights list to the
current ACE for that trustee and trustee access
type.
delete: Removes the access rights list provided
from the existing ACE for a trustee and trustee
access type. If the input access rights list is
empty , the entire ACE that corresponds to the
trustee and trustee access type is deleted.
replace: Replaces the entire ACE for the
trustee and trustee access type with the input
access rights list.

Request headers
This call sends common request headers.

File system access API 247

Response headers
This call returns common response headers.

Response body
No message body is returned upon success.

Example request
This sample sets the ACL of a file named 'file1'.

PUT /namespace/ifs/dir1/dir2/ns/file1?acl HTTP/1.1

Host: my_cluster:8080
Content-Length: <length>
Date: Tue, 22 May 2012 12:00:00 GMT
Authorization: <signature>
Content-Type: application/json

{
"owner":{
"id":"UID:0",
"name":"root",
"type":"user"
},
"group":{
"id":"GID:0",
"name”:"wheel",
"type":"group"
},
"authoritative":"acl",
"action":"update",
"acl": [
{
"trustee":{
"id":"UID:0",
"name":"root",
"type":"user"
},
"accesstype":"allow",
"accessrights":[
"file_read",
"file_write"
],
"op":"add"
},
{
"trustee":{
"id":"GID:1201",
"name":"group12",
"type":"group"
},
"accesstype":"allow",
"accessrights":"std_write_dac"
],
"op":"replace"
}
]
}

Example response

HTTP/1.1 200 OK
Date: Tue, 22 May 2012 12:00:00 GMT
Content-Length: <length>

248 File system access API

 Connection: close
Server: Apache2/2.2.19

Query operations
You can search for files and directories on the namespace that matches certain criteria. Files are searched for through a
namespace traverse and a filtering mechanism.

Query an object
Query objects by system-defined and user-defined attributes in a directory.

Request syntax

POST /namespace/<access_point>/<container_path>?query[&<query_param>] HTTP/1.1

Host <hostname>[:<port>]
Date: <date>
Authorization: <signature>

[JSON BODY]

Request query parameters

The query_param argument is optional and can be one or more of the parameters in the following table, which is separated by
an “&.”

Parameter Description Default Type Required

Name
limit Specifies the maximum number of objects to 1000 String No
send to the client. You can set the value to a
negative number to retrieve all objects.
detail Specifies which object attributes are displayed. No String No
If the detail parameter is excluded, only the
name of the object is returned. If the detail
parameter is set to yes, then system information
such as name, owner, group, mode, and size is
returned.
You can specify multiple attribute names in CSV
format. For example:

detail=size,container,content_typ
e

If you set this value to default, the following

attributes are included: name, size, owner,
last_modified, type, group, and mode.

max-depth Specifies the maximum directory level depth to 0 String No

search for objects. If set to 0, only the specified
directory is searched for objects. If set to -1, the
entire hierarchy below the specified directory is
searched for objects.

Request headers
This call sends common request headers.

File system access API 249

Response headers
This call returns common response headers.

Response body
An array of the objects that match the query filter criteria are returned in the JSON body.

Example request

POST /namespace/ifs/my_folder/?query HTTP/1.1

Host my_cluster:8080
Date: <date>
Authorization: <signature>

{
"result":[
"name",
"size",
"last_modified",
"container_path",
"user.color",
"content_type"
],
"scope":{
"logic":"and",
"conditions":[
{
"operator":">=",
"attr":"last_modified",
"value":"Thu, 15 Dec 2011 06:41:04"
},
{
"operator":"like",
"attr":"name",
"value":"ta.*"
}
]
}
}

Example response

{
"children" :
[
{
"content_type " : "text/plain; charset=UTF-8",
"container_path" : "/ifs/movie",
"last_modified" : "Thu, 05 Jan 2012 04:29:56 GMT",
"name" : "fantasy",
"size" : 56
},
{
"content_type " : "text/plain; charset=UTF-8",
"container_path" : "/ifs/folder",
"last_modified" : "Thu, 15 Dec 2011 06:41:04 GMT",
"name" : "tar",
"size" : 3359,
"user.color" : "green"
}
]
}

250 File system access API

JSON query format
You can apply the following JSON query format to refine your search.
The query is defined in the following format, in Backus-Naur Form (BNF) style.

query = <scope_query> |
{
"result":<attribute_list>,
"scope":<scope_query>
}scope_query = predicate |{
"logic":"<logic_operator>",
"conditions":[
<condition>
]
}

The attribute_list is an array of attribute names, which include system attributes and user-defined attributes. For example:

["name", "last_modified", "user.color"]

In the results, the user-defined attribute is prefixed with "user."

The only logical operators that are supported are "and", "or", and "not", where "not" is an unary operator and only one condition
is valid. The "not" operator negates the condition that is evaluated in the conditions parameter. You must specify two or more
conditions for the "and" and "or" operators in the conditions parameter.

logic_operator = and|or|not

The conditions parameter includes an array of conditions. Each condition is defined as follows:

condition = scope_query|predicate

The predicate value is defined as follows:

predicate =
{
"operator":"<comparison_operator>",
"attr":"attr_name",
"value":"attr_value" | string_array
}

The <comparison_operator> value can be any of the following operators: =, !=, <, <=, >, >=, like, or in.
The arithmetic comparison operators are self-explanatory. The "like" operator matches the specified attribute with a pattern of
regular expressions. For example, the following JSON query returns all objects with the attribute "Model" prefixed with "T75":

{
"operator":"like",
"attr":"user.Model",
"value":"^T75.*"
}

If the operator is set to "in", the value must be an array of strings, with at least one element in the array. When only one element
is in the array, the "in" operator behaves the same way as the "=" operator. For example, the following query returns objects
with the attribute "color" set to either "blue", "green", or "turquoise":

{
"operator":"in",
"attr":"user.color",
"value":[
"blue",
"green",
"turquoise"
]
}

File system access API 251

The attribute name can be the name of a user-defined attribute or one of the system defined attributes, such as:

"name" : file or directory name

"size" : the object size in bytes
"last_modified" : last modified date
"content_type" : content type
"container" : the container name
"container_path" : the container full path
"owner": the owner of the object

If the attribute is the user-defined attribute, the attribute must be prefixed with "user." to differentiate the attribute from a
system attribute with the same name. For example, if there is a user-defined attribute that is called "name", you should write the
attribute as "user.name."
Multiple query predicates can be combined through logical operators. For example, the following query returns objects that
satisfy one of the following conditions: "Model" is prefixed with T75 or the "color" attribute is either "red," "green," or
"turquoise," or the "manufacture" attribute is ACME.

{
"logic":"or",
"conditions":[
{
"operator":"like",
"attr":"user.Model",
"value":"^T75.*"
},
{
"operator":"in",
"attr":"user.color",
"value":[
"red",
"green",
"turquoise"
]
},
{
"operator":"=",
"attr":"user.manufacture",
"value":"ACME"
}
]
}

Instead of basic predicates, the element of the conditions array can be a subquery, which allows more complex queries. For
example, the following query returns objects in which either the attribute "manufacture" is set to "ACME" or the "model"
attribute is set to "T750," and the "color" attribute is set to "black."

{
"logic":"or",
"conditions":[
{
"operator":"=",
"attr":"user.manufacture",
"value":"ACME"
},
{
"logic":"and",
"conditions":[
{
"operator":"=",
"attr":"user.model",
"value":"T750"
},
{
"operator":"=",
"attr":"user.color",
"value":"black"
}
]
}

252 File system access API

 ]
}

SmartLock settings
Only root users can configure SmartLock Write Once Read Many (WORM) retention dates and commit flag settings for a file in
a SmartLock directory. A SmartLock license must be active on the cluster to configure these settings.

Get the WORM properties of a file

Retrieves the WORM retention date and committed state of the file.

Request syntax

GET /namespace/<access_point>/<WORM_directory>/<file_name>?worm HTTP/1.1

Host: <hostname>[:<port>]
Date: <date>
Authorization: <signature>

Request query parameters

Parameter Description Default Type Required

Name
worm The worm argument must be placed at the first N/A String No
position of the argument list in the URI.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body

{
"worm_committed":<boolean>,
"worm_override_retention_date":<"YYYY-MM-DD hh:mm:ss GMT">|null,
"worm_override_retention_date_val":<seconds from the Epoch>|null,
"worm_retention_date":<"YYYY-MM-DD hh:mm:ss GMT">|null,
"worm_retention_date_val":<seconds from the Epoch>|null
}

Response body parameters

Parameter Name Description

worm_committed Indicates whether the file was committed to the WORM state.
worm_retention_date Provides the retention expiration date in Coordinated Universal Time (such as
UTC/GMT). If a value is not specified, the field has a null value.
worm_retention_date_val Provides the retention expiration date in seconds from UNIX Epoch or UTC.

File system access API 253

Parameter Name Description
worm_override_retention_date Provides the override retention date that is set on the SmartLock directory
where the file resides. If the date is not set or is earlier than or equal to the
existing file retention date, this field has a null value. Otherwise, the date is
expressed in UTC/GMT, and is the retention expiration date for the file if the
worm_committed parameter is also set to true.

worm_override_retention_date_val Provides the override retention date that is set on the SmartLock directory
where the file resides. If the date is not set or if the date is set to earlier than
or equal to the file retention date, this field has a null value. Otherwise, the
date is expressed in seconds from UNIX Epoch and UTC, and is the retention
expiration date set for the file if the worm_committed parameter is set to
true. This parameter is the same as worm_override_retention_date, but
is expressed in seconds from the Epoch or UTC.

Example request

GET /namespace/ifs/dir1/file?worm HTTP/1.1

Host: my_cluster:8080
Date: Tue, 22 May 2012 12:00:00 GMT
Authorization: <signature>

Example response

HTTP/1.1 200 OK
Date: Tue, 22 May 2012 12:00:00 GMT
Content-Length: <length>
Connection: close
Server: Apache2/2.2.19

{
"worm_committed":true,
"worm_retention_date":"2013-01-22 15:11:36 GMT",
"worm_override_retention_date":null,
"worm_retention_date_val":1358885496,
"worm_override_retention_date_val":null
}

Set the retention period and commit a file in a SmartLock directory

Sets the retention period and commits a file in a SmartLock directory.

Request syntax

PUT /namespace/<access_point>/<WORM_directory>/<file_name>?worm HTTP/1.1

Host: <hostname>[:<port>]
Date: <date>
Authorization: <signature>

{
"worm_retention_date":<"YYYY-MM-DD hh:mm:ss GMT">,
"commit_to_worm":<Boolean>
}

NOTE:

If a file is not explicitly committed and an autocommit time period is configured for the SmartLock directory where the file
resides, the file is automatically committed when the autocommit period elapses.

254 File system access API

 If the file is committed without setting a retention expiration date, the default retention period that is specified for the
SmartLock directory where the file resides is applied. The retention date on the file can also be limited by the maximum
retention period set on the SmartLock directory.

For details about SmartLock WORM behavior, see the OneFS Administration Guide.

Request query parameters

Parameter Description Default Type Required

Name
worm The worm argument must be placed at the first N/A String No
position of the argument list in the URI.

Request body parameters

Parameter Description Default Type Required

Name
worm_retention_ Specifies the retention expiration date string in N/A Time, in the No
date Coordinated Universal Time (UTC/GMT). string format of:
"YYYY-MM-DD
hh:m:ss GMT"
commit_to_wor Specifies whether to commit the file to a WORM False Boolean No
m state after the retention date is set. If the
file was committed before, the file remains
committed regardless of the value in this field.

Request headers
This call sends common request headers.

Response headers
This call returns common response headers.

Response body
No message body is returned upon success.

Example request
Set the retention date for a file in a SmartLock directory.

PUT /namespace/ifs/dir1/file?worm HTTP/1.1

Host: my_cluster:8080
Date: Tue, 22 May 2012 12:00:00 GMT
Authorization: <signature>

{
"worm_retention_date":"2013-04-11 12:00:00 GMT",
"commit_to_worm":true
}

File system access API 255

Example response

HTTP/1.1 200 OK
Date: Tue, 22 May 2012 12:00:00 GMT
Content-Length: 0
Connection: close
Server: Apache2/2.2.19

Code samples for file system access

Code samples illustrate the basic syntax of OneFS API requests for file system access.
You can download a .zip file that contains code samples for C++ and Python programming languages and for curl commands
from the OneFS SDK - Info Hub. The sample code provides brief examples on how to access, modify, and delete files and
directories on your cluster through OneFS API requests.

256 File system access API