isilon onefs 7.2.0 onefs api reference - dell emc us · onefs api overview the onefs application...

IsilonOneFSVersion 7.2.0

OneFS API Reference

Copyright © 2001-2015 EMC Corporation. All rights reserved. Published in USA.

Published July, 2015

EMC believes the information in this publication is accurate as of its publication date. The information is subject to changewithout notice.

The information in this publication is provided as is. EMC Corporation makes no representations or warranties of any kind withrespect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for aparticular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicablesoftware license.

EMC², EMC, and the EMC logo are registered trademarks or trademarks of EMC Corporation in the United States and othercountries. All other trademarks used herein are the property of their respective owners.

For the most up-to-date regulatory document for your product line, go to EMC Online Support (https://support.emc.com).

EMC CorporationHopkinton, Massachusetts 01748-91031-508-435-1000 In North America 1-866-464-7381www.EMC.com

2 OneFS 7.2.0 OneFS API Reference

Introduction to this guide 5

About this guide..............................................................................................6Isilon scale-out NAS overview..........................................................................6Where to go for support...................................................................................6

Introduction to the OneFS API 7

OneFS API overview.........................................................................................8OneFS API architecture.......................................................................8OneFS API terminology .................................................................... 10

OneFS API access.......................................................................................... 10HTTP methods..................................................................................11Privileges......................................................................................... 12

OneFS API authentication..............................................................................12HTTP Basic Authentication................................................................12Session cookies...............................................................................13

System configuration API 17

System configuration API overview................................................................ 18Collection patterns...........................................................................18OneFS API self-documentation......................................................... 21

System configuration API resources...............................................................21Authentication and access control................................................... 21Auditing........................................................................................... 67NFS.................................................................................................. 70SMB.................................................................................................90System jobs................................................................................... 100SyncIQ backup and recovery.......................................................... 112Deduplication................................................................................ 179HDFS..............................................................................................183File pools....................................................................................... 189SmartLock......................................................................................196Storage pools.................................................................................200SmartQuotas..................................................................................210Snapshots..................................................................................... 221Access zones................................................................................. 235Cluster statistics............................................................................ 239Statistics resources........................................................................239

Code samples for file system configuration................................................. 243

File system access API 245

File system access API overview.................................................................. 246Common response headers............................................................246Common request headers.............................................................. 246Common namespace attributes......................................................247

Troubleshooting..........................................................................................248File system access operations..................................................................... 250

Access points.................................................................................250

Chapter 1

Chapter 2

Chapter 3

Chapter 4

CONTENTS

OneFS 7.2.0 OneFS API Reference 3

Directory operations.......................................................................256File operations............................................................................... 271Access control lists........................................................................ 284Query operations........................................................................... 309SmartLock settings........................................................................ 313

Code samples for file system access........................................................... 316

CONTENTS


CHAPTER 1

Introduction to this guide

This section contains the following topics:

l About this guide......................................................................................................6l Isilon scale-out NAS overview..................................................................................6l Where to go for support...........................................................................................6

Introduction to this guide 5

About this guideThis guide describes how the Isilon OneFS application programming interface (API)provides access to cluster configuration and access to cluster data. This guide alsoprovides a list of all available API resource URLs, HTTP methods, and parameter andobject descriptions.

We value your feedback. Please let us know how we can improve this document.

l Take the survey at https://www.research.net/s/isi-docfeedback.

l Send your comments or suggestions to [email protected].

Isilon scale-out NAS overviewThe EMC Isilon scale-out NAS storage platform combines modular hardware with unifiedsoftware to harness unstructured data. Powered by the OneFS operating system, an EMCIsilon cluster delivers a scalable pool of storage with a global namespace.

The platform's unified software provides centralized web-based and command-lineadministration to manage the following features:

l A cluster that runs a distributed file system

l Scale-out nodes that add capacity and performance

l Storage options that manage files, block data, and tiering

l Flexible data protection and high availability

l Software modules that control costs and optimize resources

Where to go for supportYou can contact EMC Isilon Technical Support for any questions about EMC Isilonproducts.

Online Support Live Chat

Create a Service Request

Telephone Support United States: 1-800-SVC-4EMC (800-782-4362)

Canada: 800-543-4782

Worldwide: +1-508-497-7901

For local phone numbers in your country, see EMC CustomerSupport Centers.

Help with onlinesupport

For questions specific to EMC Online Support registration oraccess, email [email protected].

Introduction to this guide


https://www.research.net/s/isi-docfeedback

mailto:[email protected]

https://support.emc.com/servicecenter/liveChat/

https://support.emc.com/servicecenter/createSR/

http://www.emc.com/collateral/contact-us/h4165-csc-phonelist-ho.pdf

http://www.emc.com/collateral/contact-us/h4165-csc-phonelist-ho.pdf

mailto:[email protected]

CHAPTER 2

Introduction to the OneFS API


l OneFS API overview.................................................................................................8l OneFS API access.................................................................................................. 10l OneFS API authentication...................................................................................... 12

Introduction to the OneFS API 7

OneFS API overviewThe OneFS application programming interface (API) is divided into two functional areas:one area enables cluster configuration, management, and monitoring functionality, andthe other area enables operations on files and directories on the cluster. You can sendrequests to the OneFS API through a Representational State Transfer (REST) interface,which is accessed through resource URIs and standard HTTP methods.

When an API request is sent over HTTPS to a cluster IP address or hostname, that requestis authenticated and then authorized through role-based access control. After the requestis approved, access is provided to either file system configuration libraries or directoriesand files on the cluster.

OneFS API architectureWhen you send an HTTP request through the OneFS API, your request is sent to an Apacheserver. The Apache server verifies your username and password, through either HTTPBasic Authentication for single requests or through an established session to a singlenode for multiple requests over a period of time.

After the user account is authenticated, the privileges associated with the user accountthat generated the request are verified by role-based access control (RBAC). If the useraccount has the required privileges, the request enables access to files and directorieson the cluster or to system configuration libraries, based on the resource URL provided inthe request.

The following simplified diagram shows the basic flow of the two types of OneFS APIrequests:



/platform(system configuration API)

/namespace(file system access API)

HTTP Basic or Session Authentication

RBAC(Authorization)

Directories and files on the cluster System configuration libraries

Apache Server

API request throughHTTPS/URI


OneFS API architecture 9

OneFS API terminologyThe following terms are relevant to understanding the OneFS API.

Term Definition

Access point An access point is the root path of the URL to the file system. You can define anaccess point for any directory in the file system.

Collection A collection is a group of objects of a similar type. For example, all of the user-defined quotas in the system make up a collection of quotas.

Data object Data objects contain content data, such as a file on the system.

Namespace The namespace is the file system structure on the cluster.

Object Objects refer to either containers or data objects.

An object is system configuration data that is created by users, or an object is aglobal setting on the system.

For example, a user-created object can be a file system snapshot, quota, share,export, block storage target, logical unit, sync policy, and so on.

An object can also be a global setting on the system, such as default sharesettings, HTTP server settings, snapshot subsystem settings, and so on.

Resource A resource is an object, collection, or function that you can access by a URI.

OneFS API accessBy applying standard HTTP methods to resource URIs, you can modify file system settingsor access content on any node in a cluster through the OneFS API. When making multiplechanges through the OneFS API, it is recommended that you send all requests to a singlenode to avoid configuration collisions.

OneFS API resource URIs are composed of the components defined in the following table.

Component Definition

my_cluster The IP address or host name for the cluster

obj_port The number of the port, default is 8080

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

resource_path The file path to the directory you want to access

resource_version The version of the OneFS API

collection_pattern The namespace, collection name, and object ID of the resource you want toconfigure

In both types of API requests, you can append query parameters to the end of resourceURIs to modify and refine your request. For example, you can limit a GET request to return



only a set number of entries. In the following example, only 1000 SMB shares arereturned:

GET https://192.168.1.100:8080/platform/1/protocols/smb/shares&limit="1000"

File system configuration API requestsFor file system configuration API requests, the resource URI is composed of the followingcomponents:

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

For example, you can send a GET request to the following URI to retrieve all SMB shareson a cluster, where protocols is the namespace, smb is the collection name, and sharesis the object ID:

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

File system access API requestsFor file system access APIs requests, the resource URI is composed of the followingcomponents:

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 storedin the folder at /ifs/users/folder1:

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

Additionally, in file system access API requests, you can indicate a special operation inyour request by appending a pre-defined keyword to the end of the resource URI. Thesekeywords must be placed first in the argument list and must not contain any value. Ifthese keywords are placed in any other position in the argument list, the keywords areignored. Pre-defined keywords include: acl, metadata, worm, and query.

For example:

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

HTTP methodsYou can apply certain HTTP methods to resource URIs through the OneFS API to modifyfile system settings or to access file system content.

The following conditions apply to the HTTP methods available for the OneFS API:

l The GET method returns an object or collection.

l The HEAD method returns response header meta data without the response bodycontent.

l The DELETE method removes an object from a collection.

l The POST method creates objects.

l The POST method returns a document indicating the success of the request and thelocation of the created resource.

l The PUT method enables partial modification of a resource.


HTTP methods 11

l The PUT and POST methods do not return full resource entity bodies upon success;these methods return success or failure codes.

PrivilegesPrivileges permit users to complete tasks on an EMC Isilon cluster.

Privileges are associated with an area of cluster administration such as Job Engine, SMB,or statistics.

Privileges have one of two forms:

ActionAllows a user to perform a specific action on a cluster. For example, theISI_PRIV_LOGIN_SSH privilege allows a user to log in to a cluster through an SSHclient.

Read/WriteAllows a user to view or modify a configuration subsystem such as statistics,snapshots, or quotas. For example, the ISI_PRIV_SNAPSHOT privilege allows anadministrator to create and delete snapshots and snapshot schedules. A read/writeprivilege can grant either read-only or read/write access. Read-only access allows auser to view configuration settings; read/write access allows a user to view andmodify configuration settings.

Privileges are granted to the user on login to a cluster through the OneFS API, the webadministration interface, SSH, or a console session. A token is generated for the user,which includes a list of all privileges granted to the user. Each URI, web-administrationinterface page, and command requires a specific privilege to view or modify theinformation available through any of these interfaces.

Note

Privileges are not granted to users that do not connect to the System Zone during login orto users that connect through the deprecated Telnet service, even if they are members ofa role.

OneFS API authenticationYou can authenticate to OneFS API resource URIs by establishing a session with a cookieor through HTTP Basic Authentication. You can only authenticate to resources for whichyou 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 thanauthentication with a session cookie. If you want to initiate multiple requests over aperiod of time, it is recommended that you create a session cookie.

HTTP Basic AuthenticationWith HTTP Basic Authentication (RFC 2617), you can create a standard Authorizationheader with a valid username and password and send your request to the server. If yourusername and password are authenticated by the server, 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.1Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==



Session cookiesYou can 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 anauthentication token that can then be sent with subsequent requests to provideimmediate authentication.

Session resource overviewYou can set a session cookie for extended authentication to a single node.

Query parametersThere are no parameters for this resource.

Object properties

Property Type Description Property of

username String Specifies the username requestingaccess to the cluster.

N/A

password String Specifies the password for theusername requesting access to thecluster.

N/A

services Array Specifies a list of services to obtainaccess to.

N/A

timeout_absolute Integer Retrieves the number of secondsbefore the session expires in a GETrequest.

N/A

timeout_inactive Integer Retrieves the number of seconds ofinactivity before the session expiresin a GET request.

N/A

Create a session

You can authenticate to a OneFS API resource URI by creating a session cookie and asession. When you create a session, you extend your authentication to a node formultiple requests over a period of time.

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

Procedure

1. Send a POST request to /session/1/session by specifying the JSON content-type inthe request header and by specifying your username, password, and the service youwant to access in the request body. Specify the services parameter as platformfor system configuration or namespace for file system access.

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


Session cookies 13

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 CreatedContent-Length:104Content-Type:application/jsonDate:Fri, 22 Feb 2013 19:08:36 GMTSet-Cookie:isisessid=12345678-abcd-1234-abcd-1234567890ab; path=/;HttpOnly; SecureResponse Body:{"services":["platform","namespace"],"timeout_absolute":14400,"timeout_inactive":900,"username":"user123"}

This value will authenticate the session when you send a request with a sessioncookie.

Results

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

Send a request for access with a session cookie

Authenticate to a session with a session cookie.

Before you begin

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

You do not need to specify a WWW-AUTHENTICATE header.

Procedure

1. Send a GET request to any API resource by typing the isisessid value in the Cookierequest header.

If the server validates your username and password, access is granted.

Results

Authentication is granted for future requests on this node.

Request example

GET 10.10.111.120:8080/platform/1/quotasCookie: isisessid=12345678-abcd-1234-abcd-1234567890ab

Response example

200 OKContent-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 servervalidates your session cookie, the system returns a JSON document with informationabout the session. If the server does not validate the session ID contained in the cookie,the server returns with an error message.

Request syntax

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

Response bodyIf 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 UnauthorizedContent-Type: application/json{ "errors":[ { "message":"authorization required" } ]}

Log out of a session

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

Request syntax

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

Response bodyIf authorization is successful:

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


Session cookies 15

If authorization fails:

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



CHAPTER 3

System configuration API


l System configuration API overview........................................................................ 18l System configuration API resources.......................................................................21l Code samples for file system configuration......................................................... 243

System configuration API 17

System configuration API overviewYou can access cluster configuration, status information, and file system content throughobjects and collections of objects. These objects and collections are exposed as resourceURIs, which are represented as JavaScript Object Notation (JSON) formatted documents.

Collection patternsYou can configure the file system on your cluster through the OneFS API by applying HTTPmethods 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 objectYou can read a system object that has a unique identifier through the GET method; theidentifier is the name or system-generated id for that object.

Request pattern:

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

Response:

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

Modify a system objectYou can modify an object by sending one or more of the object properties through thePUT method. Only the specified properties are modified on the resource, which leaves allother properties in their current state.

Request pattern:

PUT https://<cluster-ip-or-host-name>:<port>/<resource-version>/<namespace>/<object-id> Content-Type: application/json{ "<property>": <value> ...}

Response:

{Standard JSON success or error response}



Read an entire collectionYou can read all of the objects in a collection through the GET method.

Request pattern:

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

Response:

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

Read an object from a collectionYou can read an object in a collection through the GET method.

Request pattern:

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

Response:

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

Create an object in a collectionYou can create a user object in a collection through the POST method. The systemresponds with the final URI where the new object is located.

Request pattern:

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

Response:

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

Content-Type: application/json {Standard JSON success or error response}


Collection patterns 19

Modify an object in a collectionYou can modify an object in a collection through the PUT method.

Request pattern:

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

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

Response:


Delete an object from a collectionYou can delete a user object from a collection through the DELETE method.

Request pattern:

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

Response:


Filter a collectionYou can apply a filter to a collection to retrieve user objects that match some commoncriteria.

Request pattern:

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

Response:

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



OneFS API self-documentationYou can access detailed self-documentation about file system access API resources,including URI descriptions, query arguments, allowable HTTP methods, and the requestand response JSON representation structures.

You can access the OneFS API self-documentation through any /platform resource URI byappending the describe query parameter.

For example, for self-documentation on the quotas resource, type the following URL:

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

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

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

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

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

You can retrieve the JSON-formatted documents that are included in the self-documentation through any resource URI by appending the query parameters describeand json. This content is returned as mime-type application/json.

For example, to obtain the JSON-formatted document for the quotas resource, type thefollowing URL:

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

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

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

Authentication and access control overviewOneFS supports several methods for ensuring that your cluster remains secure, includingUNIX- and Windows-style permissions for data-level access control, access zones for dataisolation, and role-based administration control access to system configuration settings.

OneFS is designed for a mixed environment that allows you to configure both AccessControl Lists (ACLs) and standard UNIX permissions on the cluster file system.

Note

In most situations, the default settings are sufficient. You can configure additional accesszones, custom roles, and permissions policies as necessary for your particularenvironment.


OneFS API self-documentation 21

Authentication classesAuthentication classes define values for the object properties in authenticationresources.

<persona-id>The <persona-id> class must be set in the following format: "["user", "group", "SID", "UID","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 must becombined with a name. The type of thepersona can be set to user, group, or

wellknown.

name String Specifies the persona name, which must becombined with a type.

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

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


dn String Specifies the distinguished name for theuser.

dns_domain String Specifies the DNS domain.

domain String Specifies the domain 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 theuser account will expire.

gecos String Specifies the GECOS value, which is usuallythe 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 orgroup. In a POST request, this value is the IDthat refers to the item in the collection itemresource path.

locked Boolean Specifies if the account is locked.

max_password_age Integer Specifies the maximum age in secondsallowed for the password before thepassword expires.

member_of Array of[<persona>]

Specifies groups that this user or group aremembers 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 allowedto expire.

password_last_set Integer Specifies the last time the password was set.

primary_group_sid <persona> Specifies the security ID of the primary groupfor the user.

prompt_password_change Boolean Prompts a password change for the user atthe next log in.

provider String Specifies the authentication provider theobject 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.

user_can_change_password Boolean Specifies whether the user can change theirown password.

<group-id>The <group-id> class must be set in the following format: "["group", "SID", "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 forthe group or object.

groups

dns_domain String Specifies the DNS domain for theobject.

groups


Authentication and access control overview 23


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 theuser or group. In a POST request, thisvalue refers to the item in thecollection item resource path.

groups

member_of Array of[<persona>]

Specifies properties for groups thatthis user or group are members of.

groups

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 securityidentifier.

groups

type String Indicates the object type. groups

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


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 asread-only.

Authentication resourcesYou can retrieve, create, modify, or delete authentication providers, users, groups, andother configurations and settings through authentication resource URIs.

Auth access token resource

Retrieve information about the access token for the authenticated user.

Operation Method and URI

Get the security token for the currentlyauthenticated user

GET /platform/1/auth/id

View the detailed JSON schema for this resource GET /platform/1/auth/id?describe




Object properties


ntoken Object Specifies properties for the accesstoken.

N/A

additional_id Array[<persona>]

Specifies additional UIDs, GIDs, andSIDs.

ntoken

gid <persona> Specifies properties for the currentlyauthenticated primary group ID forthe user.

ntoken

group_sid <persona> Specifies properties for the currentlyauthenticated primary group securityID for the user.

ntoken

ifs_restricted Boolean Indicates if this user has restrictedaccess to the /ifs file system.

ntoken

local_address String Specifies the IP address of the nodethat is servicing the request.

ntoken

on_disk_group_id <persona> Specifies the group ID that is storedon disk for the authenticated user.

ntoken

on_disk_user_id <persona> Specifies the user ID that is stored ondisk for the authenticated user.

ntoken

privilege Array[<privilege>]

Specifies the privileges granted to theauthenticated user.

ntoken

protocol Integer Specifies the protocol that isresponsible for the creation of thetoken. The integer values for eachprotocol are as follows: NFS (1), SMB(2), NLM (3), FTP (4), HTTP (5), ISCSI(7), SMB2 (8), NFS4 (9), OneFS API(10), HDFS (15), console (16), andSSH (17).

ntoken

remote_address String Specifies the IP address of the clientrequesting the information.

ntoken

uid <persona> Specifies the currently authenticateduser ID.

ntoken

user_sid <persona> Specifies the currently authenticatedsecurity ID for the user.

ntoken

zid Integer Specifies the ID of the access zonethat is serving the request.

ntoken

zone_id String Specifies the name of the accesszone that is serving the request.

ntoken



Auth user access resource

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


Get the access rights that a user has for aspecified file

GET /platform/1/auth/access/<user-id>

View the detailed JSON schema for this resource GET /platform/1/auth/access/<user-id>?describe

Query parameters

path=<string>

Specify the path to the file, which must begin with /ifs.

zone=<string>

Specify an access zone for the user.

numeric=<boolean>

Return only the numeric user and group identities.

Object properties


access Object Specifies properties for access rights. N/A

file Object Specifies access permissions for thefile.

access

group String Specifies the group name or ID for thefile.

file

mode String Specifies the mode bits on the file. file

owner String Specifies the name or ID of the fileowner.

file

relevant_mode String Specifies the mode bits that arerelated to the user.

file

id String Specifies the user ID. access

permissions Object Specifies the permissions for the useron a file.

access

dacl String Returns a status message if the NullACL is set.

permissions

delete_child String Returns a status message if theparent directory has thedelete_child property set for the

user. If the delete_child property

is set for a user, that user is able todelete the file.

permissions

expected String Specifies the Access Control Entry(ACE) for the user.

permissions




ownership String Returns a status message if the userowns the file.

permissions

sticky String Returns a status message if thesticky bit property is set on the

parent directory. If the sticky bit

property is set, only the owner of thefile has permission to delete the file.

permissions

relevant_aces Object Specifies the relevant ACE for theuser.

access

user <persona> Specifies the user persona. access

uid Integer Specifies an ID for the user. user

Auth user password resource

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


Change the password for a user PUT /platform/1/auth/users/<user-id>/change_password

View the detailed JSON schema forthis resource

GET /platform/1/auth/users/<user-id>/change_password?describe


Object properties


new_password String Specifies the new user password. N/A

old_password String Specifies the old user password. N/A

Auth users resource

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


Get all users GET /platform/1/auth/users

Get one user GET /platform/1/auth/users/<user-id>

Modify a user PUT /platform/1/auth/users/<user-id>

Create a user POST /platform/1/auth/users

Flush the users cache DELETE /platform/1/auth/users

Delete a user DELETE /platform/1/auth/users/<user-id>




View the detailed JSON schema for thisresource

GET /platform/1/auth/users?describe

Query parameters

cached=<Boolean>

If true, only return cached objects.

domain=<string>

Filter users by domain.

filter=<string>

Search for user names based on partial strings.

provider=<string>

Filter users by authentication provider.

query_member_of=<Boolean>

Enumerate all groups for which a user is a member and also retrieve informationabout group membership.

resolve_names=<Boolean>

Return both the user ID and name, default is set to true.

zone=<string>

Filter users by access zone.

limit=<integer>

Return no more than this many results at one time (see resume).

resume=<string>

Continue returning results from the previous request (cannot be combined with otherparameters).

Object properties


resume String Specifies the value for the resumeargument for continuation requests.

N/A

users Array[<user>]or <user>

Retrieves an array of user objects or asingle user object.

N/A

Auth users member of resource

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


Get the groups that a user is a member of GET /platform/1/auth/users/<user-id>/member_of

Add a group membership for a user POST /platform/1/auth/users/<user-id>/member_of




Remove a group membership from a user DELETE /platform/1/auth/users/<user-id>/member_of/<group-id>


GET /platform/1/auth/users/<user-id>/member_of?describe

Query parameters

provider=<string>

Filter groups by provider.


Retrieve additional information about the user ID and name, default is set to true.

zone=<string>

Filter groups by access zone.

resume=<string>


Object properties



N/A

member_of Array[<persona>]

Specifies properties for groups thatthis user or group are members of.

N/A

Auth groups resource

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


Get all groups GET /platform/1/auth/groups

Flush the groups cache DELETE /platform/1/auth/groups

Get a group GET /platform/1/auth/groups/<group-id>

Create a group POST /platform/1/auth/groups

Modify a group PUT /platform/1/auth/groups/<group-id>

Delete a group DELETE /platform/1/auth/groups/<group-id>


GET /platform/1/auth/groups?describe

Query parameters

cached=<Boolean>



If true, only return cached objects.

domain=<string>

Filter groups by domain.

filter=<string>

Search for user names based on partial strings.

provider=<string>

Filter groups by provider.

query_member_of=<Boolean>

Enumerate all groups for which a user is a member and also retrieve informationabout group membership.


Return both the group ID and name, default is set to true.

zone=<string>


limit=<Integer>


resume=<string>


Object properties



N/A

groups Array[<groups>] or <group>

Retrieves an array of group objects ora single group object.

N/A

Auth groups members resource

Add, remove, or retrieve information about the members of a group who areauthenticated through a local or remote authentication provider.


Get the members of a group GET /platform/1/auth/groups/<group-id>/members

Add a member to a group POST /platform/1/auth/groups/<group-id>/members

Remove a member from a group DELETE /platform/1/auth/groups/<group-id>/members/<persona-id>


GET /platform/1/auth/groups/<group-id>/members?describe

Query parameters

provider=<string>



Filter groups by the provider.



zone=<string>


limit=<integer>


resume=<string>


Object properties


resume String Specifies the value for the resume argument forcontinuation requests.

N/A

id String Specifies the system ID given to the new member ofthe group. In a POST request, this value is the ID thatrefers to the item in the collection item resource path.

N/A

members Array[<persona>] Specifies persona properties for users or groups withthis role.

N/A

Auth netgroups resource

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


Get the members of a netgroup GET /platform/1/auth/netgroups/<netgroup>


GET /platform/1/auth/netgroups/<netgroup>?describe

Query parameters

provider=<string>

Filter netgroups by authentication provider.

recursive=<Boolean>

Perform recursive searches, when set to true.

ignore_errors=<Boolean>

Ignore netgroup errors, when set to true.

zone=<string>

Filter netgroups by access zone.



Object properties


netgroups Array Specifies properties for netgroups. N/A

domainname String Specifies the domain for which thenetgroup is valid.

netgroups

hostname String Specifies the host that is valid for thisnetgroup.

netgroups

netgroup String Specifies the name of the netgroup. netgroups

username String Specifies the user who is valid for thisnetgroup.

netgroups

Auth settings mapping resource

Modify or retrieve information about identity mapping settings.


Retrieve default identity mapping settings GET /platform/1/auth/settings/mapping/defaults

Modify the default identity mappingsettings

PUT /platform/1/auth/settings/mapping/defaults


GET /platform/1/auth/settings/mapping/defaults?describe

Query parameters

scope=[user|default|effective]

If this parameter is specified as effective, or if the parameter is unspecified, allfields are shown. If the parameter is specified as user, only fields with non-defaultvalues are shown. If the parameter is specified as default, the default values arereturned.

Object properties


mapping_settings Array Specifies the global settings forauthentication

N/A

gid_range_enabled Boolean Determines whether a fixed rangeallocates GIDs.

mapping_settings

gid_range_max Integer Specifies the ending number forallocated GIDs

mapping_settings

gid_range_min Integer Specifies the starting number forallocated GIDs

mapping_settings

gid_range_next Integer Specifies the next GID that will beallocated.

mapping_settings

uid_range_enabled Boolean Determines whether a fixed rangeallocates UIDs.

mapping_settings




uid_range_max Integer Specifies the ending number forallocated UIDs

mapping_settings

uid_range_min Integer Specifies the starting number forallocated UIDs

mapping_settings

uid_range_next Integer Specifies the next UID that will beallocated.

mapping_settings

Auth mapping identities resource

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


Retrieve identity mapping (UID, GID, SID, andon-disk) for the specified source persona

GET /platform/1/auth/mapping/identities/<identity>

Flush the identity mappings cache DELETE /platform/1/auth/mapping/identities?remove=true

Flush the identity mapping DELETE /platform/1/auth/mapping/identities/<identity>?remove=true

Manually set or modify the mapping betweentwo personae

POST /platform/1/auth/mapping/identities


GET /platform/1/auth/mapping/identities?describe


GET /platform/1/auth/mapping/identities/<identity>?describe

Query parameters

nocreate=<boolean>

Disables the automatic create of identity mappings when set to true. Default is setto false.

filter=[auto | external]

Only deletes automatically generated identity mappings when set to auto. Onlydeletes identity mappings from external authentication providers when set toexternal. This parameter will only work when the remove parameter is set totrue.

target=<boolean>

Enable the delete of a specified identity mapping.

remove=<boolean>

Removes all of the identity mappings when set to true. Default is set to false,which only flushes the identity mappings to the identity mappings cache.

replace=<boolean>

Replace the existing mappings with a manually created identity mapping, when set totrue. The default is set to false, which leaves the existing identity mapping andreturns an error.



type=[uid | gid | sid]

Specify the type of target to create an identity mapping to.

2way=<boolean>

Create or delete the bi-directional identity mapping between the source and targetwhen set to true. The default is set to false, and will only create or delete theidentity mapping.

zone=<string>

Specifies the name of the access zone that is serving the request.

Object properties


identities Array Specifies the properties for theidentity mapping entries.

N/A

id Array[<id>] Specifies the properties for theidentity mapping entry ID.

identities

source Array[<persona>]

Specifies the properties for thesource identity.

identities

targets Array Specifies the properties for the user. identities

on_disk Boolean Determines whether the identity ispreferred on-disk.

targets

target Array[<persona>]

Specifies the properties for the targetpersona.

targets

type String Specifies the origin of the identitymapping

targets

Auth mapping users rules resource

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


Get the user mapping rules GET /platform/1/auth/mapping/users/rules

Replace all user mapping rules PUT /platform/1/auth/mapping/users/rules


GET /platform/1/auth/mapping/users/rules?describe

Query parameters

zone=<string>

The access zone that the rules apply to.



Object properties


rules Array Specifies the properties for usermapping.

N/A

default_unix_user Object Specifies the properties for a defaultUNIX user. Requires a token to haveboth a primary UID and GID.

rules

domain Integer Specifies the domain name. default_unix_user

user String Specifies the user name for thedomain.

default_unix_user

options Object Specifies the properties for options. rules

break Boolean Stops processing further rules andimmediately creates a final token if arule is applied successfully.

options

default_user Object Substitutes this user if the seconduser in a rule is not found.

options

domain Integer Specifies the domain name. default_user


default_user

group Boolean Specifies that the primary GID andprimary group SID are copied to theexisting credential.

options

groups Object Specifies that all additional identifiesare copied to the existing credential.

options

domain Integer Specifies the domain name. groups


groups

user Object Maps users in the format of domain\user(n), where n is the user number.For example, user1.

options

domain String Specifies the domain name. user


user

user1 Object Specifies the properties for theprimary user.

rules

domain Integer Specifies the domain name. user1


user1

user2 Object Specifies the properties for thesecondary user.

rules

domain Integer Specifies the domain name. user2





user2

Auth mapping users lookup resource

Retrieve the access token for any authenticated user.


Lookup a user through the user mapper GET /platform/1/auth/mapping/users/lookup


GET /platform/1/auth/mapping/users/lookup?describe

Query parameters

user=<string>

The user to lookup.

zone=<string>

The name of the access zone that is serving the request.

uid=<integer>

The system generated user ID.

gid=<integer>

The supplemental group IDs of the user to lookup, which is combined with the uidparameter, and can be specified multiple times.

primary_gid=<integer>

The primary group ID of the user to lookup, which is combined with the uidparameter.

Object properties


mapping Array Specifies the properties for theaccess token.

N/A

groups Array[<groups>]

Specifies the properties for the group. mapping

privileges Array[<privilege>]

Specifies the properties for the userprivileges.

mapping

user <user> Specifies the properties for the user. mapping



Auth providers summary resource

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


Get a summary of authentication providers GET /platform/1/auth/providers/summary


GET /platform/1/auth/providers/summary?describe


Object properties


provider_instances Array Specifies properties for theauthentication providers that areconfigured on the cluster.

N/A

id String Specifies the ID of the provider. provider_instances

active_server String Specifies the server that the providerserves authentication requests with.Null if no server is set or is notapplicable for that provider.

provider_instances

forest String Specifies the Active Directory forest.Null if not applicable.

provider_instances

site String Specifies the Active Directory sitename. Null if not applicable.

provider_instances

name String Specifies the name of the provider. provider_instances

status String Indicates the online and active stateof the provider.

provider_instances

type String Specifies the type of provider. provider_instances

Auth Kerberos providers resource

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


Retrieve all Kerberos providers GET /platform/1/auth/providers/krb5

Retrieve a Kerberos provider GET /platform/1/auth/providers/krb5/<ID>

Create a new Kerberos provider POST /platform/1/auth/providers/krb5




Modify a Kerberos provider PUT /platform/1/auth/providers/krb5/<ID>

Delete a Kerberos provider DELETE /platform/1/auth/providers/krb5/<ID>


GET /platform/1/auth/providers/krb5?describe


GET /platform/1/auth/providers/krb5/<ID>?describe

Query parameters


The name of the access zone that is serving the request. If this parameter is specifiedas effective, or if the parameter is unspecified, all fields are shown. If theparameter is specified as user, only fields with non-default values are shown. If theparameter is specified as default, the default values are returned.

Object properties


krb5 Array Specifies a Kerberos authenticationprovider.

N/A

id Array Specifies the Kerberos provider ID. krb5

keytab_entries Array Specifies the key information for theKerberos Service Principal Name(SPN).

krb5

encryption Array Specifies the encryption types. keytab_entries

kvno Integer Specifies the version number for theSPN key.

keytab_entries

spn String Specifies the Service Principal Name. keytab_entries

timestamp Integer Specifies the time the key wascreated.

keytab_entries

keytab_file String Specifies the path to the keytab file toimport.

krb5

manual_keying Boolean When set to true, keys are managedmanually. When set to false, keys aremanaged through kadmin.

krb5

name String Specifies the Kerberos providername.

krb5

password String Specifies the Kerberos providerpassword.

krb5

realm String Specifies the name of the realm. krb5




recommended_spns String Specifies recommended ServicePrincipal Names.

krb5

status String Specifies the status for the provider. krb5

system Boolean Indicates that the provider instancewas created by OneFS and cannot beremoved.

krb5

user String Specifies a user for kadmin tasks. krb5

Auth settings krb5 defaults resource

Retrieve or modify default Kerberos authentication settings.


Retrieve default Kerberos authenticationsettings

GET /platform/1/auth/settings/krb5/default

Modify the default Kerberos authenticationsettings

PUT /platform/1/auth/settings/krb5/default


GET /platform/1/auth/settings/krb5/default?describe

Query parametersThere are no query parameters for this resource.

Object properties


krb5_settings Array Specifies the default settings forKerberos authentication.

N/A

always_send_preauth Boolean Determines if a pre-authenticationrequest is sent to the controller.

krb5_settings

default_realm String Specifies the realm for unqualifiednames.

krb5_settings

dns_lookup_kdc Boolean Determines if DNS is used to searchfor KDCs.

krb5_settings

dns_lookup_realm Boolean Determines if DNS is used to searchfor realm names.

krb5_settings

Auth settings krb5 realms resource

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


Retrieve Kerberos authentication settingsfor realm

GET /platform/1/auth/settings/krb5/realms




Retrieve Kerberos authentication settingsfor a specific realm

GET /platform/1/auth/settings/krb5/realms/<realm name or ID>

Create a new Kerberos authenticationrealm

POST /platform/1/auth/settings/krb5/realms

Modify Kerberos authentication realmsettings

PUT /platform/1/auth/settings/krb5/realms/<realm name or ID>

Delete a Kerberos authentication realm DELETE /platform/1/auth/settings/krb5/realms/<realm name or ID>


GET /platform/1/auth/settings/krb5/realms?describe


GET /platform/1/auth/settings/krb5/realms/<realm name or ID>?describe


Object properties


realm Array Specifies the Kerberos settings forrealm access.

N/A

admin_server String Specifies a hostname for theadministrative server.

realm

default_domain String Specifies the default domain that ismapped to the realm.

realm

is_default_realm Boolean Determines whether the realm is setas the default.

realm

is_joined Boolean Determines whether the realm isjoined.

realm

kdc Array Specifies a list of KDC hostnames. realm

realm String Specifies the name of the realm realm

Auth settings krb5 domains resource

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


Retrieve Kerberos authentication settingsfor domains

GET /platform/1/auth/settings/krb5/domains

Retrieve Kerberos authentication settingsfor a specific domains

GET /platform/1/auth/settings/krb5/domains/<domain name or ID>

Create a new Kerberos authenticationdomain

POST /platform/1/auth/settings/krb5/domains




Modify Kerberos authentication domainsettings

PUT /platform/1/auth/settings/krb5/domains/<domain name or ID>

Delete a Kerberos authentication domain DELETE /platform/1/auth/settings/krb5/domains/<domain name or ID>


GET /platform/1/auth/settings/krb5/domains?describe


GET /platform/1/auth/settings/krb5/domains/<domain name or ID>?describe


Object properties


domains Array Specifies the Kerberos settings fordomain-realm mappings.

N/A

domain String Specifies the name of the domain. domains

realm String Specifies the name of the realm. domains

ID String In a POST request, this value is the IDthat refers to the item in thecollection item resource path.

N/A

Auth ADS providers domains resource

Retrieve information about the trusted domains of configured ADS providers.


Get all trusted domains of ADS providers GET /platform/1/auth/providers/ads/<id>/domains

Get the trusted domains of a single ADSprovider

GET /platform/1/auth/providers/ads/<id>/domains/<ads-domain>


GET /platform/1/auth/providers/ads/<id>/domains?describe


Object properties


domains Array Specifies the properties for trusteddomains of configured ADS providers.

N/A

dc_address String Specifies the address for the domaincontroller.

domains




dc_name String Specifies the name for the domaincontroller.

domains

dc_site String Specifies the site for the domaincontroller.

domains

domain String Specifies the name of the domain. domains

guid String Specifies the globally unique ID forthe domain.

domains

id String Specifies a unique identifier for everydomain returned.

domains

netbios_name String Specifies the NetBIOS name for thedomain.

domains

sid String Specifies the security ID for thedomain.

domains

site String Specifies the site that the cluster is infor that domain.

domains

status String Indicates whether the domain isonline or offline.

domains

trust_type String Specifies the type of trust with thedomain. Options consist ofprimary, unknown, external,

and forest.

domains

Auth ADS providers resource

Join, modify, or leave an ADS provider domain.


Get all ADS providers GET /platform/1/auth/providers/ads

Get one ADS provider GET /platform/1/auth/providers/ads/<provider-id>

Join an ADS domain POST /platform/1/auth/providers/ads

Modify an ADS provider PUT /platform/1/auth/providers/ads/<provider-id>

Leave a domain DELETE /platform/1/auth/providers/ads/<provider-id>


GET /platform/1/auth/providers/ads/<domain>?describe

Query parameters


If this parameter is specified as effective, or if the parameter is unspecified, allfields are shown. If the parameter is specified as user, only fields with non-default



values are shown. If the parameter is specified as default, the default values arereturned.

Object properties


ads Array Specifies the properties for ADSprovider domains.

N/A

allocate_gids Boolean Allocates a GID for an unmapped ADSgroup. Active Directory groupswithout GIDs can be proactivelyassigned a GID by the ID mapper. Ifthis option is disabled, GIDs are notproactively assigned, but when auser's primary group does not includea GID, the system may allocate one.

ads

allocate_uids Boolean Enables allocation of a UID for anunmapped ADS user. Active Directoryusers without UIDs can be proactivelyassigned a UID by the ID mapper. Ifthis option is disabled, UIDs are notproactively assigned, but when auser's identity does not include a UID,the system may allocate one.

ads

assume_default_domain Boolean Enables lookup of unqualified usernames in the primary domain.

ads

authentication Boolean Enables use of the provider forauthentication and identity.

ads

check_online_interval Integer Specifies the time between provideronline checks.

ads

controller_time Integer Specifies the current time of thedomain controller.

ads

create_home_directory Boolean Creates a home directory on the firstlogin.

ads

domain_offline_alerts Boolean Sends an alert when the domain goesoffline.

ads

forest String Specifies the ADS forest. ads

home_directory_template String Specifies the home directory templatepath.

ads

hostname String Specifies the fully qualified hostnamethat is stored in the machine account.

ads

id String Specifies the ID of the providerinstance.

ads

ignore_all_trusts Boolean Ignores all trusted domains. ads

ignored_trusted_domains Boolean Includes trusted domains whenignore_all_trusts is set to

false.

ads




include_trusted_domains Boolean Includes trusted domains whenignore_all_trusts is set to true.

ads

ldap_sign_and_seal Boolean Uses encryption and signing on LDAPrequests.

ads

login_shell String Specifies the login shell path. ads

lookup_domains String Limits user and group lookup to thespecified domains.

ads

lookup_groups Boolean Looks up ADS groups in otherproviders before allocating a GID.

ads

lookup_normalize_groups Boolean Normalizes ADS group names tolowercase before lookup.

ads

lookup_normalize_users Boolean Normalizes ADS user names tolowercase before lookup.

ads

lookup_users Boolean Looks up ADS users in other providersbefore allocating a UID.

ads

machine_account String Specifies the SAM account name ofthe machine account. In POSTrequests, specify this property asaccount.

ads

machine_password_lifespan

Integer Specifies the maximum age of apassword.

ads

name String Specifies the ADS provider name. ads

netbios_domain String Specifies the NetBIOS domain nameassociated with the machine account.

ads

nss_enumeration Boolean Enables the ADS provider to respondto getpwent and getgrentrequests.

ads

primary_domain String Specifies the primary domain name. ads

sfu_support String Specifies whether to support RFC2307 attributes on ADS domaincontrollers. Valid options are none or

rfc2307.

ads

site String Specifies the ADS site. ads

status String Specifies the status of the provider. ads

store_sfu_mappings Boolean Stores the SFU mappingspermanently in the ID mapper.

ads


ads



Auth ADS providers controllers resource

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


Get all domain controllers for a trustedADS domain

GET /platform/1/auth/providers/ads/<domain-id>/controllers


GET /platform/1/auth/providers/ads/<domain-id>/controllers?describe


Object properties


controllers Array Specifies properties the domaincontrollers.

N/A

dc_address String Specifies the IP address for thedomain controller.

controllers

dc_name String Specifies the name for the domaincontroller.

controllers

id String Specifies the name for the domaincontroller.

controllers

Auth ADS providers search resource

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


Get objects that are searchable in domains GET /platform/1/auth/providers/ads/<object>/search


GET /platform/1/auth/providers/ads/<object>/search?describe

Query parameters

domain=<string>

The domain to search in.

user=<string>

The username to authentication to the domain, if untrusted.

password=<string>

The password for the domain, if untrusted.

filter=<string>

The filter to use when performing a search. The filter must be in the form of an LDAPquery.



description=<string>

An optional description to search for.

search_users=<Boolean>

If true, search for users.

search_groups=<Boolean>

If true, search for groups.

limit=<integer>


resume=<string>


Object properties



N/A

objects Array Specifies the properties for searchobjects.

N/A

description String Specifies the description returnedfrom the Active Directory server.

objects

display_name String Specifies the display name returnedfrom the Active Directory server.

objects

id <persona> Specifies the properties for apersona, which consists of either atype and a name or an id.

objects

Auth file providers resource

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


Get all file providers GET /platform/1/auth/providers/file

Get one file provider GET /platform/1/auth/providers/file/<provider-id>

Create a file provider POST /platform/1/auth/providers/file

Modify a file provider PUT /platform/1/auth/providers/file/<provider-id>

Delete a file provider DELETE /platform/1/auth/providers/file/<provider-id>


GET /platform/1/auth/providers/file?describe

Query parameters




If specified as effective, or unspecified, all fields are shown. If specified as user,only fields with non-default values are shown. If specified as default, the defaultvalues are returned.

Object properties


file Object Specifies the properties for anauthentication file provider.

N/A

authentication Boolean Enables authentication andidentification through the provider.

file

cache_entry_expiry Integer Specifies the amount of time to cachea user or group.

file


file

enabled Boolean Enables the file provider. file

enumerate_groups Boolean Enables providers to enumerategroups.

file

enumerate_users Boolean Enables providers to enumerateusers.

file

findable_groups String Specifies a list of groups that can beresolved.

file

findable_users String Specifies a list of users that can beresolved.

file

group_domain String Specifies the domain used to qualifygroups for this provider.

file

group_file String Specifies the location of the file thatcontains group information.

file

home_diretory_template String Specifies the home directory templatepath.

file

id String Specifies the file provider ID. file

listable_groups String Specifies groups that can be viewedin the provider.

file

listable_users String Specifies users that can be viewed inthe provider.

file

login_shell String Specifies the login shell path. file

modifiable_groups String Specifies groups that can be modifiedin the provider.

file

modifiable_users String Specifies users that can be modifiedin the provider.

file

name String Specifies the name of the fileprovider.

file

netgroup_file String Specifies the path to a netgroupsreplacement file.

file




normalize_groups Boolean Normalizes the group name tolowercase before lookup.

file

normalize_users Boolean Normalizes the user name tolowercase before lookup.

file

ntlm_support String Specifies the supported NTLM versionfor users with NTLM-compatiblecredentials.

file

password_file String Specifies the location of the file thatcontains user information.

file

provider_domain String Specifies the domain for the provider. file

restrict_findable Boolean Checks the provider for filtered listsof findable and unfindable users andgroups.

file

restrict_listable Boolean Checks the provider for filtered listsof listable and unlistable users andgroups.

file

restrict_modifiable Boolean Checks the provider for filtered listsof modifiable and unmodifiable usersand groups.

file

status String Specifies the status of the provider. file


file

unfindable_groups String Specifies a group that cannot beresolved by the provider.

file

unfindable_users String Specifies a user that cannot beresolved by the provider.

file

unlistable_groups String Specifies a group that cannot belisted by the provider.

file

unlistable_users String Specifies a user who cannot be listedby the provider.

file

unmodifiable_groups String Specifies a group that cannot bemodified by the provider.

file

unmodifiable_users String Specifies a user who cannot bemodified by the provider.

file

user_domain String Specifies the domain that qualifiesusers for this provider.

file



Auth LDAP providers resource

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


Get all LDAP providers GET /platform/1/auth/providers/ldap

Get one LDAP provider GET /platform/1/auth/providers/ldap/<provider-id>

Create an LDAP provider POST /platform/1/auth/providers/ldap

Modify an LDAP provider PUT /platform/1/auth/providers/ldap/<provider-id>

Delete an LDAP provider DELETE /platform/1/auth/providers/ldap/<provider-id>


GET /platform/1/auth/providers/ldap/<provider-id>?describe

Query parameters


If specified as effective, or if the parameter is unspecified, all fields are shown. Ifspecified as user, only fields with non-default values are shown. If specified asdefault, the default values are returned.

Object properties


ldap Object Specifies the properties for an LDAPprovider.

N/A

authentication Boolean Enables authentication through theprovider.

ldap

balance_servers Boolean Connects the provider to a randomserver.

ldap

base_dn String Specifies the root of the tree in whichto search for identities.

ldap

bind_dn String Specifies a distinguished name thatis used when binding to LDAP servers.

ldap

bind_mechanism String Specifies the bind mechanism to usewhen connecting to an LDAP server.The only supported value is simple.

ldap

bind_password String Specifies a password for adistinguished name that is usedwhen binding to LDAP servers.

ldap

bind_timeout Integer Specifies a timeout in seconds whenbinding LDAP servers.

ldap




cache_entry_expiry Integer Specifies the amount of time to cachea user or group.

ldap

certificate_authority_file String Specifies the path to the rootcertificates file.

ldap

check_online_interval Integer Specifies the time between theprovider online checks.

ldap

cn_attribute String Specifies the canonical name. ldap


ldap

crypt_password_attribute String Specifies a hashed password value. ldap

email_attribute String Specifies the LDAP email attribute. ldap

enabled Boolean Enables the LDAP provider. ldap

enumerate_groups Boolean Enables the LDAP provider toenumerate groups.

ldap

enumerate_users Boolean Enables the LDAP provider toenumerate users.

ldap


ldap


ldap

gecos_attribute String Specifies the LDAP GECOS attribute. ldap

gid_attribute String Specifies the LDAP GID attribute. ldap

group_base_dn String Specifies a distinguished name forthe entry where LDAP searches forgroups begins.

ldap


ldap

group_filter String Specifies the LDAP filter for groupobjects.

ldap

group_members_attribute String Specifies the LDAP Group Membersattribute.

ldap

group_search_scope String Specifies the depth from the base DNto perform LDAP searches.

ldap


ldap

homedir_attribute String Specifies the LDAP Homedir attribute. ldap

id String Specifies the ID of the LDAP provider. ldap

ignore_tls_errors String Continues over secure connections,even if the identity check fails.

ldap


ldap





ldap

login_shell String Specifies the login shell path. ldap

name String Specifies the name of the LDAPprovider.

ldap

name_attribute String Specifies the LDAP UID attribute,which is used as the login name.

ldap

netgroup_base_dn String Specifies a distinguished name forthe entry where LDAP searches fornetgroups begins.

ldap

netgroup_filter String Specifies the LDAP filter for netgroupobjects.

ldap

netgroup_members_attribute

String Specifies the LDAP NetgroupMembers attribute.

ldap

netgroup_search_scope String Defines the depth from the base DNto perform LDAP searches.

ldap

netgroup_triple_attribute String Specifies the LDAP Netgroup Tripleattribute.

ldap

normalize_groups Boolean Normalizes group names tolowercase before lookup.

ldap

normalize_users Boolean Normalizes user names to lowercasebefore lookup.

ldap

nt_password_attribute String Specifies the LDAP NT Passwordattribute.

ldap

ntlm_support String Specifies the supported NTLM versionfor users with NTLM-compatiblecredentials.

ldap

provider_domain String Specifies the provider domain. ldap

require_secure_connection Boolean Specifies whether to continue over anon-TLS connection.

ldap

restrict_findable Boolean Checks the provider for filtered listsof findable and unfindable users andgroups.

ldap

restrict_listable Boolean Checks the provider for filtered listsof listable and unlistable users andgroups.

ldap

search_scope String Specifies the default depth from thebase DN to perform LDAP searches.

ldap

search_timeout Integer Specifies the search timeout period. ldap

server_uris String Specifies the server URIs. ldap

shell_attribute String Specifies the LDAP shell attribute. ldap

status String Specifies the status of the provider. ldap





ldap

uid_attribute String Specifies the LDAP UID Numberattribute.

ldap

unfindable_groups String Specifies groups that cannot beresolved by the provider.

ldap

unfindable_users String Specifies users who cannot beresolved by the provider.

ldap

unique_group_members_attribute

String Specifies the LDAP Unique GroupMembers attribute.

ldap


ldap

unlistable_users String Specifies a user who cannot be listedby the provider.

ldap

user_base_dn String Specifies a distinguished name forthe entry where LDAP searches forusers begins.

ldap

user_domain String Specifies the domain used to qualifyusers for this provider.

ldap

user_filter String Specifies the LDAP filter for userobjects.

ldap

user_search_scope String Specifies the depth from the base DNto perform LDAP searches.

ldap

Auth local providers resource

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


Get all local providers GET /platform/1/auth/providers/local

Get one local provider GET /platform/1/auth/providers/local/<file-id>

Create a local provider POST /platform/1/auth/providers/local

Modify a local provider PUT /platform/1/auth/providers/local/<file-id>

Delete a local provider DELETE /platform/1/auth/providers/local/<file-id>


GET /platform/1/auth/providers/local?describe



Query parameters


If this parameter is specified as effective, or if the parameter is unspecified, allfields are shown. If this parameter is specified as user, only fields with non-defaultvalues are shown. If this parameter is specified as default, the original values arereturned.

Object properties


local Object Specifies the properties for a localauthentication provider.

N/A

authentication Boolean Enables authentication through theprovider.

local


local


local

id String Specifies the ID for the local provider. local

lockout_duration Integer Specifies the length of time inseconds that an account isinaccessible after multiple failedlogin attempts.

local

lockout_threshold Integer Specifies the number of failed loginattempts necessary for an account tobe locked out.

local

lockout_window Integer Specifies the time in seconds inwhich lockout_threshold failed

attempts must be made for anaccount to be locked out.

local

login_shell String Specifies the login shell path. local

machine_name String Specifies the Active Directory accountname for the machine.

local

max_password_age Integer Specifies the maximum password agein seconds.

local

min_password_age Integer Specifies the minimum password agein seconds.

local

min_password_length Integer Specifies the minimum passwordlength.

local

name String Specifies the name of the localprovider.

local

password_prompt_time Integer Specifies time in seconds remainingbefore being prompted to change thepassword.

local

status String Specifies the status of the provider. local





local

Auth NIS providers resource

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


Get all NIS providers GET /platform/1/auth/providers/nis

Get one NIS provider GET /platform/1/auth/providers/nis/<nis-name>

Create an NIS provider POST /platform/1/auth/providers/nis

Modify an NIS provider PUT /platform/1/auth/providers/nis/<nis-name>

Delete an NIS provider DELETE /platform/1/auth/providers/nis/<nis-name>


GET /platform/1/auth/providers/nis?describe

Query parameters



Object properties


nis Object Specifies the properties for an NISauthentication provider.

N/A

authentication Boolean Enables authentication andidentification through the provider.

nis

balance_servers Boolean Enables the provider to connect to arandom server.

nis

cache_entry_expiry Integer Specifies the amount of time inseconds to cache a user or group.

nis

check_online_interval Integer Specifies the amount of time inseconds between provider onlinechecks.

nis

create_home_directory Integer Creates a home directory on firstlogin.

nis




enabled Boolean Enables the NIS provider. nis

enumerate_groups Boolean Enables the provider to enumerategroups.

nis

enumerate_users Boolean Enables the provider to enumerateusers.

nis


nis


nis


nis


nis

hostname_lookup Boolean Enables host name lookups. nis

id String Specifies the NIS provider ID. nis


nis


nis

login_shell String Specifies the login shell path. nis

name String Specifies the NIS provider name. nis

nis_domain String Specifies the NIS domain name. nis

normalize_groups Boolean Normalizes the group name tolowercase before lookup.

nis

normalize_users Boolean Normalizes the user name tolowercase before lookup.

nis

ntlm_support String Specifies the NTLM version for userswith NTLM-compatible credentials.

nis

provider_domain String Specifies the provider domain. nis

request_timeout Integer Specifies the request timeout intervalin seconds.

nis

restrict_findable Boolean Checks the provider for filtered listsof findable and unfindable users.

nis

restrict_listable Boolean Checks the provider for filtered listsof listable and unlistable users.

nis

retry_time Integer Specifies the timeout period inseconds after which a request isretried.

nis

servers String Specifies a list of NIS servers for thisprovider.

nis




check_online_interval Integer Specifies the amount of time inseconds between provider onlinechecks.

nis

status String Specifies the status of the provider. nis

system String Indicates that the provider instancewas created by OneFS and cannot beremoved.

nis

unfindable_groups String Specifies a group that cannot beresolved by the provider.

nis

unfindable_users String Specifies a user that cannot beresolved by the provider.

nis


nis

unlistable_users String Specifies a user that cannot beresolved by the provider.

nis

user_domain String Specifies the domain used to qualifyusers for this provider.

nis

ypmatch_using_tcp Boolean Uses TCP for YP match operations. nis

Auth roles members resource

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


Get the members of a role GET /platform/1/auth/roles/<role>/members

Add a member to a role POST /platform/1/auth/roles/<role-id>/members

Remove a member from a role DELETE /platform/1/auth/roles/<role-id>/members/<persona-id>


GET /platform/1/auth/roles/<role-id>/members?describe

Query parameters



Object properties



N/A

roles Array Specifies properties for members assigned to a role. N/A




members Array[<persona>] Specifies users or groups that are assigned this role. roles

Auth roles resource

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


Get all roles GET /platform/1/auth/roles

Get one role GET /platform/1/auth/roles/<role-id>

Create a role POST /platform/1/auth/roles

Modify a role PUT /platform/1/auth/roles/<role-id>

Delete a role DELETE /platform/1/auth/roles/<role-id>


GET /platform/1/auth/roles?describe

Query parameters



resume=<string>


Object properties



N/A

roles Array Specifies properties for user roles. N/A

id String Specifies an ID for the role. roles

name String Specifies a name for the role. roles

members Array[<persona>] Specifies users or groups that are assigned this role. roles

privileges Array[<privilege>] Specifies privileges that are granted by the role. roles

Auth roles privileges resource

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


Get the privileges of a role GET /platform/1/auth/roles/<id>/privileges




Add a privilege to a role POST /platform/1/auth/roles/<id>/privileges

Remove a privilege from a role DELETE /platform/1/auth/roles/<id>/privileges/<privilege-id>


GET /platform/1/auth/roles/<id>/privileges?describe

Query parameters

resume=<string>


Object properties



N/A

privileges Array[<privilege>]

Specifies the privileges that aregranted by the role.

N/A

Auth global settings resource

Retrieve or modify the global authentication settings on the cluster.


Get global settings GET /platform/1/auth/settings/global

Modify global settings PUT /platform/1/auth/settings/global


GET /platform/1/auth/settings/global?describe

Query parameters

scope=[effective|user|default]


Object properties


global_settings Object Specifies properties for globalauthentication settings.

N/A

alloc_retries Integer Specifies the number of times to retryan ID allocation before failing.

global_settings




cache_cred_lifetime Integer Specifies the length of time inseconds to cache credentialresponses from the ID mapper.

global_settings

cache_id_lifetime Integer Specifies the length of time inseconds to cache ID responses fromthe ID mapper.

global_settings

gid_range_enabled Boolean Enables the use of a fixed range forallocating a GID.

global_settings

gid_range_max Integer Specifies the ending number forallocating a GID.

global_settings

gid_range_min Integer Specifies the starting number forallocating a GID.

global_settings

gid_range_next Integer Specifies the next GID to beallocated.

global_settings

group_uid Integer Specifies the UID to use when thekernel must retrieve a UID for a group.

global_settings

load_providers array[<string>]

Specifies which providers are loadedby the authentication daemon(lsassd). Valid strings are"ActiveDirectory", "Local", "File","NIS", or "Ldap".

global_settings

min_mapped_rid Integer Starts RID in the local domain to mapa UID and a GID.

global_settings

null_gid Integer Specifies the alternative GID to usewhen the kernel is unable to retrievea GID for a persona.

global_settings

null_uid Integer Specifies the alternative UID to usewhen the kernel is unable to retrievea UID for a persona.

global_settings

on_disk_identity String Specifies the type of identity that isstored on disk.

global_settings

rpc_block_time Integer Specifies the minimum amount oftime in milliseconds to wait beforeperforming an oprestart.

global_settings

rpc_max_requests Integer Specifies the maximum number ofoutstanding RPC requests.

global_settings

rpc_timeout Integer Specifies the maximum amount oftime in seconds to wait for an idmapresponse.

global_settings

send_ntlmv2 Boolean Specifies whether to send NTLMv2responses.

global_settings

space_replacement String Specifies space replacementcharacter.

global_settings




system_gid_threshold Integer Specifies the minimum GID toattempt to lookup in the idmapdatabase.

global_settings

system_uid_threshold Integer Specifies the minimum UID toattempt to lookup in the idmapdatabase.

global_settings

uid_range_enabled Boolean Enables a fixed range for allocatingUIDs.

global_settings

uid_range_max Integer Specifies the ending number forallocating a UID.

global_settings

uid_range_min Integer Specifies the starting number forallocating a UID.

global_settings

uid_range_next Integer Specifies the next UID to allocate. global_settings

unknown_gid Integer Specifies the GID to use for anunknown or anonymous group.

global_settings

unknown_uid Integer Specifies the UID to use for anunknown or anonymous user.

global_settings

workgroup String Specifies the NetBIOS workgroup ordomain.

global_settings

Auth shells resource

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


Get a list of user shells that are supported on thecluster

GET /platform/1/auth/shells

View the detailed JSON schema for this resource GET /platform/1/auth/shells?describe


Object properties


shells Array[<string>]

Specifies a list of supported shells. N/A



Auth wellknowns resource

Retrieve wellknown personas from the cluster.


Get all wellknown personas GET /platform/1/auth/wellknowns

Get a wellknown persona GET /platform/1/auth/wellknowns/<wellknown>


GET /platform/1/auth/wellknowns?describe


Object properties


wellknowns Array[<persona>]

Specifies values for a persona, whichconsists of either a type and a nameor an ID.

N/A

Authentication API examplesYou can see examples for some authentication API requests.

Change a user password

Change a user password.

Request exampleSpecify both the new and old password.

PUT /platform/1/auth/users/USER:johndoe/change_passwordAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example

204 No ContentContent-type: text/plain

Create a local group

Create a local group.

Request example

POST /platform/1/auth/groupAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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



Response example

201 CreatedContent-type: application/json

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

Modify a local group

Modify a local group.

Request exampleYou must include the force parameter when modifying an authentication group.

PUT /platform/1/auth/groups/GROUP:mygroup?force=trueAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"gid": 2004}

Response example


Add a member to a local group

Add a member to a local group.

Request example

POST /platform/1/auth/groups/GROUP:mygroup/membersAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"id": "USER:user01"}

Response example


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

Create a user

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

Request exampleCreate the user "user123" through the following request:

POST /platform/1/auth/usersAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


{



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

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

POST /platform/1/auth/groups/administrators/membersAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


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

Modify a user

Modify the properties for a user.

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

PUT /platform/1/auth/users/USER:user123Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example

204 No ContentContent-type: application/json

Join a domain

Join an Active Directory server domain.

Request example

POST /platform/1/auth/providers/adsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


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



Modify an ADS provider

Modify an Active Directory authentication provider.

Request example

PUT /platform/1/auth/providers/ads/server1.company.comAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


Create an LDAP provider

Create an LDAP provider.

Request example

POST /platform/1/auth/providers/ldapAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


{"id" : "ldaptest"}

Modify an LDAP provider

Modify an LDAP provider.

Request example

PUT /platform/1/auth/providers/ldap/ldaptestAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example




Modify a local provider

Modify a local provider.

Request example

PUT /platform/1/auth/providers/local/zone1Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


Create an authentication role

Create an authentication role.

Request example

POST /platform/1/auth/rolesAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"dba"}

Response example


{"id" : "dba"}

Modify an authentication role

Modify an authentication role.

Request example

PUT /platform/1/auth/roles/dbaAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"dba2"}

Response example


Modify global authentication settings

Modify global authentication settings.

Request example

PUT /platform/1/auth/settings/globalAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"send_ntlmv2":"true"}



Response example


Create a krb5 realm

Create a krb5 authentication realm.

Request example

POST /platform/1/auth/settings/krb5/realmsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"realm":"test_realm"}

Response example


{"id" : "2024839292}

Create a krb5 domain

Create a krb5 authentication domain.

Request example

POST /platform/1/auth/settings/krb5/domainsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


{"id" : "29274939282"}

Modify krb5 domains

Modify a krb5 authentication domain

Request example

PUT /platform/1/auth/settings/krb5/domains/test_domainAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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



Response example


Modify krb5 settings

Modify default krb5 authentication settings.

Request example

PUT /platform/1/auth/settings/krb5/defaultsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


Auditing overviewYou can audit system configuration changes and SMB and NFS protocol activity on anEMC Isilon cluster. All audit data is stored and protected in the cluster file system andorganized by audit topics.

When you enable system configuration auditing, no additional configuration is required;all configuration events that are handled by the application programming interface (API)through the command-line interface (CLI) are tracked and recorded in the config audittopic directories.

Auditing can detect many potential sources of data loss, including fraudulent activities,inappropriate entitlements, and unauthorized access attempts. Customers in industriessuch as financial services, health care, life sciences, and media and entertainment, aswell as in governmental agencies, must meet stringent regulatory requirementsdeveloped to protect against these sources of data loss.

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 SMBand NFS protocol are recorded in the protocol audit topic directories. The protocolaudit log file is consumable by auditing applications that support the EMC Common EventEnabler (CEE). You can specify which events to log in each access zone. For example, youmight want to audit the default set of protocol events in the System access zone butaudit only successful attempts to delete files in a different access zone.

The audit events are logged on the individual nodes where the SMB or NFS client initiatedthe 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.

Audit resourcesYou can retrieve and modify OneFS audit topics and settings.


Auditing overview 67

Audit settings resource

Applies the standard system object pattern to OneFS audit settings.


Get audit settings GET /platform/1/audit/settings

Modify audit settings PUT /platform/1/audit/settings

View the detailed JSON schema for this resource. GET /platform/1/audit/settings?describe


Object properties


config_auditing_enabled Boolean Enables logging for API configurationchanges when set to true.

settings

protocol_auditing_enabled Boolean Enables logging for the I/O streamwhen set to true.

settings

audited_zones String Specifies the zones that are auditedwhen theprotocol_auditing_enabledproperty is set to true.

settings

cee_server_uris String Specifies a list of Common EventEnabler (CEE) server URIs. Protocolaudit logs are sent to these URIs forexternal processing.

settings

Audit topic resource

Applies the standard collection pattern to OneFS Audit topics.


Get all audit topics GET /platform/1/audit/topics

Get an audit topic GET /platform/1/audit/topics/<name>

Modify an audit topic PUT /platform/1/audit/topics/<name>

View the detailed JSON schema for this resource. GET /platform/1/audit/topics?describe




Object properties


id String Specifies the system-provided ID forthe audit topic.

topics

name String Specifies the name of the audit topic. topics

max_cached_messages String Specifies the number of messagesthat can be sent and received at thesame time. Messages that are sentand received at the same time can belost if a system crash occurs.However, you can prevent messageloss by setting themax_cached_message property to

0, which sets audit logs tosynchronous.

topics

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

Enable protocol auditing

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

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

PUT /platform/1/audit/settingsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

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

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

Enable configuration auditing

You can enable configuration auditing on the system.

Request example

PUT /platform/1/audit/settingsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{


Auditing overview 69

'config_auditing_enabled': True }

Response exampleNo message body is returned for this request.

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

Modify an audit topic

You can modify an audit topic on the system.

Request example

PUT /1/audit/topics/protocolAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ "max_cached_messages": 1000 }


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

NFSOneFS provides an NFS server so you can share files on your cluster with NFS clients thatadhere to the RFC1813 (NFSv3) and RFC3530 (NFSv4) specifications.

In OneFS, the NFS server is fully optimized as a multi-threaded service running in userspace instead of the kernel. This architecture load balances the NFS service across allnodes of the cluster, providing the stability and scalability necessary to manage up tothousands of connections across multiple NFS clients.

NFS mounts execute and refresh quickly, and the server constantly monitors fluctuatingdemands on NFS services and makes adjustments across all nodes to ensure continuous,reliable performance. Using a built-in process scheduler, OneFS helps ensure fairallocation of node resources so that no client can seize more than its fair share of NFSservices.

The NFS server also supports access zones defined in OneFS, so that clients can accessonly the exports appropriate to their zone. For example, if NFS exports are specified forZone 2, only clients assigned to Zone 2 can access these exports.

To simplify client connections, especially for exports with large path names, the NFSserver also supports aliases, which are shortcuts to mount points that clients can specifydirectly.

For secure NFS file sharing, OneFS supports NIS and LDAP authentication providers.

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

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




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 primaryuser group. A persona consists of either atype and name, or an ID.

secondary_group Array of<persona>

Specifies persona properties for thesecondary user group. A persona consists ofeither 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:


id <persona-id> Specifies the serialized form of the persona.

type String Specifies the type of persona, which must becombined with a name. The type of thepersona can be set to user, group, or

wellknown.

name String Specifies the persona name, which must becombined with a type.

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

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

NFS exports summary resource

Retrieves summary information for NFS exports.

Operations Method and URI

Get the NFS exports summary GET /platform/2/protocols/nfs/exports-summary


GET /platform/2/protocols/nfs/exports-summary?describe

Query parameters

zone=<string>

Filter exports by access zone.


NFS 71

Object properties


summary Object Specifies properties for the collectionof exports.

N/A

count Integer Specifies the total number of exportsin the system.

summary

NFS exports resource

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


Get all NFS exports GET /platform/2/protocols/nfs/exports

Get one NFS export GET /platform/2/protocols/nfs/exports/<export-id>

Create an NFS export POST /platform/2/protocols/nfs/exports

Modify an NFS export PUT /platform/2/protocols/nfs/exports

Delete an NFS export DELETE /platform/2/protocols/nfs/exports/<export-id>

View the detailed JSON schema forNFS exports

GET /platform/2/protocols/nfs/exports?describe

View the detailed JSON schema for asingle NFS export

GET /platform/2/protocols/nfs/exports/<export-id>?describe

Query parameters

sort=<string>

Order results by this field. The default value is id.

check=<Boolean>

Check for conflicts when listing exports.

scope=[effective|user]

If this parameter is specified as effective, or if it is unspecified, all export fieldsare shown. If this parameter is specified as user, only fields with non-default valuesare shown.

force=<Boolean>

Override client and username conflicts or errors when creating or modifying anexport.

dir=[ASC|DESC]

Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.

zone=<string>


limit=<integer>




resume=<string>

Continue returning results from previous request (cannot be used with otherparameters).

Object properties


total Integer Specifies the total number of exportsconfigured.

N/A


N/A

all_dirs Boolean True if all directories under thespecified paths are mountable.

exports

block_size Integer Specifies the block size returned bythe NFS statfs procedure.

exports

can_set_time Boolean True if the client can set file timesusing the NFS set attribute request.This parameter does not affect serverbehavior, but is included toaccommodate legacy clientrequirements.

exports

case_insensitive Boolean True if the case is ignored for filenames. This parameter does notaffect server behavior, but is includedto accommodate legacy clientrequirements.

exports

case_preserving Boolean True if the case is preserved for filenames. This parameter does notaffect server behavior, but is includedto accommodate legacy clientrequirements.

exports

chown_restricted Boolean True if the superuser can change fileownership. This parameter does notaffect server behavior, but is includedto accommodate legacy clientrequirements.

exports

clients String Specifies the clients with access tothe export.

exports

commit_asynchronous Boolean True if NFS commit requests executeasynchronously.

exports

conflicting_paths String Reports the paths that conflict withanother export.

exports

description String Specifies the user defined string thatis used to identify the export.

exports

directory_transfer_size Integer Specifies the preferred size fordirectory read operations. This valueis used to advise the client of optimal

exports


NFS 73


settings for the server, but is notenforced.

encoding String Specifies the default character setencoding of the clients connecting tothe export, unless otherwisespecified.

exports

id Integer Specifies the system ID given to theexport. In a POST request, this valueis the ID that refers to the item in thecollection item resource path.

exports

link_max Integer Specifies the reported maximumnumber of links to a file. Thisparameter does not affect serverbehavior, but is included toaccommodate legacy clientrequirements.

exports

map_all <user-mapping>

Specifies the users and groups thatare mapped to non-root clients.

exports

map_failure <user-mapping>

Specifies the user and groups thatclients are mapped to ifauthentication fails.

map_full Boolean True if user mappings query theOneFS user database. When set tofalse, user mappings only query localauthentication.

exports

map_lookup_uid Boolean True if incoming user IDs (UIDs) aremapped to users in the OneFS userdatabase. When set to false,incoming UIDs are applied directly tofile operations.

exports

map_non_root <user-mapping>

Specifies the user and groups thatnonroot clients are mapped to.

exports

map_retry Boolean Determines whether searches for theusers specified in map_all or

map_root are retried if the search

fails.

exports

map_root <user-mapping>

Specifies the users and groups thatare mapped to root clients.

exports

max_file_size Integer Specifies the maximum file size forany file accessed from the export.This parameter does not affect serverbehavior, but is included toaccommodate legacy clientrequirements.

exports

name_max_size Integer Specifies the reported maximumlength of a file name. This parameterdoes not affect server behavior, but is

exports




included to accommodate legacyclient requirements.

no_truncate Boolean True if long file names result in anerror. This parameter does not affectserver behavior, but is included toaccommodate legacy clientrequirements.

exports

paths String Specifies the paths under /ifs that

are exported.

exports

read-only Boolean True if the export is read-only. exports

read_only_clients Array Specifies the clients with read-onlyaccess to the export.

exports

read_transfer_max_size Integer Specifies the maximum buffer sizethat clients should use on NFS readrequests. This value is used to advisethe client of optimal settings for theserver, but is not enforced.

exports

read_transfer_multiple Integer Specifies the preferred multiple sizefor NFS read requests. This value isused to advise the client of optimalsettings for the server, but is notenforced.

exports

read_transfer_size Integer Specifies the preferred size for NFSread requests. This value is used toadvise the client of optimal settingsfor the server, but is not enforced.

exports

read_write_clients Array Specifies the clients with both readand write access to the export, evenwhen the export is set to read-only.

exports

readdirplus Boolean True if readdirplus requests are

enabled. Enabling this property mayimprove network performance and isonly available for NFSv3.

exports

readdirplus_prefetch Integer Sets the number of directory entriesthat are prefetched when areaddirplus request is processed.

(Deprecated)

exports

return_32bit_file_ids Boolean Limits the size of file identifiersreturned by NFSv3+ to 32-bit values.

exports

root_clients Array Specifies the clients with root accessto the export.

exports

security_flavors Array Specifies the authentication typesthat are supported for this export.

exports

setattr_asynchronous Boolean True if set attribute operationsexecute asynchronously.

exports


NFS 75


snapshot String Specifies the snapshot for all mounts. exports

symlinks Boolean True if symlinks are supported. This

value is used to advise the client ofoptimal settings for the server, but isnot enforced.

exports

time_delta Integer Specifies the resolution of all timevalues that are returned to the client.

exports

unresolved_clients Array Reports clients that cannot beresolved.

exports

write_datasync_action String Specifies the action to be taken whenan NFSv3+ datasync write isrequested. Options includedatasync, filesync, and

unstable.

exports

write_datasync_reply String Specifies the stability dispositionreturned when an NFSv3+ datasyncwrite is processed. Options includedatasync, filesync, and

unstable.

exports

write_filesync_action String Specifies the action to be taken whenan NFSv3+ filesync write is requested.Options include datasync,

filesync, and unstable.

exports

write_filesync_reply String Specifies the stability dispositionreturned when an NFSv3+ filesync isprocessed. Options includedatasync, filesync, and

unstable.

exports

write_transfer_max_size Integer Specifies the maximum buffer sizethat clients should use on NFS writerequests. This value is used to advisethe client of optimal settings for theserver, but is not enforced.

exports

write_transfer_multiple Integer Specifies the preferred multiple sizefor NFS write requests. This value isused to advise the client of optimalsettings for the server, but is notenforced.

exports

write_transfer_size Integer Specifies the preferred size for NFSwrite requests. This value is used toadvise the client of optimal settingsfor the server, but is not enforced.

exports

write_unstable_action String Specifies the action taken when anNFSx3+ unstable write is processed.Options include datasync,


exports




write_unstable_reply String Specifies the stability dispositionreturned when an NFSv3+ unstablewrite is requested. Options includedatasync, filesync, and

unstable.

exports

zone String Specifies the zone in which the exportis valid.

exports

NFS aliases resource

Create, modify, delete, or retrieve information about NFS aliases. Aliases are names forphysical paths in the file system.


Get all NFS aliases GET /platform/2/protocols/nfs/aliases

Get an NFS aliases GET /platform/2/protocols/nfs/aliases/<alias id>

Create a new NFS alias POST /platform/2/protocols/nfs/aliases

Modify an NFS alias PUT /platform/2/protocols/nfs/aliases/<alias id>

Delete an NFS alias DELETE /platform/2/protocols/nfs/aliases/<alias id>


GET /platform/2/protocols/nfs/aliases?describe


GET /platform/2/protocols/nfs/aliases/<alias id>?describe

Query parameters

sort=<string>


check=<boolean>

Check for conflicts when listing exports.

dir=[ASC|DESC]


zone=<string>


limit=<integer>


resume=<string>



NFS 77

Object properties


total Integer Specifies the total number of aliasesconfigured.

N/A


N/A

aliases Object Specifies properties for NFS aliases. N/A

health String Specifies whether the alias is usable.Options include: good, illegalfile type, illegal path, nameconflict, not exported, pathnot found, and unknown.

aliases

id Integer Specifies a string which representsthe unique location of the alias.

aliases

name String Specifies a name by which the aliascan be referenced

aliases

path String Specifies the path to which the aliaspoints.

aliases

zone String Specifies the access zone in whichthe alias is valid.

aliases

NFS NLM locks resource

Applies the standard collection pattern to NFS Network Lock Manager (NLM) advisorylocks.


Get a list of NFS advisory locks GET /platform/2/protocols/nfs/nlm/locks


GET /platform/2/protocols/nfs/nlm/locks?describe

Query parameters

sort=<string>

Order results by this field.

dir=[ASC|DESC]


limit=<integer>


resume=<string>




Object properties


total Integer Specifies the total number of locksavailable.

N/A


N/A

id String Specifies the system ID given to thelock. In a POST request, this value isthe ID that refers to the item in thecollection item resource path.

locks

client String Specifies the client host name and IPaddress.

locks

client_id String Specifies the client ID. locks

lock_type String Specifies the type of lock. locks

range Integer Specifies the byte range within thelocked file.

locks

path String Specifies the path under /ifs that is

locked.

locks

created Integer Specifies the UNIX Epoch time thelock was created.

locks

lin String Specifies the LIN in /ifs that is

locked.

locks

NFS NLM lock waiters resource

Applies the standard collection pattern to NFS Network Lock Manager (NLM) lock waiters.


Get a list of NLM lock waiters on NFS GET /platform/2/protocols/nfs/nlm/waiters


GET /platform/2/protocols/nfs/nlm/waiters?describe

Query parameterssort=<string>


dir=[ASC|DESC]


limit=<integer>


resume=<string>



NFS 79

Object properties


total Integer Specifies the total number of lockwaiters available.

N/A


N/A

waiters Array Specifies information for an NLM lockon an NFS export.

N/A

id String Specifies the system ID given to thelock. In a POST request, this value isthe ID that refers to the item in thecollection item resource path.

waiters


waiters

client_id String Specifies the client ID. waiters

lock_type String Specifies the type of lock. waiters

range Integer Specifies the byte range within thelocked file.

waiters

path String Specifies the path under /ifs that

is locked.

waiters

created Integer Specifies the UNIX Epoch time thelock was created.

waiters

lin String Specifies the LIN in /ifs that is

locked.

waiters

NFS NLM sessions resource

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


Get all NFS NLM sessions GET /platform/2/protocols/nfs/nlm/sessions

Delete an NFS NLM session DELETE /platform/2/protocols/nfs/nlm/sessions/<session-id>

View the detailed JSON schema forNFS NLM sessions

GET /platform/2/protocols/nfs/nlm/sessions?describe

View the detailed JSON schema foran NFS NLM session

GET /platform/2/protocols/nfs/nlm/sessions/<session-id>?describe

Query parameters

sort=<string>


dir=[ASC|DESC]




limit=<integer>


resume=<string>


Object properties


total String Specifies the total number ofsessions to display.

N/A


N/A

sessions Array Specifies properties for NLMsessions.

N/A

id String Specifies the system ID assigned tothe session.

sessions


sessions

NFS default export settings resource

Applies the standard system object pattern to default NFS export settings. These settingsare applied to all new exports, unless otherwise specified.


Get default NFS export settings GET /platform/2/protocols/nfs/settings/export

Modify default NFS export settings PUT /platform/2/protocols/nfs/settings/export


GET /platform/2/protocols/nfs/settings/export?describe

Query parameters


When specified as effective, or not specified, all fields are returned. Whenspecified as user, only fields with non-default values are shown. When specified asdefault, the original values are returned.

zone=<string>

Filters exports by access zone.


NFS 81

Object properties


total Integer Specifies the total number of exportsconfigured.

N/A


N/A

all_dirs Boolean True if all directories under thespecified paths are mountable.

exports

block_size Integer Specifies the block size returned bythe NFS statfs procedure.

exports

can_set_time Boolean True if the client can set file timesusing the NFS set attribute request.This parameter does not affect serverbehavior, but is included toaccommodate legacy clientrequirements.

exports

case_insensitive Boolean True if the case is ignored for filenames. This parameter does notaffect server behavior, but is includedto accommodate legacy clientrequirements.

exports

case_preserving Boolean True if the case is preserved for filenames. This parameter does notaffect server behavior, but is includedto accommodate legacy clientrequirements.

exports

chown_restricted Boolean True if the superuser can change fileownership. This parameter does notaffect server behavior, but is includedto accommodate legacy clientrequirements.

exports

commit_asynchronous Boolean True if NFS commit requests executeasynchronously.

exports

directory_transfer_size Integer Specifies the preferred size fordirectory read operations. This valueis used to advise the client of optimalsettings for the server, but is notenforced.

exports

encoding String Specifies the default character setencoding of the clients connecting tothe export, unless otherwisespecified.

exports

link_max Integer Specifies the reported maximumnumber of links to a file. Thisparameter does not affect serverbehavior, but is included toaccommodate legacy clientrequirements.

exports




map_all <user-mapping>

Specifies the users and groups thatare mapped to non-root clients.

exports

map_failure <user-mapping>

Specifies the user and groups thatclients are mapped to ifauthentication fails.

exports

map_full Boolean True if user mappings query theOneFS user database. When set tofalse, user mappings only query localauthentication.

exports

map_lookup_uid Boolean True if incoming user IDs (UIDs) aremapped to users in the OneFS userdatabase. When set to false,incoming UIDs are applied directly tofile operations.

exports

map_non_root <user-mapping>

Specifies the user and groups thatnonroot clients are mapped to.

exports

map_retry Boolean Determines whether searches for theusers specified in map_all or

map_root are retried if the search

fails.

exports

map_root <user-mapping>

Specifies the users and groups thatare mapped to root clients.

exports

max_file_size Integer Specifies the maximum file size forany file accessed from the export.This parameter does not affect serverbehavior, but is included toaccommodate legacy clientrequirements.

exports

name_max_size Integer Specifies the reported maximumlength of a file name. This parameterdoes not affect server behavior, but isincluded to accommodate legacyclient requirements.

exports

no_truncate Boolean True if long file names result in anerror. This parameter does not affectserver behavior, but is included toaccommodate legacy clientrequirements.

exports

read-only Boolean True if the export is read-only. exports

read_transfer_max_size Integer Specifies the maximum buffer sizethat clients should use on NFS readrequests. This value is used to advisethe client of optimal settings for theserver, but is not enforced.

exports

read_transfer_multiple Integer Specifies the preferred multiple sizefor NFS read requests. This value isused to advise the client of optimal

exports


NFS 83


settings for the server, but is notenforced.

read_transfer_size Integer Specifies the preferred size for NFSread requests. This value is used toadvise the client of optimal settingsfor the server, but is not enforced.

exports

readdirplus Boolean True if readdirplus requests are

enabled. Enabling this property mayimprove network performance and isonly available for NFSv3.

exports

readdirplus_prefetch Integer Sets the number of directory entriesthat are prefetched when areaddirplus request is processed.

(Deprecated.)

exports

return_32bit_file_ids Boolean Limits the size of file identifiersreturned by NFSv3+ to 32-bit values.

exports

security_flavors Array Specifies the authentication typesthat are supported for this export.

exports

setattr_asynchronous Boolean True if set attribute operationsexecute asynchronously.

exports

snapshot String Specifies the snapshot for all mounts. exports

symlinks Boolean True if symlinks are supported. This

value is used to advise the client ofoptimal settings for the server, but isnot enforced.

exports

time_delta Integer Specifies the resolution of all timevalues that are returned to the client.

exports

write_datasync_action String Specifies the action to be taken whenan NFSv3+ datasync write isrequested. Options includedatasync, filesync, and

unstable.

exports

write_datasync_reply String Specifies the stability dispositionreturned when an NFSv3+ datasyncwrite is processed. Options includedatasync, filesync, and

unstable.

exports

write_filesync_action String Specifies the action to be taken whenan NFSv3+ filesync write is requested.Options include datasync,


exports

write_filesync_reply String Specifies the stability dispositionreturned when an NFSv3+ filesync isprocessed. Options include

exports




datasync, filesync, and

unstable.

write_transfer_max_size Integer Specifies the maximum buffer sizethat clients should use on NFS writerequests. This value is used to advisethe client of optimal settings for theserver, but is not enforced.

exports

write_transfer_multiple Integer Specifies the preferred multiple sizefor NFS write requests. This value isused to advise the client of optimalsettings for the server, but is notenforced.

exports

write_transfer_size Integer Specifies the preferred size for NFSwrite requests. This value is used toadvise the client of optimal settingsfor the server, but is not enforced.

exports

write_unstable_action String Specifies the action taken when anNFSx3+ unstable write is processed.Options include datasync,


exports

write_unstable_reply String Specifies the stability dispositionreturned when an NFSv3+ unstablewrite is requested. Options includedatasync, filesync, and

unstable.

exports

zone String Specifies the zone in which the exportis valid.

exports

NFS global settings resource

Retrieve or modify global configuration settings for NFS exports.


Get default NFS export settings GET /platform/2/protocols/nfs/settings/global

Modify default NFS exportsettings

PUT /platform/2/protocols/nfs/settings/global

View the detailed JSON schemafor this resource

GET /platform/2/protocols/nfs/settings/global?describe

Query parameters


When specified as effective, or not specified, all fields are returned. Whenspecified as user, only fields with non-default values are shown. When specified asdefault, the original values are returned.


NFS 85

Object properties


settings Object Specifies the global NFSconfiguration

N/A

service Boolean Enables the NFS service. When set tofalse, disables the NFS service.

settings

nfsv3_enabled Boolean Enables NFSv3. When set to false,disables NFSv3.

settings

nfsv4_enabled Boolean Enables NFSv4. When set to false,disables NFSv4.

settings

lock_protection Integer Provides the number of nodes thatcan fail in the cluster without losinglock functionality.

settings

rpc_minthreads Integer Provides the minimum number ofthreads in the nfsd thread pool.

settings

rpc_maxthreads Integer Provides the maximum number ofthreads in the nfsd thread pool.

settings

NFS exports configuration check resource

Retrieves information on the status and validity of current NFS exports. Each export withan error is reported along with the first error encountered during the check.


Check NFS exports for configuration errors GET /platform/2/protocols/nfs/check


GET /platform/2/protocols/nfs/check?describe


Object properties


checks Array Specifies information about the NFSexport.

N/A

id Integer Specifies the ID of the NFS export. checks

messages String Provides a message about the statusand validity of the NFS export.

checks

NFS zone settings resource

Retrieve or modify zone configuration settings for NFS exports.


Get NFS server settings for a zone GET /platform/2/protocols/nfs/settings/zone




Modify NFS server settings for azone

PUT /platform/2/protocols/nfs/settings/zone

View the detailed JSON schemafor this resource

GET /platform/2/protocols/nfs/settings/zone?describe


Object properties


settings Object Specifies the per-zone NFSconfiguration

N/A

nfsv4_allow_numeric_ids Boolean If true, sends owners and groups asUIDs and GIDs when look up fails or ifthe nfsv4_no_name property is set

to 1.

settings

nfsv4_domain String Specifies the domain or realmthrough which users and groups areassociated.

settings

nfsv4_no_domain Boolean If true, sends owners and groupswithout a domain name.

settings

nfsv4_no_domain_uids Boolean If true, sends UIDs and GIDs without adomain name.

settings

nfsv4_no_names Boolean If true, sends owners and groups asUIDs and GIDs.

settings

nfsv4_replace_domain Boolean If true, replaces the owner or groupdomain with an NFS domain name

settings

zone String Specifies the access zones for thesesettings.

settings

NFS reload resource

Reloads cached export information. The netgroup cache is updated against the remoteprovider and hosts are updated against the DNS if the time to live (TTL) has expired.Netgroups are automatically refreshed on an interval specified by the netgroup expirationoption. DNS hosts are intermittently refreshed. Local export information, such as optionsspecified with exports create or exports modify, is updated immediately following theaction.


Reload NFS exports POST /platform/2/protocols/nfs/reload

View the detailed JSON schema for NFSexport reload

GET /platform/2/protocols/nfs/reload?describe


NFS 87


Object propertiesThere are no properties for this resource.

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

Create NFS alias

Create an NFS alias.

Request example

POST /platform/1/protocols/nfs/aliasesAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


{"id":"204"}

Modify NFS alias

Modify an NFS alias.

Request example

PUT /platform/1/protocols/nfs/aliases/204Authorization: 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/1/protocols/nfs/exportsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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



]}

Response example


{"id":24}

Modify NFS export

Modify an NFS export.

Request example

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

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

Response example


Modify default NFS settings

Modify the default NFS settings on the cluster.

Request example

PUT /platform/1/protocols/nfs/settings/exportAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


Modify global NFS settings

Modify the global NFS settings on the cluster.

Request example

PUT /platform/1/protocols/nfs/settings/globalAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{


NFS 89

"nfsv3_enabled":true }

Response example


Modify NFS zone settings

Modify the settings for an NFS access zone.

Request example

PUT /platform/1/protocols/nfs/settings/zoneAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


SMBOneFS includes a configurable SMB service to create and manage SMB shares. SMBshares 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.

The /ifs directory is configured as an SMB share and is enabled by default. OneFSsupports both user and anonymous security modes. If the user security mode is enabled,users who connect to a share from an SMB client must provide a valid user name withproper credentials.

SMB shares act as checkpoints, and users must have access to a share in order to accessobjects in a file system on a share. If a user has access granted to a file system, but not tothe share on which it resides, that user will not be able to access the file systemregardless of privileges. For example, assume a share named ABCDocs contains a filenamed file1.txt in a path such as: /ifs/data/ABCDocs/file1.txt. If a userattempting to access file1.txt does not have share privileges on ABCDocs, that usercannot 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 areconverted to SIDs during retrieval and are converted back to their on-disk representationbefore they are stored on the cluster.

When a file or directory is created, OneFS checks the access control list (ACL) of its parentdirectory. If the ACL contains any inheritable access control entries (ACEs), a new ACL isgenerated from those ACEs. Otherwise, OneFS creates an ACL from the combined file anddirectory create mask and create mode settings.

OneFS supports the following SMB clients:

SMB version Supported operating systems

1.0 Windows 2000 or later



SMB version Supported operating systems

Windows XP or later

Mac OS X 10.5 or later

2.0 Windows Vista or laterWindows Server 2008 or later

Mac OS X 10.9 or later

2.1 Windows 7 or laterWindows Server 2008 R2 or later

3.0 - Multichannel only Windows 8 or laterWindows Server 2012 or later

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

SMB shares summary resource

Retrieves summary information for SMB shares.


Get the SMB shares summary GET /platform/1/protocols/smb/shares-summary


GET /platform/1/protocols/smb/shares-summary?describe


Object properties


count Integer Specifies the total number of sharesin the system.

summary

SMB shares resource

Applies the standard collection pattern to SMB shares.


Get a single SMB share GET /platform/1/protocols/smb/shares/<share-name>

Get a list of SMB shares GET /platform/1/protocols/smb/shares

Create an SMB share POST /platform/1/protocols/smb/shares

Modify an SMB share PUT /platform/1/protocols/smb/shares/<share-name>


SMB 91


Delete an SMB share DELETE /platform/1/protocols/smb/shares/<share-name>

View the detailed JSON schema forSMB shares

GET /platform/1/protocols/smb/shares?describe

View the detailed JSON schema foran SMB share object

GET /platform/1/protocols/smb/shares/<share-name>?describe

Query parameters

sort=<string>


zone=<string>

An optionally named zone to use for user and group resolution.


If this parameter is specified as effective, or if it is unspecified, all export fieldsare shown. If this parameter is specified as user, only fields with non-default valuesare shown. If this parameter is specified as default, the original values arereturned.


When this parameter is set to true, the group and user names are resolved.

dir=[ASC|DESC]


limit=<integer>


resume=<string>


Object properties


total Integer Specifies the total number of sharesdisplayed.

N/A

resume String Specifies the value for the resumeargument to be used for continuationrequests.

N/A

run_as_root Array Lists the personas to be run as root.The permissions for the personas inthis list override permissionsspecified elsewhere.

share

id Integer Specifies the serialized form of thepersona (such as 'UID:0','USER:name', 'GID:0', 'GROUP:wheel','SID:S-1-1').

run_as_root




name String Specifies the persona name, whichmust be combined with type.

run_as_root

type String Specifies the type of persona, whichmust be combined with name.

run_as_root

allow_execute_always Boolean Enables users to execute files thatthey have read rights for.

share

strict_locking Boolean Specifies whether byte range lockscontend with SMB I/O.

share

hide_dot_files Boolean Hides files and directories that beginwith a period.

share

impersonate_guest String Specifies the condition in which useraccess is performed as the guestaccount.

share

strict_flush Boolean Determines whether the data isalways flushed to disk.

share

mangle_byte_start Integer Specifies the starting value for theautomatic byte mangling range (indecimal notation).

share

directory_create_mask Integer Specifies the permission bits (indecimal notation) that can be setwhen a directory is created.

share

directory_create_mode Integer Specifies the permission bits that areset when a directory is created.

share

file_create_mask Integer Specifies the permission bits (indecimal notation) that can be setwhen a file is created.

share

file_create_mode Integer Specifies the permission bits that areset when a file is created.

share

create_permissions String Determines how permissions are setfor new files and directories in theSMB share.

share

mangle_map Array Specifies the character mangle map. share

impersonate_user String Specifies the user account to be usedas a guest account.

share

change_notify String Specifies the level of changenotification alerts on the SMB share.

share

oplocks Boolean Specifies whether to support oplocks. share

allow_delete_readonly Boolean Specifies whether read-only files inthe SMB share can be deleted.

share

ntfs_acl_support Boolean Supports NTFS access control lists(ACLs) on files and directories.

share

access_based_enumeration

Boolean Enumerates only the files and foldersthat the requesting user has access

share


SMB 93


to. This does not apply to the rootdirectory of the share.

access_based_enumeration_root_only

Boolean Specifies whether access-basedenumeration is used in the rootdirectory of the SMB share.

share

host_acl array Lists the hostnames, subnets, or IPaddresses that are allowed or deniedaccess to the share. All types areallowed unless specifically denied. Itis recommended that a deny clausebe the final entry in the list.

share

inheritable_path_acl String Sets an inheritable ACL on the SMBshare path.

share

id String Specifies the system ID given to theSMB share. In a POST request, thisvalue is the ID that refers to the itemin the collection item resource path.

share

description String Describes the SMB share. share

path String Specifies the path of the SMB sharewithin /ifs.

share

name String Specifies the SMB share name. share

csc_policy String Specifies the client-side cachingpolicy for the SMB shares.

share

browsable Boolean Ensures that the SMB share is visiblein net view and in the browse list.

share

permissions Object Specifies an ordered list ofpermission modifications.

share

permission String Specifies the file system rights toallow or deny.

permissions

permission_type String Specifies whether to allow or denythe permission.

permissions

trustee Object Specifies a persona, which consistsof either a type and name or an id.

permissions


trustee


trustee


trustee



SMB open files resource

Retrieves a listing of all files that are currently open through SMB on the queried node.


Get a list of files opened throughSMB

GET /platform/1/protocols/smb/openfiles

Close a file opened through SMB DELETE /platform/1/protocols/smb/openfiles/<file-id>

View the detailed JSON schema forSMB open files

GET /platform/1/protocols/smb/openfiles?describe

View the detailed JSON schema foran SMB open file object

GET /platform/1/protocols/smb/openfiles/<file-id>?describe

Query parameters

sort=<string>


dir=[ASC|DESC]


limit=<integer>


resume=<string>


Object properties


total Integer Specifies the total number of openfiles available.

N/A

resume String Specifies the value for the resumeargument to be used for continuationcalls.

N/A

id Integer Provides the system ID given to thefile. In a POST request, this value isthe ID used to refer to the item in thecollection item resource path.

openfiles

file String Provides the path of the file within /ifs.

openfiles

user String Provides the name of the user withthe file opened.

openfiles

locks Integer Provides the number of locks the userholds on the file.

openfiles


SMB 95


permissions String Provides the permissions on the filefor the user.

openfiles

SMB sessions resource

Retrieves a listing of all SMB sessions that are currently open on the queried node.


Get a list of SMB sessions GET /platform/1/protocols/smb/sessions

Close an SMB session user DELETE /platform/1/protocols/smb/sessions/<computer>/<user>

Close an SMB session computer DELETE /platform/1/protocols/smb/sessions/<computer>

View the detailed JSON schemafor the SMB session

GET /platform/1/protocols/smb/sessions?describe

View the detailed JSON schemafor the SMB session user

GET /platform/1/protocols/smb/sessions/<computer>/<user>?describe

View the detailed JSON schemafor the SMB session computer

GET /platform/1/protocols/smb/sessions/<computer>?describe

Query parameters

sort=<string>


dir=[ASC|DESC]


limit=<integer>


resume=<string>


Object properties


total Integer Specifies the total number ofsessions available.

N/A

resume String Specifies the value for the resumeargument to be used for continuationcalls.

N/A

id Integer Specifies the ID for the SMB session. sessions

computer String Specifies the internet address for theclient.

sessions




user String Specifies the local user name. sessions

client_type String Specifies the client type. sessions

openfiles Integer Specifies the number of files currentopened by the client.

sessions

active_time Integer Specifies the number of secondssince the session started.

sessions

idle_time Integer Specifies the number of secondssince the last client operation.

sessions

guest_login Boolean When set to true, guests can log in. sessions

encryption Boolean When set to true, the session isencrypted.

sessions

SMB share settings resource

Applies the standard system object pattern to default SMB share settings.


Get SMB share settings GET /platform/1/protocols/smb/settings/share

Modify SMB share settings PUT /platform/1/protocols/smb/settings/share

View the detailed JSON schema forSMB share settings

GET /platform/1/protocols/smb/settings/share?describe

Query parameters


If this parameter is specified as effective, or if it is not specified, all export fieldsare shown. If this parameter is specified as user, only fields with non-default valuesare shown. If this parameter is specified as default, the original values arereturned.

Object properties


allow_execute_always Boolean Enables users to execute files thatthey have read rights for.

settings

strict_locking Boolean Specifies whether byte range lockscontend against SMB I/O.

settings

hide_dot_files Boolean Hides files and directories that beginwith a period.

settings

impersonate_guest String Specifies the condition in which useraccess is performed as the guestaccount.

settings


SMB 97


strict_flush Boolean Determines whether the data isalways flushed to disk.

settings

mangle_byte_start Integer The starting value for the automaticbyte mangling range (in decimalnotation).

settings

directory_create_mask Integer Specifies the permission bits (indecimal notation) that can be setwhen a directory is created.

settings

directory_create_mode Integer Specifies the permission bits that areset when a directory is created.

settings

file_create_mask Integer Specifies the permission bits (indecimal notation) that can be setwhen a file is created.

settings

file_create_mode Integer Specifies the permission bits that areset when a file is created.

settings

create_permissions String Determines how permissions are setfor new files and directories in theSMB share.

settings

mangle_map String Specifies the character mangle map. settings

impersonate_user Array Specifies the user account to be usedas a guest account.

settings

change_notify String Specifies the level of changenotification alerts on the SMB share.

settings

oplocks Boolean Specifies whether or not to supportoplocks.

settings

allow_delete_readonly Boolean Specifies whether read-only files inthe SMB share can be deleted.

settings

ntfs_acl_support Boolean Supports NTFS Access Control List(ACL) on files and directories.

settings

access_based_enumeration

Boolean Enumerates only the files and foldersthat the requesting user has accessto, but does not apply to the rootdirectory of the share.

settings

access_based_enumeration_root_only

Boolean Specifies whether access-basedenumeration is used in the rootdirectory of the SMB share.

settings

host_acl Array Provides a list of hostnames,subnets, or IP addresses that areallowed or denied access to theshare. All of these types are allowedunless specifically denied. It isrecommended that a deny clause bethe final entry in the list.

settings



SMB global settings resource

Applies the standard system object pattern to the global SMB share settings.


Get the global SMB settings GET /platform/1/protocols/smb/settings/global

Modify the global SMB settings PUT /platform/1/protocols/smb/settings/global

View the detailed JSON schema for theSMB share summary

GET /platform/1/protocols/smb/settings/global?describe

Query parameters


When specified as effective, or when not specified, all the fields are returned.When specified as user, only the fields with non-default values are returned. Whenspecified as default, the original values are returned.

Object properties


service Boolean Specifies whether the SMB service isenabled.

settings

access_based_share_enum Boolean Enumerates only shares that therequesting user has access to.

settings

audit_fileshare String Specifies the level of file share auditevents to log.

settings

audit_logon String Specifies the level of logon auditevents to log.

settings

dot_snap_accessible_child Boolean Enables access to .snapshotdirectories in SMB sharesubdirectories. This property does notaffect the root directory of the SMBshare.

settings

dot_snap_accessible_root Boolean Enables access to the .snapshotdirectory in the root of all the SMBshares.

settings

dot_snap_visible_child Boolean Shows .snapshot directories in theSMB share subdirectories. Thisproperty does not affect the rootdirectory of the SMB share.

settings

dot_snap_visible_root Boolean Shows the .snapshot directory in theroot of all SMB shares.

settings

enable_security_signatures Boolean Indicates whether the server supportssigned SMB packets.

settings


SMB 99


guest_user String Specifies the fully qualified usernameto use for guest access.

settings

ignore_eas Boolean Specifies whether to ignore extendedattributes (EAs) on files.

settings

onefs_cpu_multiplier Integer Specifies the number of OneFS driverworker threads per CPU.

settings

onefs_num_workers Integer Sets the maximum number of OneFSdriver worker threads.

settings

require_security_signatures Boolean Indicates whether the server requiressigned SMB packets.

settings

server_string String Provides a description of the server. settings

srv_cpu_multiplier Integer Specifies the number of SRV serviceworker threads per CPU.

settings

srv_num_workers Integer Sets the maximum number of SRVservice worker threads.

settings

support_netbios Boolean Specifies whether NetBIOS support issupported on the server.

settings

support_smb2 Boolean Specifies whether the SMB2 protocolis supported on the server.

settings

System jobs overviewThe most critical function of OneFS is maintaining the integrity of data on your Isiloncluster. Other important system maintenance functions include monitoring andoptimizing performance, detecting and mitigating drive and node failures, and freeing upavailable space.

Because maintenance functions use system resources and can take hours to run, OneFSperforms them as jobs that run in the background through a service called Job Engine.The time it takes for a job to run can vary significantly depending on a number of factors.These include other system jobs that are running at the same time; other processes thatare taking up CPU and I/O cycles while the job is running; the configuration of yourcluster; the size of your data set; and how long since the last iteration of the job was run.

Up to three jobs can run simultaneously. To ensure that maintenance jobs do not hinderyour productivity or conflict with each other, Job Engine categorizes them, runs them atdifferent priority and impact levels, and can temporarily suspend them (with no loss ofprogress) to enable higher priority jobs and administrator tasks to proceed.

In the case of a power failure, Job Engine uses a checkpoint system to resume jobs asclose as possible to the point at which they were interrupted. The checkpoint systemhelps Job Engine keep track of job phases and tasks that have already been completed.When the cluster is back up and running, Job Engine restarts the job at the beginning ofthe phase or task that was in process when the power failure occurred.

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 providesstatistics and reporting tools that you can use to determine how long different systemjobs take to run in your OneFS environment.



Note

To initiate any Job Engine tasks, you must have the role of SystemAdmin in the OneFSsystem.

System job resourcesYou can retrieve, create, modify, or delete system job settings and configurations.

Job types resource

Applies the standard collection pattern to system job types.


Get all system job types GET /platform/1/job/types

Get a system job type GET /platform/1/job/types/<name>

Modify a system job type PUT /platform/1/job/type/<name>

View the detailed JSON schema for this resource. GET /platform/1/job/types?describe

Query parameters

sort=<string>


dir=[ASC|DESC]


show_all=<Boolean>

Whether or not all job types are returned, including hidden job types. The defaultvalue is false.

Object properties


total Integer Specifies the total number of jobtypes available.

N/A

allow_multiple_instances Boolean Determines whether multipleinstances of the job type can runsimultaneously.

types

description String Provides a brief description of the jobtype.

types

enabled Boolean Determines whether the job type isenabled and is able to run on thesystem.

types

exclusion_set String Specifies a set of mutually-exclusivejob types for the job. No job in the setcan run concurrently with another jobin the same set.

types


System jobs overview 101


hidden Boolean Determines whether the job type istypically visible in the webadministration interface.

types

id String Specifies the system-assigned ID forthe job type.

types

policy String Specifies the default impact policy forthe job type.

types

priority Integer Specifies the default priority for thejob type in descending order ofpriority.

types

schedule String Specifies a schedule for the job type. types

Job policies resource

Applies the standard collection pattern to job impact policies.


Get all job impact policies GET /platform/1/job/policies

Get a job impact policy GET /platform/1/job/policies/<name>

Create a job impact policy POST /platform/1/job/policies

Modify a job impact policy PUT /platform/1/job/policies/<name>

Delete a job impact policy DELETE /platform/1/job/policies/<name>

View the detailed JSON schema for this resource GET /platform/1/job/policies?describe

Query parameters

sort=<string>


dir=[ASC|DESC]


show_all=<Boolean>

Determines if all job types are returned, including hidden job types. The default valueis false.

resume=<string>


Object properties


total Integer Specifies the total number of policiesthat are available.

N/A




resume String Specifies the value of the resumeargument for continuation calls.

N/A

description String Specifies a description of the impactpolicy.

policies

id String Specifies the system-assigned ID forthe impact policy. In a POST request,this value is the ID that refers to theitem in the collection item resourcepath.

policies

intervals Array Specifies the time span for the impactpolicy.

policies

begin String Specifies the beginning time for thepolicy in the following format:'WWWW HH:MM', where WWWW isthe full name of the day of the week,HH is the hour (00-23), and MM is theminute (00-59).

intervals

end String Specifies the ending time for theimpact, in the following format:'WWWW HH:MM', where WWWW isthe full name of the day of the week,HH is the hour (00-23), and MM is theminute (00-59).

intervals

impact String Specifies the impact of the time spanas low, medium, high, or paused.

intervals

name String Specifies the name of the impactpolicy.

policies

system Boolean Determines whether the impact policyis read-only.

policies

Jobs resource

Applies the standard collection pattern to OneFS system jobs.


Get information about all system jobs GET /platform/1/job/jobs

Get information about a system job GET /platform/1/job/jobs/<id>

Create a system job POST /platform/1/job/jobs

Modify a system job PUT /platform/1/job/jobs/<id>

View the detailed JSON schema for this resource GET /platform/1/job/jobs?describe

Query parameters

sort=<string>




dir=[ASC|DESC]


batch=<Boolean>

Determines if other query parameters are ignored. When set to true, all other queryparameters are ignored, and the results are returned unsorted and as quickly aspossible.

state=[running|paused_user|paused_system|paused_policy|paused_priority]

Return only the jobs that are in the specified state.

limit=<integer>


resume=<string>


Object properties


total Integer Specifies the number of jobsavailable.

N/A


N/A

create_time Integer Specifies the time the job wasqueued in seconds from UNIX Epoch.

jobs

current_phase Integer Specifies the current phase of thejob.

jobs

description String Specifies a description of the job. jobs

id Integer Specifies the system-assigned ID forthe job.

jobs

impact String Specifies a value for the impact of thejob on the system. Options includelow, medium, high, and paused.

jobs

participants Integer Specifies the set of device IDs(devids) that are working on the job.

jobs

paths String Specifies the paths that the job isqueued for.

jobs

policy String Specifies the impact policy that isapplied to this job.

jobs

priority Integer Specifies the current priority of thejob in descending order ofimportance.

jobs

progress String Specifies a human-readabledescription of the progress of the job.The value for this property is defined

jobs




by each job implementation and canvary between the phases of the job.

retries_remaining Integer Specifies the number of retriesavailable if the job fails.

jobs

running_time Integer Specifies how long the job has beenrunning.

jobs

start_time Integer Specifies when the job started inseconds from UNIX Epoch.

jobs

state String Specifies the current state of the job.Options include running,

paused_user, paused_system,

paused_policy,

cancelled_user,

cancelled_system, failed,

succeeded, and unknown.

jobs

total_phases Integer Specifies the total number of phasesfor the job type.

jobs

type String Specifies the job type. jobs

waiting_on Integer Specifies the system-assigned ID ofthe job that precedes another job inthe queue.

jobs

waiting_reason String Specifies the reason the job iswaiting. For example, a job mightwaiting because it is lower in priority.

jobs

allow_dup Boolean Determines if the job is queued whenanother job of the same type isalready running or queued.

N/A

changelistcreate_params Object Specifies the required parameters forthe ChangelistCreate job.

N/A

newer_snapid Integer Specifies the newer snapshot ID. changelistcreate_params

older_snapid Integer Specifies the older snapshot ID. changelistcreate_params

retain_repstate Boolean Determines if the replication record isretained after a changelist is created.Retaining a replication record allowsa changelist to be recreated later.

changelistcreate_params

domainmark_params Object Specifies parameters for thedomainmark job.

N/A

delete Boolean Determines if the operation is adelete operation.

domainmark_params

root String Specifies the /ifs path to associate

with the domain.

domainmark_params




type String Specifies the type of domain. domainmark_params

prepair_params Object Specifies the parameters for thePermissionRepair job.

N/A

mapping_type String Specifies the type of permissions forconvert mode. Options includeglobal, sid, unix, and native.

prepair_params

mode String Specifies the type ofPermissionRepair operation. Optionsinclude clone, inherit, andconvert.

prepair_params

template String Designates an /ifs file or directory

as a template. This template isrequired for clone and inherit modesand is not accepted for convert mode.

prepair_params

zone String Specifies the authentication zone.This zone is not accepted for clone orinherit modes.

prepair_params

snaprevert_params Object Specifies the parameters required forthe SnapRevert job.

N/A

snapid Integer Specifies the snapshot to revert. snaprevert_params

Job reports resource

Applies the standard collection pattern to system job reports.


Get all job reports GET /platform/1/job/reports

Get a job report GET /platform/1/job/reports/<id>

View the detailed JSON schema for this resource GET /platform/1/audit/settings?describe

Query parametersbegin=<integer>

Returns only reports at or after the given time in seconds from UNIX Epoch.

end=<integer>

Returns only reports before the given time in seconds from UNIX Epoch.

job_id=<integer>

Returns only reports with the specified job ID.

job_type=<string>

Returns only reports with the specified job type

limit=<integer>




resume=<string>


Object properties


total Integer Specifies the total number of reportsthat are available.

N/A


N/A

id String Specifies the system-assigned ID forthe reported job event.

reports

job_id Integer Specifies the system-assigned ID forthe job.

reports

job_type String Specifies the job type. reports

phase Integer Specifies the job phase number atthe time of the reported event.

reports

results String Specifies the job results. reports

time Integer Specifies the time of the reportedevent in seconds from UNIX Epoch.

reports

Job events resource

Applies the standard collection pattern to system job events.


Get information about job events GET /platform/1/job/events

View the detailed JSON schema for this resource GET /platform/1/job/events?describe

Query parameters

begin=<integer>

Returns only events at or after the given time in seconds from UNIX Epoch.

end=<integer>

Returns only events before the given time in seconds from UNIX Epoch.

job_id=<integer>

Returns only events for the specified job ID.

job_type=<string>

Returns only events for the specified job type

state=[running|paused_user|paused_system|paused_policy|paused_priority|cancelled_user|cancelled_system|failed|succeeded|unknown]

Return only the events for jobs that are in the specified state.

limit=<integer>




resume=<string>


Object properties


total Integer Specifies the total number of eventsthat are available.

N/A


N/A

id String Specifies the system-assigned ID forthe reported job event.

events


events

job_type String Specifies the job type. events

message String Specifies a description of the event. events

phase Integer Specifies the job phase number atthe time of the reported event.

events

policy String Specifies the policy in effect for thejob at the time of the event.

events

progress String Specifies a human-readabledescription of the progress of the job.The value for this property is definedby each job implementation and canvary between the phases of the job.

events

running_time Integer Specifies how long the job will take tocomplete.

events

results String Specifies the job results. events

time Integer Specifies the time of the reportedevent in seconds from UNIX Epoch.

events

Job statistics resource

Provides statistics about system jobs and workers across the cluster.


Get system job statistics GET /platform/1/job/statistics

View the detailed JSON schema for this resource. GET /platform/1/job/statistics?describe




Object properties


total Integer Specifies the total number of jobstatistics that are available.

N/A


jobs

nodes Array Specifies properties for the node. jobs

cpu Object Specifies properties for the CPU. nodes

average Integer Specifies the average CPU usage ofthe job on the node.

cpu

current Integer Specifies the current CPU usage ofthe job on the node.

cpu

maximum Integer Specifies the maximum CPU usage ofthe job on the node.

cpu

minimum Integer Specifies the minimum CPU usage ofthe job on the node.

cpu

io Object Specifies the input and outputproperties.

nodes

read Object Specifies the read properties. io

bytes Integer Specifies the number of bytes thatwere recently read by this job on thisnode.

read

ops Integer Specifies the number of readoperations that were recentlyperformed by this job on this node.

read

write Object Specifies the write properties. io

bytes Integer Specifies the number of bytes thatwere recently written by this job onthis node.

write

ops Integer Specifies the number of writeoperations that were recentlyperformed by this job on this node.

write

memory Object Specifies properties for memoryusage.

nodes

physical Object Specifies the properties for physicalmemory usage.

memory

average Integer Specifies the average physicalmemory usage of the job on the nodein KB.

physical

current Integer Specifies the current physicalmemory usage of the job on this nodein KB.

physical




maximum Integer Specifies the maximum physicalmemory usage of the job on this nodein KB.

physical

minimum Integer Specifies the minimum physicalmemory usage of the job on this nodein KB.

physical

virtual Object Specifies the properties for virtualmemory usage.

memory

average Integer Specifies the average virtual memoryusage of the job on the node in KB.

virtual

current Integer Specifies the current virtual memoryusage of the job on this node in KB.

virtual

maximum Integer Specifies the maximum virtualmemory usage of the job on this nodein KB.

virtual

minimum Integer Specifies the minimum virtualmemory usage of the job on this nodein KB.

virtual

node Integer Specifies the devid of the node. nodes

pid Integer Specifies the process ID of the node. nodes

total_workers Integer Specifies number of workers for thisjob on the node.

nodes

workers Object Specifies properties for the workers. nodes

stw Integer Specifies the sleep-to-work ratio forthe worker.

workers

task String Specifies a non-human-readablerepresentation of the task the workeris processing.

workers

task_result String Specifies a non-human-readablerepresentation of the task results thatthe worker produced.

workers

worker Integer Specifies a system-assigned ID to theworker.

workers

phase Integer Specifies the phase that the job iscurrently in.

nodes

total_node Integer Specifies the number of nodes thatare participating in the job.

nodes

System job API examplesYou can see examples for some system job API calls.



Modify a job type

You can modify a system job type.

Request example

PUT /platform/1/job/types/AVScanAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'policy': 'MEDIUM', 'enabled': True}

Response example

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

Create a job policy

You can create a system job policy.

Request example

POST /platform/1/job/policiesAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'intervals': [ { 'impact': 'High', 'begin': 'Tuesday 00:00', 'end': 'Thursday 23:59'} ], 'name': 'myPolicy', 'description': 'Custom policy' }

Response example

201 CREATEDContent-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/1/job/policies/myPolicyAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'intervals': [ { 'impact': 'Medium', 'begin': 'Tuesday 00:00',



'end': 'Thursday 23:59'} ], 'description': 'Custom policy - medium impact Tuesday through Thursday'}

Response example

204 No ContentContent-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 has completed.

Request example

POST /platform/1/job/jobsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'type': 'AVScan', 'allow_dup': True}

Response example

201 CREATEDContent-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/1/job/jobs/AVScanAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'state': 'pause'}

Response example

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

SyncIQ backup and recovery overviewOneFS enables you to replicate data from one Isilon cluster to another through the SyncIQsoftware module. You must activate a SyncIQ license on both Isilon clusters before youcan replicate data between them.

You can replicate data at the directory level while optionally excluding specific files andsub-directories from being replicated. SyncIQ creates and references snapshots to



replicate a consistent point-in-time image of a root directory. Metadata such as accesscontrol lists (ACLs) and alternate data streams (ADS) are replicated along with data.

SyncIQ enables you to maintain a consistent backup copy of your data on another Isiloncluster. SyncIQ offers automated failover and failback capabilities that enable you tocontinue operations on another Isilon cluster if a primary cluster becomes unavailable.

Sync resourcesYou 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>, <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.


SyncIQ backup and recovery overview 113

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 "==".


accessed_after No operator is required; every operation is set to "==".


birth_time No operator is required; every operation is set to "==".


birth_before No operator is required; every operation is set to "==".


birth_after No operator is required; every operation is set to "==".


changed_time No operator is required; every operation is set to "==".


changed_before No operator is required; every operation is set to "==".


changed_after No operator is required; every operation is set to "==".


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 "!=".



Type Conditions

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.

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 jobs resource

Applies the standard collection pattern to SyncIQ replication jobs.


Get a list of all replication jobs GET /platform/1/sync/jobs

Get the details of a replication job GET /platform/1/sync/jobs/<job_id>

Start a replication job POST /platform/1/sync/jobs

Modify an in-progress replication job PUT /platform/1/sync/jobs/<job_id>




View the detailed JSON schema for this resource GET /platform/1/sync/jobs?describe

Query parameters

sort=<string>


state=[scheduled|running|paused|finished|failed|canceled|needs_attention|unknown]

Return only those jobs that are in the specified state.

dir=[ASC|DESC]


limit=<integer>


resume=<string>


Object properties


total Integer Specifies the total number ofreplication jobs available.

N/A

resume String Specifies the value of the resumeargument to be used for continuationcalls.

N/A

action String Specifies the action taken by thereplication job. Options includeresync_prep, allow_write,

allow_write_revert, test, andrun.

jobs

ads_streams_replicated String Specifies the number of streams thatare created by the replication job.

jobs

block_specs_replicated Integer Specifies the number of blockspecifications that are required by thereplication job.

jobs

bytes_recoverable Integer Specifies the number of bytes thatcan be recovered by the replicationjob.

jobs

bytes_transferred Integer Specifies the number of bytes thatwere transferred by the replicationjob.

jobs




char_specs_replicated Integer Specifies the number of characterspecification files that are replicatedby the replication job.

jobs

directories_replicated Integer Specifies the number of directoriesthat are replicated by the replicationjob.

jobs

dirs_changed Integer Specifies the number of directoriesthat were changed by the replicationjob.

jobs

dirs_deleted Integer Specifies the number of directoriesthat were deleted by the replicationjob.

jobs

dirs_moved Integer Specifies the number of directoriesthat were moved by the replicationjob.

jobs

dirs_new Integer Specifies the number of directoriesthat were created by the replicationjob.

jobs

duration Integer Specifies the amount of time inseconds between the start and end ofthe replication job. If the replicationjob has not ended, this value is theamount of time since the replicationjob started. This field is null if thereplication job has not started.

jobs

end_time Integer Specifies the time that the replicationjob ended in Unix EPOCH seconds.This field is null if the replication jobhas not ended.

jobs

error String Specifies the primary error messagefor the replication job.

jobs

errors Array Specifies a list of error messages forthe replication job.

jobs

error_checksum_files_skipped

Integer Specifies the number of files withchecksum errors that were skipped bythe replication job.

jobs

error_io_files_skipped Integer Specifies the number of files with I/Oerrors that were skipped by thereplication job.

jobs

error_net_files_skipped Integer Specifies the number of files withnetwork errors that were skipped bythe replication job.

jobs

failed_chunks Integer Specifies the number of data chunksthat failed transmission.

jobs




fifos_replicated Integer Specifies the number of First In FirstOut (FIFO) files that were replicatedby the replication job.

jobs

file_data_bytes Integer Specifies the number of bytestransferred from the source to targetclusters.

jobs

files_changed Integer Specifies the number of files changedby the replication job.

jobs

files_linked Integer Specifies the number of files that arelinked by the replication job.

jobs

files_new Integer Specifies the number of files createdby the replication job.

jobs

files_selected Integer Specifies the number of files that areselected for replication before theyare transferred.

jobs

files_transferred Integer Specifies the number of files thatwere transferred by the replicationjob.

jobs

files_unlinked Integer Specifies the number of files thatwere unlinked by the replication job.

jobs

files_with_ads_replicated Integer Specifies the number of files withADS that were replicated by thereplication job.

jobs

flipped_lins Integer Specifies the number of LINs thathave changed between replicationjobs.

jobs

hard_links_replicated Integer Specifies the number of hard linksthat were replicated by the replicationjob.

jobs

hash_exceptions_fixed Integer Specifies the number of hashexceptions that were fixed by thereplication job. Files that havechanged on the target cluster for anyreason may fail a hash check.

jobs

hash_exceptions_found Integer Specifies the number of hashexceptions that were found by thereplication job.

jobs

id String Specifies a unique identifier for thereplication policy.

jobs

job_id Integer Specifies an ID for the replication job. jobs




lins_total Integer Specifies the number of LINs thatwere transferred by the replicationjob.

jobs

network_bytes_to_source Integer Specifies the total number of bytessent to the source cluster by thereplication job.

jobs

network_bytes_to_target Integer Specifies the total number of bytesthat were sent to the target cluster bythe replication job.

jobs

new_files_replicated Integer Specifies the number of new files thatwere replicated by the replication job.

jobs

num_retransmitted_files Integer Specifies the number of files thatwere retransmitted by the replicationjob.

jobs

phases Array Specifies data for each phase of thereplication job.

jobs

end_time Integer Specifies the time the replication jobcompleted for this phase.

phases

phase String Specifies the phase that thereplication job is in.

phases

start_time Integer Specifies the time that the replicationjob started for the phase.

phases

policy Object Specifies the replication policy that isassociated with the replication job, ornull if there is no associatedreplication policy with the replicationjob. Replication jobs without anassociated replication policy mightbe newly created and unavailable inthe underlying database.

jobs

action String Specifies the action taken by thisreplication policy. When set to copy,

source files are copied to the targetcluster. When set to sync, the source

directory is replicated to the targetdirectory. Files and directories thatwere deleted on the source cluster,moved within the target directory, orno longer match the selection criteriaare deleted from the target directory.

policy

check_integrity Boolean Determines whether cyclicredundancy checks (CRC) areperformed on the received data.

policy




conflicted Boolean Determines if the replication policywill start any scheduled replicationjobs after encountering an error. If setto true, the replication policy will notstart any more replication jobs untilthis field is set to false.

Note

This field should not be changedwithout the help of Isilon TechnicalSupport.

policy

description String Specifies a user-assigned descriptionfor the replication policy.

policy

disable_fofb Boolean Enables or disables data failover orfailback.

Note


policy

disable_stf Boolean Enables or disables the SnapshotTracking File (STF) based data transferthrough a file system scan for OneFSversions 6.5 or greater.

Note


policy

enabled Boolean Determines if a replication job willautomatically run based on aschedule for the replication policy.

policy

file_matching_pattern String Specifies a file matching pattern thatcan filter and search for a set of fileswith specific properties. For example,(a AND b) OR (x AND y).

policy

or_criteria Array Specifies an array that containsobjects with and_criteria properties,each set of which is logicallyconnected through the OR operator tocreate the full file matching pattern.

file_matching_pattern

and_criteria Array Specifies an array that containsindividual file criteria objects, each ofwhich describes one criterion. Thesevalues are connected logically

or_criteria




through the AND operator to form aset a criteria.

items Array Specifies criteria for finding a file. and_criteria

case_sensitive Boolean Determines if the value comparison iscase sensitive. The default value istrue.

items

attribute_exists Boolean Determines that a custom attributespecified in the field option isavailable. The default value is true.

items

field String Specifies the name of the fileattribute to match. This field is onlyrequired if the attribute is acustom_attribute type. The defaultvalue is empty. Additionally, theattribute_exists parameter must beset to true.

items

operator String Specifies how to compare theattribute of each file to the value. Forexample, ==, !=, >, <, <=, or !.

items

type String Specifies the type of file attributecriteria to match. For example, name,path, accessed_time, group_name,and so on.

items

value String orInteger

Specifies the value that the specifiedattribute of each file is compared to.

items

whole_word Boolean Determines if the attribute will matchthe entire word. The default value istrue.

items

force_interface Boolean Determines whether data is sentthrough only the subnet and pool thatis specified in thesource_network field. Set this

option when there are multipleinterfaces for the source subnet.When this option is enabled, thenet.inet.ip.choose_ifa_by_ipsrc sysctlmust also be set.

Note


policy

has_sync_state Determines whether the replicationpolicy has scanned the file system.When this field is set to false, the

policy




policy is reset. When this field is setto true, the policy is in progress.

id String Specifies the replication policy ID. Ina POST request, this is the ID of thecreated item that refers to the item inthe collection item resource path.

policy

last_job_state String Specifies the state of the most recentjob for the replication policy.

policy

last_started Integer Specifies the last time a replicationjob was started for the replicationpolicy. The value is null if thereplication policy has never run.

policy

last_success Integer Specifies a timestamp of the lastknown successfully completedreplication job. The value is null if noreplication jobs were successfullycompleted for the replication policy.

policy

log_level String Specifies the severity an event mustreach before the event is logged.

policy

log_removed_files Boolean Determines if the system will log anyfiles or directories that were deleteddue to a replication job.

policy

name String Specifies the user-assigned name ofthe replication policy.

policy

next_run Integer Specifies the next time the replicationjob is scheduled to run in Unix EPOCHseconds. This value is null if thereplication job is unscheduled.

policy

password_set Boolean Indicates if a password is set for thetarget cluster. The password value isnot shown in GET requests.

policy

report_max_age Integer Specifies the length of time inseconds that a replication policyreport is stored.

policy

report_max_count Integer Specifies the maximum number ofreplication policy reports that arestored on the system

policy

restrict_target_network Boolean Determines if a replication policy willconnect to only nodes with aSmartConnect zone specified in thetarget_host parameter. If this

value is set to false, replicationpolicies are not restricted to specifiednodes on the target cluster.

policy




schedule String Specifies a schedule for newreplication jobs on a replicationpolicy.

policy

source_exclude_directories Array Specifies the directories to excludefrom a replication job. If you modifythis field, a full or differentialreplication job is performed on alldata on the source cluster.

policy

source_include_directories Array Specifies the directories to include ina replication job. If you modify thisfield, a full replication job isperformed on all data on the sourcecluster.

policy

source_network Object Restricts replication policies on thelocal cluster to a specified subnetand pool.

policy

pool String Restricts replication policies to thespecified pool.

source_network

subnet String Restricts replication policies to thespecified subnet.

source_network

source_root_path String Specifies the root directory on thesource cluster that files are replicatedfrom. If you modify this field, a fullreplication job is performed on alldata on the source cluster.

policy

source_snapshot String Specifies an optional snapshot thatcan be copied and replicated from.

source_snapshot_archive Boolean Determines if archival snapshots ofthe source data are taken on thesource cluster before a replicationjob. When this value is set to true, asnapshot is taken.

policy

source_snapshot_expiration

Integer Specifies the length of time inseconds to keep a snapshot on thesource cluster before the snapshot isdeleted.

policy

source_snapshot_pattern String Specifies the name pattern forsnapshots that are taken on thesource cluster before a replicationjob.

policy

target_compare_initial_sync

Boolean Determines if the target clustercreates diffs against the originalreplication job. When this value is setto true, a diff is created.

policy




target_detect_modification Boolean Determines whether SyncIQ checksthe target directory for modificationsbefore replicating files.

policy

target_host String Specifies a hostname or IP addressfor the sync target cluster. Thereplication policy will not run if thetarget cluster host is modified andthe new target does not match thecurrent target association.

policy

target_path String Specifies an absolute file systempath on the target cluster for thereplication job.

policy

target_snapshot_alias String Specifies an alias for the snapshottaken on the target cluster after areplication job completes.

policy

target_snapshot_archive Boolean Determines if an archival snapshot ofthe target data is taken on the targetcluster after a successful replicationjob is complete. When this value isset to true, the snapshot is taken.

policy

target_snapshot_expiration Integer Specifies the length of time inseconds to keep a snapshot on thetarget cluster before deleting thesnapshot.

policy

target_snapshot_pattern String Specifies a snapshot naming patternfor snapshots that are taken on thetarget cluster after the replication jobcompletes. For information onsnapshot naming patterns, see theOneFS CLI Administration Guide.

policy

workers_per_node Integer Specifies the number of workerthreads on a node that are performinga replication job. In a POST request,this parameter is only valid when theaction property is set toallow_write or

allow_write_revert.

policy

policy_action String Specifies the action the replicationpolicy will perform. Options include:sync and copy.

jobs

policy_id String Specifies the system-assigned ID forthe replication policy.

jobs

policy_name String Specifies the user-assigned name forthe replication policy.

jobs




regular_files_replicated Integer Specifies the number of regular filesthat were replicated by the replicationjob.

jobs

retransmitted_files String Specifies the number of files thatwere retransmitted by the replicationjob. Files are retransmitted if they faila hash check or are missing from thetarget cluster for any reason.

jobs

retry Integer Specifies the number of times thereplication job was retried.

jobs

sockets_replicated Integer Specifies the number of sockets thatare being replicated by the replicationjob.

jobs

source_bytes_recovered Integer Specifies the number of bytes thatwere recovered on the source cluster.

jobs

source_directories_created Integer Specifies the number of directoriesthat were created on the sourcecluster.

jobs

source_directories_deleted Integer Specifies the number of directoriesthat were deleted on the sourcecluster.

jobs

source_directories_linked Integer Specifies the number of directoriesthat are linked on the source cluster.

jobs

source_directories_unlinked

Integer Specifies the number of directoriesthat are unlinked on the sourcecluster.

jobs

source_directories_visited Integer Specifies the number of sourcedirectories that were processed in theinitial replication job.

jobs

source_files_deleted Integer Specifies the number of files thatwere deleted on the source cluster.

jobs

source_files_linked Integer Specifies the number of files that arelinked on the source cluster.

jobs

source_files_unlinked Integer Specifies the number of files that areunlinked on the source cluster.

jobs

sparse_data_bytes Integer Specifies the number of sparse databytes that were transferred by thisreplication job.

jobs

start_time Integer Specifies the time the replication jobstarted in Unix EPOCH seconds. Thisfield is null if the replication job hasnot started.

jobs




state String Specifies the state of the replicationjob. Options include: scheduled,

running, paused, finished,

failed, canceled,

needs_attention, and unknown.

jobs

symlinks_replicated Integer Specifies the number of symlinks thatare replicated by the replication job.

jobs

sync_type Integer Specifies the type of actionperformed by the job. Optionsinclude: invalid, legacy,

initial, incremental,

upgrade, fofb, and domainmark.

jobs

target_bytes_recovered Integer Specifies the number of bytes thatwere recovered on the target cluster.

jobs

target_directories_created Integer Specifies the number of directoriesthat were created on the targetcluster.

jobs

target_directories_deleted Integer Specifies the number of directoriesthat were deleted on the targetcluster.

jobs

target_directories_linked Integer Specifies the number of directoriesthat are linked on the target cluster.

jobs

target_directories_unlinked Integer Specifies the number of directoriesthat are unlinked on the targetcluster.

jobs

target_files_deleted Integer Specifies the number of files thatwere deleted on the target cluster.

jobs

target_files_linked Integer Specifies the number of files that arelinked on the target cluster.

jobs

target_files_unlinked Integer Specifies the number of files that areunlinked on the target cluster.

jobs

target_snapshots Array Specifies list of the target snapshotscreated by this replication job.

jobs

total_chunks Integer Specifies the total number of datachunks that were transmitted by thisreplication job.

jobs

total_data_bytes Integer Specifies the total number of bytestransferred by the replication job.

jobs

total_files Integer Specifies the number of files thatwere changed by the replication job.

jobs




total_network_bytes Integer Specifies the total number of bytesthat were sent over the network bythe replication job.

jobs

total_phases Integer Specifies the total number of phasesfor the replication job.

jobs

unchanged_data_bytes Integer Specifies the number of bytes thatwere unchanged by the replicationjob.

jobs

up_to_date_files_skipped Integer Specifies the number of up-to-datefiles that are skipped by thereplication job. These files were onthe source cluster during a file systemscan, but were not transferredbecause the file had not changed.

jobs

updated_files_replicated Integer Specifies the number of updates filesthat are replicated by the replicationjob.

jobs

user_conflict_files_skipped Integer Specifies the number of files withuser conflicts that are skipped by thereplication job.

jobs

warnings Array Specifies a list of warning messagesfor the replication job.

jobs

workers Array Specifies a list of workers for thereplication job.

jobs

connected Boolean Determines whether the source andtarget clusters are connected on thenetwork.

workers

last_split Integer Specifies the time for when the lastnetwork split occurred in UNIX time.

workers

last_work Integer Specifies the time for when theworkers last received a replication jobin UNIX time.

workers

lin Integer Specifies the LIN that the replicationjob is performing an operation on.

workers

process_id Integer Specifies a process ID for eachworker.

workers

source_host Integer Specifies the source hostname foreach worker.

workers

target_host Integer Specifies the target hostname foreach worker.

workers

worker_id Integer Specifies an ID for each worker. workers



Sync policies resource

Applies the standard collection pattern to SyncIQ replication policies.


Get all replication policies GET /platform/1/sync/policies

Get a replication policy GET /platform/1/sync/policies/<policy>

Create a replication policy POST /platform/1/sync/policies

Modify a replication policy PUT /platform/1/sync/policies/<policy>

Delete all replication policies DELETE /platform/1/sync/policies

Delete a replication policy DELETE /platform/1/sync/policies/<policy>

View the detailed JSON schema for this resource. GET /platform/1/sync/policies?describe

Query parameters

sort=<string>


scope=[user|effective]

Specifies which fields to return. The effective option returns all fields and theuser option returns only fields with non-default values. If you do not specify thescope parameter, all fields are returned. The default value is effective.

dir=[ASC|DESC]


local_only=<Boolean>

Deletes the replication policy from only the source cluster. This parameter is useful ifthe target cluster is unavailable to have the replication policy removed.

force=<Boolean>

Deletes only replication jobs that are not currently running.

limit=<integer>


resume=<string>


Object properties


id String Provides the system ID assigned tothe replication policy.

policies

conflicted Boolean If set to true, checks if the mostrecent run of the replication job failedbecause of a conflict with anotherreplication job or because of incorrect

policies




settings. Conflicted policies will stopafter a failure until the problem isfixed and the conflicted flag isremoved.

action String If set to copy, source files are copiedto the target cluster. If set to sync,files and directories that were deletedon the source cluster and files that nolonger match the selection criteria aredeleted from the target directory.

policies

name String Specifies the user-assigned name forthe replication policy.

policies

check_integrity Boolean If set to true, determines if the datawas transmitted correctly across thenetwork. If the transfer fails, thereplication job fails and the error islogged. If set to false, no check isperformed.

policies

description String Provides the user-defined descriptionof the replication policy.

policies

enabled Boolean If set to true, replication jobs areautomatically run based on theassociated replication policy andschedule. If set to false, replicationjobs are only performed whenmanually triggered.

policies

file_matching_pattern Array Specifies criteria that determineswhich files are selected for transfer.

policies

source_root_path String Specifies the root directory on thesource cluster for the replication job.

policies

source_include_directories Array Specifies the directories that areincluded in the replication job.

policies

source_exclude_directories Array Specifies the directories that areexcluded from the replication job.

policies

target_path String Specifies the destination file systempath on the target cluster for thereplication job.

policies

target_snapshot Boolean If set to true, archival snapshots ofthe data are taken on the targetcluster after a successful replicationjob completes. If set to false, nosnapshots are taken.

policies

target_detect_modifications

Boolean If set to true, SyncIQ detects if fileswere changed on the target clusterand resends all modified files.

policies




schedule String Specifies a schedule that determineswhen replication jobs should run for areplication policy.

policies

log_level String Provides the severity level that anevent must reach before the event islogged.

policies

log_removed_files Boolean If set to true, the system logs any filesor directories that are deleted duringa replication job. If set to false, nodeleted files are logged.

policies

report_max_age Integer Specifies the length of time, inseconds, that a replication policyreport is stored.

policies

report_max_count Integer Specifies the maximum number ofreplication policy reports that can bestored on the cluster.

policies

source_network Object Restricts replication policies on thelocal cluster to the specified subnetand pool.

policies

restrict_target_network Boolean If set to true, limits the replicationpolicy to nodes that are in the targetzone name. If set to false, thereplication policy applies to allavailable nodes in the target cluster.

policies


Boolean If set to true, files on the target clusterare compared against the sourcecluster during the initial replicationjob, and missing files are transferred.

policies

last_success Integer Species a timestamp for when thelast known successful replication jobcompleted.

policies

target_snapshot_alias String Specifies the alias of the snapshottaken on the target cluster after thereplication job completes.

policies

target_snapshot_pattern String Specifies the naming pattern forsnapshots taken on the target clusterafter the replication job completes.

policies

target_snapshot_expiration Integer Specifies the length of time inseconds that snapshots are kept onthe target cluster.

policies

target_snapshot_rename_pattern

String Specifies the naming pattern forsnapshots taken on the sourcecluster before a replication job.

policies




target_snapshot_rename_expiration

Integer Specifies the length of time inseconds that snapshots are kept onthe source cluster.

policies

workers_per_node Integer Specifies the number of workerprocesses on a node that areperforming a replication job.

policies

source_host String Specifies the hostname or IP addressof a source cluster for a replicationjob.

policies

source_cluster_grid String Specifies the globally uniqueidentifier for the source cluster.

policies

Sync policies reset resource

Resets the incremental state of a replication policy and forces a full sync or copy. Youmust post an empty object: {} to reset the policy.


Reset a replication policy. POST /platform/1/sync/policy/<policy>/reset

View the detailed JSON schema for thisresource.

GET /platform/1/sync/policy/<policy>/reset?describe


Object propertiesThere are no properties for this resource.

Sync reports resource

Applies the standard collection pattern to SyncIQ reports.


Get all replication reports GET /platform/1/sync/reports

Get a replication report GET /platform/1/sync/reports/<report-id>

View the detailed JSON schema for this resource. GET /platform/1/sync/reports?describe

Query parameters

sort=<string>


policy_name=<string>

Return only those reports that have the specified replication policy name.




Return only those reports whose replication jobs are in the specified state.

dir=[ASC|DESC]

Directions for the sort order are ascending ( ASC) or descending (DESC). The defaultsetting is ASC.

newer_than=<integer>

Return only those reports for replication jobs that started before the specified numberof days.

reports_per_policy=<integer>

Return only the specified number of reports per replication policy. Ten replicationpolicies are returned by default.

limit=<integer>


resume=<string>


Object properties



N/A


N/A



reports


reports


reports


reports


reports


reports


reports





reports


reports


reports


reports


reports


reports


reports


reports



reports


reports


reports


reports


reports


reports





reports


reports


reports


reports


reports


reports


reports


reports


reports


reports


reports


reports

job_id Integer Specifies an ID for the replication job. reports


reports


reports





reports


reports


reports


reports


phases


phases


phases


source files are copied to the targetcluster. When set to sync, the source


policy


policy


Note


policy


policy


policy




Note



Note


policy


policy

file_matching_pattern String Specifies a file matching pattern thatcan filter and search for a set of fileswith specific properties. For example,(a AND b) OR (x AND y).

policy



and_criteria Array Specifies an array that containsindividual file criteria objects, each ofwhich describes one criterion. Thesevalues are connected logicallythrough the AND operator to form aset a criteria.

or_criteria



items


items

field String Specifies the name of the fileattribute to match. This field is onlyrequired if the attribute is acustom_attribute type. The defaultvalue is empty. Additionally, the

items




attribute_exists parameter must beset to true.


items


items



items


items


option when there are multipleinterfaces for the source subnet.When this option is enabled, thenet.inet.ip.choose_ifa_by_ipsrc sysctlmust also be set.

Note


policy

has_sync_state Determines whether the replicationpolicy has scanned the file system.When this field is set to false, thepolicy is reset. When this field is setto true, the policy is in progress.

policy


policy


policy


policy

last_success Integer Specifies a timestamp of the lastknown successfully completed

policy




replication job. The value is null if noreplication jobs were successfullycompleted for the replication policy.


policy


policy


policy


policy


policy


policy


policy



policy


policy


policy


policy





policy


source_network


source_network


policy


policy


Integer Specifies the length of time inseconds to keep a snapshot on thesource cluster before the snapshot isdeleted.

policy


policy



policy


policy


policy


policy


policy





policy


policy


policy

workers_per_node Integer Specifies the number of workerthreads on a node that are performinga replication job. In a POST request,this parameter is only valid when theaction property is set toallow_write or

allow_write_revert.

policy


reports


reports


reports


reports


reports


reports


reports


reports





reports


reports


reports



reports


reports


reports


reports


reports


reports


reports



failed, canceled,


reports

subreport_count Integer Specifies the number of subreportsthat are available for the replicationjob.

reports


reports




reports





reports


reports


reports


reports


reports


reports


reports


reports


reports


reports


reports


reports


reports


reports


reports


reports





reports


reports


reports

Sync reports subreports resource

Applies the standard collection pattern to subreports about replication jobs.


Get all subreports for a single report GET /platform/1/sync/reports/<ID>/subreports

Get a subreport for a single report GET /platform/1/sync/reports/<ID>/subreports/<SID>


GET /platform/1/sync/reports/<ID>/subreports?describe

Query parameters

sort=<string>


dir=[ASC|DESC]

Directions for the sort order are ascending (ASC) or descending (DESC). Thedefault setting is ascending.


Return only those subreports for replication jobs that started before the specifiednumber of days.

limit=<integer>


resume=<string>


Object properties



N/A


N/A






subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports

end_time Integer Specifies the time that the replicationjob ended in Unix EPOCH seconds.

subreports




This field is null if the replication jobhas not ended.


subreports


subreports



subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports





subreports


subreports


subreports


subreports


subreports

job_id Integer Specifies an ID for the replication job. subreports


subreports


subreports


subreports


subreports


subreports


subreports


phases


phases


phases


source files are copied to the target

policy




cluster. When set to sync, the source



policy


Note


policy


policy


Note


policy


Note


policy


policy

file_matching_pattern String Specifies a file matching pattern thatcan filter and search for a set of files

policy




with specific properties. For example,(a AND b) OR (x AND y).



and_criteria Array Specifies an array that containsindividual file criteria objects, each ofwhich describes one criterion. Thesevalues are connected logicallythrough the AND operator to form aset a criteria.

or_criteria



items


items

field String Specifies the name of the fileattribute to match. This field is onlyrequired if the attribute is acustom_attribute type. The defaultvalue is empty. Additionally, theattribute_exists parameter must beset to true.

items


items


items



items


items


option when there are multipleinterfaces for the source subnet.

policy




When this option is enabled, thenet.inet.ip.choose_ifa_by_ipsrc sysctlmust also be set.

Note


has_sync_state Determines whether the replicationpolicy has scanned the file system.When this field is set to false, thepolicy is reset. When this field is setto true, the policy is in progress.

policy


policy


policy


policy

last_success Integer Specifies a timestamp of the lastknown successfully completedreplication job. The value is null if noreplication jobs were successfullycompleted for the replication policy.

policy


policy


policy


policy


policy


policy





policy


policy



policy


policy


policy


policy


policy


source_network


source_network


policy


policy


Integer Specifies the length of time inseconds to keep a snapshot on the

policy




source cluster before the snapshot isdeleted.


policy



policy


policy


policy


policy


policy


policy


policy


policy

workers_per_node Integer Specifies the number of workerthreads on a node that are performinga replication job. In a POST request,this parameter is only valid when theaction property is set to

policy




allow_write or

allow_write_revert.


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports



subreports


subreports


subreports


subreports





subreports


subreports


subreports



failed, canceled,


subreports


subreports




subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports





subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports

Sync reports rotate resource

Rotates the records in the database and periodically removes older reports from thesystem.


Retrieve information on whether the rotation isrunning.

GET /platform/1/sync/reports-rotate

Force the reports in the database to rotate. POST /platform/1/sync/reports-rotate

View the detailed JSON schema for this resource. GET /platform/1/sync/reports-rotate?describe




Object properties


message String Reports if the replication reports arecurrently being rotated.

N/A

running Boolean Determines whether the replicationreports are being rotated.

N/A

Sync target policies resource

Applies the standard collection pattern to SyncIQ target replication policies.


Get all target replication policies GET /platform/1/sync/target/policies

Get a target replication policy GET /platform/1/sync/target/policies/<policy-id>


GET /platform/1/sync/target/policies?describe

Query parameters

sort=<string>


target_path=<string>

Return only those replication policies with the specified target path.

dir=[ASC|DESC]


limit=<integer>


resume=<string>


Object properties


total Integer Specifies the total number ofreplication policies available.

N/A


N/A

failover_failback_state String Specifies the condition of thereplication policy with respect to datafailover/failback. Options include:

policies




writes_disabled,

enabling_writes,

writes_enabled,

disabling_writes,

creating_resync_policy,

resync_policy_created.

id String Specifies an ID for the replicationpolicy.

policies

last_job_state String Specifies the state of the lastreplication job run for the replicationpolicy. Options include: scheduled,


failed, canceled,


policies

last_source_coordinator_ip String Specifies the IP address from which aSyncIQ coordinator daemon lastconnected to the cluster to updateinformation about the job processesfor this replication policy.

policies

last_update_from_source Integer Specifies the time in Unix EPOCHseconds that the cluster was lastupdated with information about thereplication job from the source clusterfor this replication policy. The value isset to null if no update has occurredyet.

policies

legacy_policy Boolean Indicates if the replication policy wasdefined by a OneFS version before6.0. OneFS versions before 6.0 didnot have the target replication policyconcept, and canceling from thetarget side is unavailable

policies


policies

source_cluster_guid String Specifies a unique identifier for thesource cluster.

policies

source_host String Specifies the hostname or IP addressof the replication source cluster.

policies

target_path String Specifies the absolute file systempath on the target cluster for thereplication job destination.

policies



Sync target policies cancel resource

Cancels the most recent replication job for a replication policy from the target cluster.


Cancel the most recent replication job POST /platform/1/sync/target/policies/<policy>/cancel


GET /platform/1/sync/target/policies/<policy>/cancel?describe


Object properties


id String The unique identifier that refers to theitem in the collection item resourcepath.

N/A

Sync target reports resource

Applies the standard collection pattern to replication reports running on a target cluster.


Get all replication target reports GET /platform/1/sync/target/reports

Get a replication target report GET /platform/1/sync/target/reports/<report-id>


GET /platform/1/sync/target/reports?describe

Query parameters

sort=<string>


policy_name=<string>

Return only those target reports that have the specified policy name.


Return only those target reports whose replication jobs are in the specified state.

dir=[ASC|DESC]



Return only those reports with replication jobs that started before the specifiednumber of days.

reports_per_policy=<integer>



Return only the specified number of reports per replication policy. Ten reports arereturned by default.

limit=<integer>


resume=<string>


Object properties



N/A


N/A



reports


reports


reports


reports


reports


reports


reports


reports


reports





reports


reports


reports


reports


reports


reports



reports


reports


reports


reports


reports


reports


reports


reports





reports


reports


reports


reports


reports


reports


reports


reports


reports


reports

job_id Integer Specifies an ID for the replication job. reports


reports


reports


reports


reports





reports


reports


phases


phases


phases


reports


reports


reports


reports


reports


reports


reports


reports


reports


reports


reports






reports


reports


reports


reports


reports


reports


reports



failed, canceled,


reports


reports


reports




reports


reports


reports


reports





reports


reports


reports


reports


reports

target_path String Specifies the absolute file systempath on the target cluster for thereplication job.

reports


reports


reports


reports


reports


reports


reports


reports


reports


reports





reports


reports

Sync target reports subreports resource

Applies the standard collection pattern to SyncIQ subreports for replication jobs on thetarget cluster.


Get all target subreports for a single report GET /platform/1/sync/target/reports/<ID>/subreports

Get a target subreport for a single report GET /platform/1/sync/target/reports/<ID>/subreports/<SID>


GET /platform/1/sync/target/reports/<ID>/subreports?describe

Query parameters

sort=<string>


dir=[ASC|DESC]

Directions for the sort order are ascending (ASC) or descending (DESC). Thedefault setting is ascending.


Return only those subreports whose replication jobs are in the specified state.


Return only those subreports for replication jobs that started before the specifiednumber of days.

limit=<integer>


resume=<string>


Object properties



N/A





N/A



subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports





subreports


subreports


subreports



subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports





subreports


subreports


subreports


subreports


subreports

job_id Integer Specifies an ID for the replication job. subreports


subreports


subreports


subreports


subreports


subreports


subreports


phases


phases


phases


subreports





subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports



subreports


subreports


subreports


subreports


subreports


subreports





subreports



failed, canceled,


subreports


subreports


subreports




subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports

target_path String Specifies the absolute file systempath on the target cluster for thereplication job.

subreports





subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports


subreports

Sync rules resource

Applies the standard collection pattern to SyncIQ replication job performance rules. Rulescan restrict the amount of network bandwidth or files transferred per second forreplication policies.


Get all replication job performance rules. GET /platform/1/sync/rules

Create a replication job performance rule. POST /platform/1/sync/rules

Delete all replication job performance rules. DELETE /platform/1/sync/rules/




Delete all replication job performance rules bytype.

DELETE /platform/1/sync/rules?type=<string>

Delete a replication job performance rule. DELETE /platform/1/sync/rules/<rule>

View the detailed JSON schema for this resource. GET /platform/1/sync/rules?describe

Query parameters

sort=<string>


dir=[ASC|DESC]


type=[bandwidth|file_count|cpu]

Specifies the type of rule to delete.

limit=<integer>


resume=<string>


Object properties


total Integer Specifies the total number of rulesavailable.

N/A


N/A

description String Specifies a user-assigned descriptionto the performance rule.

rules

enabled Boolean Determines whether the performancerule is in effect during the specifiedintervals.

rules

id String Specifies the system-assigned ID forthe performance rule.

In a POST request, this value is the IDthat refers to the item in thecollection item resource path.

rules

schedule Array Specifies a list of time intervals that aperformance rule is in effect within agiven week. Options include begin,

end, or the day of the week, such as

monday, tuesday, wednesday,

rules




thursday, friday, saturday, orsunday.

begin String Specifies the start time for theschedule. The start time is inclusive,and the format is \"hh:mm\" wherehh: is the hour in 24-hour format andthe minutes. A null value indicatesthe beginning of the day (\"00:00\").

schedule

end String Specifies the end time for theschedule. The end time is inclusive,and the format is \"hh:mm\" with athree-letter weekday nameabbreviation, where hh: is the hour in24-hour format and the minutes. Anull value indicates the end of theday (\"23:59\").

schedule

limit Integer Specifies the amount of systemresources that are limited by the rule.Units include: kb/s for bandwidth,file/s for file-count, or a percentagethat indicates the processingpercentage used for the CPU.

rules

Sync settings resource

Applies the standard system object pattern to global SyncIQ settings.


Get global SyncIQ settings GET /platform/1/sync/settings

Modify global SyncIQ settings PUT /platform/1/sync/settings

View the detailed JSON schema for this resource. GET /platform/1/sync/settings?describe


Object properties


force_interface Boolean Determines whether data is sent overa specified source interface and asource subnet, which is useful if thereare multiple interfaces for a singlesource subnet. When enabling thisproperty, you must also set a defaultsource interface. This property isenabled for all new replication

N/A




policies unless otherwise specifiedwhen the replication policy is created.

report_email String Specifies email addresses to sendreplication job reports to.

N/A

report_max_age Integer Specifies the default amount ofseconds to retain a replication jobreport before the replication jobreport is deleted.

N/A

report_max_count Integer Specifies the maximum number ofreplication job reports to retain for areplication policy.

N/A

restrict_target_network Boolean Determines if replication policiesconnect only to nodes in the specifiedzone if the target cluster is set as aSmartConnect zone. This property isenabled for all new replicationpolicies unless otherwise specifiedwhen the replication policy is created.If this property is disabled,replication policies can connect toany node on the target cluster.

N/A

source_network Object Restricts replication policies on thelocal cluster to the specified subnetand pool.

N/A

service Array Specifies if the replication job serviceis on, paused, or off. If set to

paused, all replication jobs are

paused. If set to off, all replication

jobs are canceled.

N/A

Sync history file resource

Applies the standard collection pattern to OneFS replication job performance reports.These reports indicate the number of files per second that were sent by replicationpolicies at a given time.


Get all replication job performance reports. GET /platform/1/sync/history/file

View the detailed JSON schema for this resource. GET /platform/1/sync/history/file?describe

Query parameters

begin=<integer>

The beginning timestamp for the report.

end=<integer>

The ending timestamp for the report.



Object properties


total Integer Specifies the total number of reportsavailable.

N/A

allocated Integer Specifies a list of nodes that areallocated for the replication job.

statistics

id Integer Specifies an ID for a singleperformance report.

statistics

limit Integer Specifies the number of files persecond that can be sent by areplication policy.

statistics

timestamp Integer Specifies a timestamp for theperformance report.

statistics

total Integer Specifies the total number of files persecond that were sent during thereplication job.

statistics

Sync history network resource

Applies the standard collection pattern to OneFS replication job performance reports.These reports indicate the amount of network bandwidth consumed by data replicationpolicies at a given time.


Get all replication job performance reports. GET /platform/1/sync/history/network

View the detailed JSON schema for this resource. GET /platform/1/sync/history/network?describe

Query parameters

begin=<integer>

The beginning timestamp for the report.

end=<integer>

The ending timestamp for the report.

Object properties



N/A

allocated Integer Specifies a list of nodes that areallocated for the replication job.

statistics

id Integer Specifies an ID for a singleperformance report.

statistics




limit Integer Specifies the kilobytes per secondthat can be consumed by areplication job on the network.

statistics

timestamp Integer Specifies a timestamp for theperformance report.

statistics

total Integer Specifies the total kilobytes perseconds consumed by the replicationjobs.

statistics

SyncIQ API examplesYou can see examples for some SyncIQ API calls.

Start a replication job

Manually start a replication job on the system.

Request example

POST /platform/1/sync/jobsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'id': 'testpol' }

Response example

201 CreatedContent-type: application/json, Allow: 'GET, POST, HEAD'

{ "id":"testpol" }

Modify a replication job

Pause, cancel, or restart a job.

Request exampleYou can only modify the state object property for a replication job. Options are pause,cancel, and restart.

PUT /platform/1/sync/jobs/testpolAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'state': cancel, }



Response example

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

Create a replication policy

You can create a replication policy on the file system.

Request example

POST /platform/1/sync/policiesAuthorization: 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 examplesIn the following example, the request was successful and a replication policy ID isreturned for the created object.

201 CreatedContent-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 ErrorContent-type: application/json, Allow: 'DELETE, GET, POST, HEAD' { "errors":[ { "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/1/sync/policies/myNewPolicy Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==



{ 'target_compare_initial_sync': True, 'enabled': True, 'description': 'New policy', 'target_host': 'newHostname' }

Response examplesThe 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 wasreturned.

500 Internal Server ErrorContent-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/1/sync/policy/testPolicy/resetAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Response example

201 CreatedContent-type: application/json, Allow: 'POST'

{ "id":"5275f97ebb3892ed4a47f71de20d4609" }

Force rotation for reports

Manually start rotation for the records in the database, which deletes reports that areolder than the specified maximum retention period.

Request example

POST /platform/1/sync/reports-rotateAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==



Response example


{ "id":"a33006f364842eefb629fc6b95c92559" }

Cancel a target replication policy

You can cancel a replication policy from the target cluster.

Request example

POST /platform/1/sync/target/policies/testpol/cancelAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Response example

200 OKContent-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" } ] }

Create a replication policy rule on the system.

You can create a replication policy rule on the file system.

Request example

POST /platform/1/sync/rulesAuthorization: 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


{ "id":"fc-0" }

Modify a replication policy rule.

You can modify replication policy rules on the system.

Request example

PUT /platform/sync/rules/Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Response example

204 No ContentContent-type: text/plain, Allow: 'DELETE, GET, PUT, POST'

Modify SyncIQ settings

You can modify the SyncIQ settings on the system.

Request example

PUT /platform/1/sync/settingsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'report_max_count': 1234, 'service': 'on' }

Response example

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

Deduplication overviewThe SmartDedupe software module enables you to save storage space on your cluster byreducing redundant data. Deduplication maximizes the efficiency of your cluster bydecreasing the amount of storage required to store multiple files with similar blocks.

SmartDedupe deduplicates data by scanning an Isilon cluster for identical data blocks.Each block is 8 KB. If SmartDedupe finds duplicate blocks, SmartDedupe moves a singlecopy of the blocks to a hidden file called a shadow store. SmartDedupe then deletes theduplicate blocks from the original files and replaces the blocks with pointers to theshadow store.


Deduplication overview 179

Deduplication is applied at the directory level, targeting all files and directoriesunderneath one or more root directories. You can first assess a directory fordeduplication and determine the estimated amount of space you can expect to save. Youcan then decide whether to deduplicate the directory. After you begin deduplicating adirectory, you can monitor how much space is saved by deduplication in real time.

SmartDedupe does not deduplicate files that are 32 KB and smaller, because doing sowould consume more cluster resources than the storage savings are worth. Each shadowstore can contain up to 255 blocks. Each block in a shadow store can be referenced32000 times.

Deduplication resourcesYou can retrieve, create, modify, or delete SmartDedupe configurations and settings.

Deduplication summary resource

Applies the standard summary pattern to OneFS SmartDedupe jobs.


Get a summary of deduplication jobs GET /platform/1/dedupe/dedupe-summary

View the detailed JSON schema for this resource GET /platform/1/dedupe/dedupe-summary?describe


Object properties


block_size Integer Specifies the file system block size inbytes.

summary

estimated_physical_blocks Integer Specifies the estimated number ofphysical blocks that arededuplicated.

summary

estimated_saved_blocks Integer Specifies the estimated number ofphysical blocks that are saved bydeduplication.

summary

logical_blocks Integer Specifies the number of logicalblocks that are deduplicated.

summary

saved_logical_blocks Integer Specifies the number of logicalblocks that are saved bydeduplication.

summary

total_blocks Integer Specifies the total number of physicalblocks in the cluster.

summary

used_blocks Integer Specifies the total number of physicalblocks that are holding data in thecluster.

summary



Deduplication settings resource

Applies the standard system object pattern to OneFS deduplication settings.


Get deduplication settings GET /platform/1/dedupe/settings

Modify deduplication settings PUT /platform/1/dedupe/settings

View the detailed JSON schema for this resource GET /platform/1/dedupe/settings?describe


Object properties


assess_paths Array Specifies the path to directories thatare assessed for deduplication.

settings

dedupe_schedule String Specifies a schedule fordeduplication.

settings

paths Array Specifies the paths that arededuplicated.

settings

Deduplication reports resource

Applies the standard collection pattern to SmartDedupe reports.


Get a report for all deduplication jobs GET /platform/1/dedupe/reports

View the detailed JSON schema for this resource GET /platform/1/dedupe/reports?describe

Query parameters

sort=<string>


begin=<integer>

Return only those reports at or after the given time in seconds since UNIX Epoch.

end=<integer>

Return only those reports at or before the given time in seconds since UNIX Epoch.

job_id=<integer>

Return only those jobs with a specific identifier.

job_type=[Dedupe|DedupeAssessment]

Return only those jobs with the specified job type.

dir=[ASC|DESC]



Deduplication overview 181

limit=<integer>


resume=<string>


Object properties



reports

dedupe_percent Boolean Specifies the percentage of scannedblocks that were deduplicated.

reports

elapsed_time Boolean Specifies the amount of time taken tocomplete the job.

reports

id String Specifies a unique identifier for thereport.

reports

job_id String Specifies a unique identifier for thededuplication job in the report.

reports

job_type String Specifies the type of deduplicationjob.

reports

reports Array Specifies a list of entries in the reportfor the deduplication job.

reports

phase Integer Reports the phase of the job. Thisvalue ranges from 1-4.

reports

results String Specifies the results for the report. reports

time Integer Specifies the time that the report wasgenerated in seconds since UNIXEpoch.

reports

Deduplication API examplesYou can see examples for some deduplication API calls.

Modify deduplication settings

You can modify deduplication settings on the cluster.

Request example

PUT /platform/1/dedupe/settingsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'paths': [ '/ifs/data/dedupeme1', '/ifs/data/dedupeme2' ]}



Response example

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

Hadoop overviewHadoop is an open-source platform that runs analytics on large sets of data across adistributed file system.

In a Hadoop implementation on an EMC Isilon cluster, OneFS acts as the distributed filesystem and HDFS is supported as a native protocol. Clients from a Hadoop clusterconnect to the Isilon cluster through the HDFS protocol to manage and process data.

Hadoop support on the cluster requires you to activate an HDFS license. To obtain alicense, contact your EMC Isilon sales representative.

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

HDFS racks resource

Create or retrieve information about HDFS racks.


Get all HDFS racks GET /platform/1/protocols/hdfs/racks

Create an HDFS rack POST /platform/1/protocols/hdfs/racks

Get an HDFS rack GET /platform/1/protocols/hdfs/racks/<rack ID>

Modify an HDFS rack PUT /platform/1/protocols/hdfs/racks/<rack ID>

Delete an HDFS rack DELETE /platform/1/protocols/hdfs/racks/<rack ID>


GET /platform/1/protocols/hdfs/racks?describe


GET /platform/1/protocols/hdfs/racks/<rack ID>?describe


Object properties


total Integer Specifies the number of HDFS rackson the cluster.

N/A


N/A


Hadoop overview 183


client_ip_ranges Array Specifies an array of IP ranges.Clients connections from these IPranges are served by nodes from anarray of corresponding nodes fromthe ip_pools parameter.

racks

id String Specifies the system-provided ID ofthe HDFS rack.

racks

ip_pools Array Specifies an array of IP pool names.Clients connections from the IPranges specified in theclient_ip_ranges parameter are

served from this array.

racks

name String Specifies the system or user providedname of the HDFS rack.

racks

HDFS proxyusers resource

Create, delete, or retrieve information about HDFS proxyusers.


Get all HDFS proxyusers GET /platform/1/protocols/hdfs/proxyusers

Get an HDFS proxyuser GET /platform/1/protocols/hdfs/proxyusers/<NAME>

Create an HDFS proxyuser POST /platform/1/protocols/hdfs/proxyusers/ or

PUT /platform/1/protocols/hdfs/proxyusers/<NAME>

Delete an HDFS proxyuser DELETE /platform/1/protocols/hdfs/proxyusers/<NAME>


GET /platform/1/protocols/hdfs/proxyusers?describe

View detailed JSON schema for thisresource

GET /platform/1/protocols/hdfs/proxyusers/<NAME>?describe

Query parameters

zone=<string>

Specify an access zone for the user. The default value is system.

Object properties


total Integer Specifies the number of proxyusersconfigured.

N/A





N/A

proxyusers Array Specifies the HDFS impersonationinformation of a proxyuser.

N/A

id String Specifies the ID of the proxyuser thatis assigned by the system.

proxyusers

members Array Specifies users or groups that areimpersonated by a proxyuser.

proxyusers

id String Specifies the serialized form of the IDsuch as 'UID:0', 'USER:name', or 'GID:0.

members

name String Specifies the persona name, whichmust be combined with the typeoption.

members

type String Specifies the persona type, whichmust be combined with the nameoption. Values include "user","group", or "wellknown".

members

name String Specifies the name of the proxyuser. proxyusers

HDFS proxyusers name members resource

Add, modify, delete, or retrieve information about HDFS proxyuser members.


Get all members of the HDFSproxyusers

GET /platform/1/protocols/hdfs/proxyusers/<NAME>/members

Add a member to the HDFS proxyuser POST /platform/1/protocols/hdfs/proxyusers/<NAME>/members/ or

PUT /platform/1/protocols/hdfs/proxyusers/<NAME>/members/<MEMBER>

Remove a member from the HDFSproxyuser

DELETE /platform/1/protocols/hdfs/proxyusers/<NAME>/members/<MEMBER>


GET /platform/1/protocols/hdfs/proxyusers/<NAME>/members?describe

Query parameters

zone=<string>

Specify an access zone for the user.


Hadoop overview 185

Object properties



N/A

members Array Specifies properties for proxyusermembers.

N/A

id String Specifies the serialized form of thepersona (such as 'UID:0','USER:name', 'GID:0', 'GROUP:wheel','SID:S-1-1').

members


members


members

HDFS settings resource

Modify or retrieve information about global HDFS settings.


Get the global HDFS settings GET /platform/1/protocols/hdfs/settings

Modify the global HDFS settings PUT /platform/1/protocols/hdfs/settings


GET /platform/1/protocols/hdfs/settings?describe


Object properties


default_block_size Integer Specifies the block size(size=2**value) reported by the HDFSserver.

settings

default_checksum_type String Specifies the checksum type reportedby the HDFS server.

settings

server_log_level String Specifies a log level for the HDFSdaemon.

settings

server_threads Integer Specifies the number of workerthreads dedicated to the HDFSdaemon.

settings



HDFS API examplesYou can see examples for some HDFS API requests.

Create an HDFS rack

You can create an HDFS rack.

Request exampleThe rack name must be preceded by a forward slash (/).

POST /platform/1/protocols/hdfs/racksAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ "name":"/racktest"}

Response example


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

Modify an HDFS rack

You can modify the properties for an HDFS rack.

Request exampleThe rack name must be preceded by a forward slash (/). In the URL, you must replace theforward slash with the escape character %2F.

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

Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ "name":"/rack2test"}



Modify global HDFS settings

You can modify the properties for global HDFS settings.

Request example

PUT /platform/1/protocols/hdfs/settings/Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ "default_checksum_type":"crc32"}


Hadoop overview 187



Create HDFS proxyusers

Create an HDFS proxyuser.

Request example

POST /platform/1/protocols/hdfs/proxyusersAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"proxy_user_test"}

Response example


You can also create an HDFS proxyuser through the PUT method.

Request example

PUT /platform/1/protocols/hdfs/proxyusers/proxy_user_testAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{}

Response example


Create HDFS proxyuser member

Create an HDFS proxyuser member.

Request example

POST /platform/1/protocols/hdfs/proxyusers/proxy_user_test/membersAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"proxy_user_member_test"}

Response example


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

Request example

PUT /platform/1/protocols/hdfs/proxyusers/proxy_user_test/members/USER:proxy_user_member_testAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{}



Response example


File poolsFile pools are sets of files that you define to apply policy-based control of the storagecharacteristics of your data.

The initial installation of OneFS places all files in the cluster into a single file pool, whichis subject to the default file pool policy. SmartPools enables you to define additional filepools, 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 lastaccess or a combination of these and other factors), and define specific storageoperations for files that match them. The following examples demonstrate a few ways youcan configure file pool policies:

l You can create a file pool policy for a specific file extension that requires highavailability.

l You can configure a file pool policy to store that type of data in a storage pool thatprovides the fastest reads or read/writes.

l You can create another file pool policy to evaluate last accessed date, allowing you tostore older files in storage pool best suited for archiving for historical or regulatorypurposes.

File pool resourcesYou can retrieve, create, modify, or delete file pool configurations and settings.

File pool default policy resource

Modify or retrieve information about the default OneFS file pool policy.


Get information about the default file pool policy GET /platform/1/filepool/default-policy

Modify the default file pool policy PUT /platform/1/filepool/default-policy

View the detailed JSON schema for this resource GET /platform/1/filepool/default-policy?describe


Object properties


default-policy Object Specifies the default file pool policy. N/A

actions Array Specifies a list of actions that will betaken on matching files.

default-policy

action_param Object Specifies parameters for the actionthat vary by the definedaction_type. This parameter can

actions


File pools 189


be set as a string, Boolean, object, ornull.

action_type String Specifies the type of action. Optionsareset_requested_protection,

set_data_access_pattern,

enable_coalescer,

apply_data_storage_policy,

set_cloudpool_policy.

actions

File pool policies resource

Create or retrieve information about OneFS file pool policies.


Get information about all file pool policies GET /platform/1/filepool/policies

Get information about a file pool policy GET /platform/1/filepool/policies/<policyname>

Create a file pool policy POST /platform/1/filepool/policies

Modify a file pool policy PUT /platform/1/filepool/policies/<policyname>

Delete a file pool policy DELETE /platform/1/filepool/policies/<policyname>

View the detailed JSON schema for this resource GET /platform/1/filepool/policies?describe

View the detailed JSON schema for this resource GET /platform/1/filepool/policies/<policyname>?describe


Object properties


total Integer Specifies the number of file poolpolicies on the cluster.

N/A


N/A

policies Object Specifies a file pool policy. N/A


policies



actions






enable_coalescer,



actions

apply_order Integer Specifies the order in which thispolicy is applied.

actions

birth_cluster_id String Specifies the GUID that is assigned tothe cluster where the file pool policywas created.

actions

description String Specifies a description for the filepool policy.

actions

file_matching_pattern Object Specifies the file matching rules forthe file pool policy.

actions

or_criteria Object Specifies the criteria for the oroperator.


and_criteria Object Specifies the criteria for the andoperator.

or_criteria

attribute_exists Boolean Specifies whether an attributeindicates a match. Only applies whenthe type parameter is set to

custom_attribute.

and_critieria

begins_with Boolean Determines if files are matchedrecursively under the given path. Onlyapplies when the type parameter is

set to path.

and_criteria

case_sensitive Boolean Determines whether to apply case-sensitivity when comparing fileattributes. Only applies when thetype parameter is set to either nameor path.

and_criteria

field String Specifies a file attribute field namefor comparison when the typeparameter is set tocustom_attribute.

and_criteria

operator String Specifies the comparison operator tocompare an attribute against a value.Comparison operators are "==", "!=",">", ">=", "<", "<=", and "!".

and_criteria

type String Specifies the file attribute that iscompared against a given value, suchas name, path, link_count,

accessed_time, birth_time,

and_criteria


File pools 191


changed_time,

metadata_changed_time, size,

file_type, and

custom_attribute.

units String Specifies the unit of size, such as B,KB, MB, GB, TB, PB, or EB. Onlyapplies when the type parameter isset to size.

and_criteria

use_relative_time Boolean Determines whether time units referto a calendar date and time (such asJun 2, 2009) or a period of time (suchas 2 weeks). Only applies when thetype parameter is set to


changed_time, or

metadata_changed_time.

and_criteria


Specifies the value that is comparedagainst a file attribute.

and_criteria

id Integer Specifies the system assigned ID forthe file pool policy.

actions

name String Specifies the system or user assignedname for the file pool policy.

actions

File pool templates resource

Retrieve information about OneFS file pool policy templates.


Get information about file pool policy templatea GET /platform/1/filepool/templates

Get information about a file pool policy template GET /platform/1/filepool/templates/<name>

View the detailed JSON schema for this resource GET /platform/1/filepool/templates?describe

View the detailed JSON schema for this resource GET /platform/1/filepool/templates/<name>?describe


Object properties


total Integer Specifies the number of file pooltemplates on the cluster.

N/A


N/A

templates Object Specifies a file pool policy template. N/A





templates



actions



enable_coalescer,



actions

apply_order Integer Specifies the order in which thispolicy is applied.

actions

birth_cluster_id String Specifies the GUID that is assigned tothe cluster where the file pool policywas created.

actions

description String Specifies a description for the filepool policy.

actions

file_matching_pattern Object Specifies the file matching rules forthe file pool policy.

actions

or_criteria Object Specifies the criteria for the oroperator.


and_criteria Object Specifies the criteria for the andoperator.

or_criteria

attribute_exists Boolean Specifies whether an attributeindicates a match. Only applies whenthe type parameter is set to

custom_attribute.

and_critieria

begins_with Boolean Determines if files are matchedrecursively under the given path. Onlyapplies when the type parameter is

set to path.

and_criteria

case_sensitive Boolean Determines whether to apply case-sensitivity when comparing fileattributes. Only applies when thetype parameter is set to either nameor path.

and_criteria

field String Specifies a file attribute field namefor comparison when the typeparameter is set tocustom_attribute.

and_criteria


File pools 193


operator String Specifies the comparison operator tocompare an attribute against a value.Comparison operators are "==", "!=",">", ">=", "<", "<=", and "!".

and_criteria

type String Specifies the file attribute that iscompared against a given value, suchas name, path, link_count,


changed_time,

metadata_changed_time, size,

file_type, and

custom_attribute.

and_criteria

units String Specifies the unit of size, such as B,KB, MB, GB, TB, PB, or EB. Onlyapplies when the type parameter isset to size.

and_criteria

use_relative_time Boolean Determines whether time units referto a calendar date and time (such asJun 2, 2009) or a period of time (suchas 2 weeks). Only applies when thetype parameter is set to


changed_time, or

metadata_changed_time.

and_criteria


Specifies the value that is comparedagainst a file attribute.

and_criteria

id Integer Specifies the system assigned ID forthe file pool policy.

actions

name String Specifies the system or user assignedname for the file pool policy.

actions

File pools API examplesYou 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/1/filepool/policies Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{'file_matching_pattern': {'or_criteria': [ {'and_criteria': [ {'operator': '==', 'type': 'path', 'value': '/ifs/



data/vms'} ] } ] }, '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 exampleIn the following example, "vms_mirror" is the ID of the file pool policy.

PUT /platform/1/filepool/policies/vms_mirror Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ "action_param":"false" "action_type":"set_requested_protection" }



Modify the default file pool policy

You can modify the default file pool policy.

Request example

PUT /platform/1/filepool/policies/ Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ "action_param":"random" "action_type":"set_data_access_pattern" }


File pools 195



SmartLock overviewYou can prevent users from modifying and deleting files on an EMC Isilon cluster with theSmartLock software module. You must activate a SmartLock license on a cluster toprotect data with SmartLock.

With the SmartLock software module, you can create SmartLock directories and commitfiles within those directories to a write once read many (WORM) state. You cannot eraseor re-write a file committed to a WORM state. 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 toa WORM state, even after it is removed from a WORM state.

SmartLock resourcesYou can retrieve, create, or modify SmartLock configurations and settings.

SmartLock domains resource

Create or retrieve information about a SmartLock domain.


Get all SmartLock domains GET /platform/1/worm/domains

Get a SmartLock domain GET /platform/1/worm/domains/<domain>

Create a SmartLock domain POST /platform/1/worm/domains

Modify a SmartLock domain PUT /platform/1/worm/domains/<domain>


GET /platform/1/worm/domains?describe


GET /platform/1/worm/domains?describe

Query parameters

sort=<string>


dir=[ASC|DESC]


limit=<integer>


resume=<string>



Continue returning results from previous request (cannot be combined with otherparameters).

Object properties


total Integer Specifies the number of SmartLockdomains on the cluster.

N/A


N/A

autocommit_offset Integer Specifies the autocommit time periodfor the domain, in seconds. After afile is in the domain without beingmodified for the specified timeperiod, the file is automaticallycommitted. If this parameter is set tonull, there is no autocommit time,and files must be committedmanually.

domains

default_retention Integer Specifies the default amount of time,in seconds, that a file in this domainwill be protected. The defaultretention period is applied if noretention date is manually set on thefile. This parameter can also be set toforever, use_min (which applies

the min_retention option), or

use_max (which applies the

max_retention option).

domains

id Integer Specifies the system-assigned ID forthis protection domain.

domains

incomplete Boolean If true, indicates that OneFS is stillcreating the domain and is unable toprevent files from being modified ordeleted. If false, indicates that thedomain is fully created and is able toprevent files from being modified ordeleted.

domains

lin Integer Specifies the logical inode number(LIN) for the root of this domain.

domains

max_modifies Integer Specifies the maximum number oftimes a SmartLock domain can bemodified.

domains

max_retention Integer Specifies the maximum amount oftime, in seconds, that a file in thisdomain will be protected. This settingwill override the retention period ofany file committed with a longerretention period. If this parameter isset to null, an infinite length retentionperiod is set.

domains


SmartLock overview 197


min_retention Integer Specifies the minimum amount oftime, in seconds, that a file in thisdomain will be protected. This settingwill override the retention period ofany file committed with a shorterretention period. If this parameter isset to null, this minimum value is notenforced. This parameter can also beset to forever.

domains

override_date Integer Specifies the override retention datefor the domain. If this date is laterthan the retention date for anycommitted file, the file will remainprotected until the override retentiondate.

domains

path String Specifies the root path of thisdomain. Files in this directory and allsubdirectories will be protected.

domains

privileged_delete String When the on option is selected, files

in this domain can be deletedthrough the privileged delete feature.If the disabled option is selected,

privileged file deletes arepermanently disabled and cannot beturned on.

domains

total_modifies Integer Specifies the number of times thisdomain has been modified and thenumber of times the attributes for thedomain have changed. A SmartLockdomain can be modified a fixednumber of times as defined by themax_modifies parameter.

domains

type String Specifies whether the domain is anenterprise domain or a compliancedomain. Compliance domains can notbe created on enterprise clusters.Enterprise and compliance domainscan be created on complianceclusters.

domains

SmartLock settings resource

Modify or retrieve information about SmartLock global settings.


Get SmartLock global settings GET /platform/1/worm/settings

Modify SmartLock global settings PUT /platform/1/worm/settings





GET /platform/1/worm/settings?describe


Object properties


cdate Object Specifies the current time of theSmartLock compliance clock in UnixEpoch seconds. If the complianceclock is not set, this value is null. APUT request will set the complianceclock date to the current system time.The cluster must be in compliancemode to set the compliance clock.

settings

SmartLock API examplesYou can see examples for some SmartLock API requests.

Create a SmartLock

You can create a SmartLock domain.

Request example

POST /platform/1/worm/domains Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ "path":"/ifs/test/domain_test" }

Response example


{"id" : "224731515-4837484-928237-1003"}

Modify a SmartLock

You can modify a SmartLock domain.

Request example

PUT /platform/1/worm/domains/domaintest Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"privileged_delete":"on"}


SmartLock overview 199



Modify SmartLock settings

You can modify SmartLock settings.

Request exampleIn this example, you can set the compliance clock to the current system time by sending aPUT request to this resource with an empty JSON object {} for the cdate value. This clustermust be in compliance mode to set the compliance clock.

PUT /platform/1/worm/domains/settingsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"cdate" : }



Storage pools overviewOneFS organizes different node types into separate node pools, and you can furtherorganize these node pools into logical tiers of storage. By activating a SmartPoolslicense, you can create file pool policies that store files in these tiers automatically,based on file matching criteria that you specify.

Without an active SmartPools license, OneFS manages all node pools as a single pool ofstorage and stores file data and metadata across the entire cluster, ensuring that data isprotected, secure, and readily accessible. All files belong to the default file pool and aregoverned by the default file pool policy. In this mode, OneFS provides a number offunctions that you can deploy, such as autoprovisioning, compatibilities, virtual hotspare, SSD strategies, global namespace acceleration (GNA), L3 cache, and storage tiers.

When you activate a SmartPools license, you can take further control of your data set tooptimize the performance of your cluster. Additional functions become available,including custom file pool policies that take precedence over the default policy, andspillover management.

The following table summarizes storage pool functions based on whether a SmartPoolslicense is inactive or active.

Function Without activeSmartPools license

With active SmartPoolslicense

Automatic storage pool provisioning Yes Yes

Compatibilities (node equivalence) Yes Yes

Virtual hot spare Yes Yes

SSD strategies Yes Yes

L3 cache Yes Yes

Tiers Yes Yes



Function Without activeSmartPools license

With active SmartPoolslicense

GNA Yes Yes

File pool policies No Yes

Spillover management No Yes

Storage pools resourcesYou can retrieve, create, modify, or delete system storage pool settings andconfigurations.

Storage pool settings resource

Modify or retrieve information about OneFS storage pools.


Get storage pool settings GET /platform/1/storagepool/settings

Modify storage pool settings PUT /platform/1/storagepool/settings


GET /platform/1/storagepool/settings?describe


Object properties


automatically_manage_io_optimization

String Automatically manages the I/Ooptimization settings on files.Operations are optimized by storingsingle copies of each file's metadataon SSD and reducing the latency ofmetadata read operations.Options are: all,

files_at_default, and none.

When the option forfiles_at_default is specified,

files that do not have a manuallymanaged flag set will have their I/Ooptimization settings set by theSmartPools job.

settings

automatically_manage_protection

String Automatically manages the protectionsettings on files. Options are: all,

files_at_default, and none.

settings

global_namespace_acceleration_enabled

Boolean Determines if metadata is stored onsolid state drives. Enabling thisoption optimizes namespaceoperations.

settings


Storage pools overview 201


global_namespace_acceleration_state

String Specifies whether namespaceoperation optimizations are currentlyin effect. Read-only values are:honored or inactive.

settings

protect_directories_one_level_higher

Boolean Determines if an additional protectionlevel is added automatically to alldirectories.

settings

spillover_enabled Boolean Determines if data is written intoother pools when the specifiedstorage target is not writeable.

settings

spillover_target Object Specifies a target pool for data whenthe specified storage target is notwriteable.

settings

id Integer Specifies the target pool ID if a targetis specified. Otherwise, this value canbe set to null.

spillover_target

name String Specifies the target pool name if atarget is specified. Otherwise, thisvalue can be set to null.

spillover_target

type String Specifies the type of target pool.Options are tier, nodepool,

anywhere, and invalid.

spillover_target

virtual_hot_spare_deny_writes

Boolean Determines if writes are denied inreserved virtual hot spare space.

settings

virtual_hot_spare_hide_spare

Boolean Determines if reserved virtual hotspare space is hidden from free spacecounts.

settings

virtual_hot_spare_limit_drives

Integer Specifies the number of drives toreserve for the virtual hot spare. Thisvalue can be 0-4.

settings

virtual_hot_spare_limit_percent

Integer Specifies the percent space to reservefor the virtual hot spare. This valuecan be 0-20.

settings

Storage pools tiers resource

Applies the standard collection pattern to OneFS tiers.


Get a list of all tiers GET /platform/1/storagepool/tiers

Get a single tier GET /platform/1/storagepool/tiers/<name or id>

Create a new tier POST /platform/1/storagepool/tiers

Delete all tiers DELETE /platform/1/storagepool/tiers

Delete a single tier DELETE /platform/1/storagepool/tiers/<name or id>





GET /platform/1/storagepool/tiers?describe


Object properties


total Integer Specifies the total number of tiers. N/A

id Integer Specifies the system ID given to thetier.

tiers

lnns Array Specifies the nodes that are part ofthis tier.

tiers

name String Specifies the name of the tier. tiers

usage Object Reports the total tier usage. tiers

avail_bytes Integer Reports the number of available freebytes that are in the tier when avirtual hot spare is taken intoaccount.

usage

avail_ssd_bytes Integer Reports the number of available freebytes that are in the tier and on SSDdrives when a virtual hot spare istaken into account.

usage

balanced Boolean Reports if the pool usage is currentlybalanced.

usage

free_bytes Integer Reports the number of free bytes thatare in the pool.

usage

free_ssd_bytes Integer Reports the number of free bytes thatare in the pool and on SSD drives.

usage

total_bytes Integer Reports the number of total bytes ofdata in the pool.

usage

total_ssd_bytes Integer Reports the number of total bytes ofdata in the pool and on SSD drives.

usage

virtual_hot_spare_bytes Integer Reports the number of bytes reservedfor a virtual hot spare in the pool.

usage

Storage pools node pools resource

Applies the standard collection pattern to OneFS node pools.


Get information for all node pools GET /platform/1/storagepool/nodepools

Get information for a single node pool GET /platform/1/storagepool/nodepools/<name orid>




Create a new node pool POST /platform/1/storagepool/nodepools

Modify a node pool PUT /platform/1/storagepool/nodepools/<name orid>

Delete a manually managed node pool DELETE /platform/1/storagepool/nodepools/<name or id>


GET /platform/1/storagepool/nodepools?describe


Object properties


total Integer Specifies the total number of nodepools.

N/A

id Integer Specifies the system ID given to thenode pool.

nodepools

lnns Array Specifies the nodes that are part ofthis node pool, by Logical NodeNumber (LNN).

nodepools

manual Boolean Determines if the node pool ismanaged manually by the user orautomatically by the system.

nodepools

name String Specifies the name of the node pool. nodepools

protection_policy String Specifies the underlying protectionpolicy.

nodepools

tier String Specifies the name or system ID ofthe tier that the node pool is in. If thenode pool is not in a tier, this value isnull.

nodepools

usage Object Reports the total pool usage. nodepools

avail_bytes Integer Reports the number of available freebytes that are in the pool when avirtual hot spare is taken intoaccount.

usage

avail_ssd_bytes Integer Reports the number of available freebytes that are in the pool and on SSDdrives when a virtual hot spare istaken into account.

usage


usage


usage





usage


usage


usage


usage

Storage pools resource

Applies the standard collection pattern to OneFS storage pools. You can supply atoplevels argument to filter out node pools within tiers.


Get information for all storage pools GET /platform/1/storagepool/storagepools


GET /platform/1/storagepool/storagepools?describe


Object properties


total Integer Specifies the total number of storagepools.

N/A

id Integer Specifies the system ID given to thestorage pool.

storagepools

lnns Array Specifies the nodes that are part ofthis storage pool, by Logical NodeNumber (LNN).

storagepools

manual Boolean Determines if the node pool ismanaged manually by the user orautomatically by the system.

storagepools

name String Specifies the name of the storagepool.

storagepools

protection_policy String Specifies the underlying protectionpolicy.

storagepools

type String Specifies the pool type. Options aretier or nodepool.

storagepools

tier String Specifies the name or system ID ofthe tier that the node pool is in. If thenode pool is not in a tier, this value isnull.

storagepools




usage Object Reports the total pool usage. storagepools

avail_bytes Integer Reports the number of available freebytes that are in the pool when avirtual hot spare is taken intoaccount.

usage

avail_ssd_bytes Integer Reports the number of available freebytes that are in the pool and on SSDdrives when a virtual hot spare istaken into account.

usage


usage


usage


usage


usage


usage


usage

Storage pools suggested protection resource

Retrieve information about the suggested protection policy for a storage pool.


Get information about the suggestedprotection policy

GET /platform/1/storagepool/suggested_protection/<NID>


GET /platform/1/storagepool/suggested_protection/<NID>?describe


Object properties


suggested_protection String Specifies the suggested protectionpolicy.

suggested_protection



Storage pool status resource

Retrieves the heath status of the overall OneFS pool system.


Get the status of the OneFS pool system GET /platform/1/storagepool/status

View the detailed JSON schema for this resource GET /platform/1/storagepool/status?describe


Object properties


affected Object Identifies unhealthy nodes and drives. unhealthy

device Object Specifies the logical node number or drive identifier. affected

bay Integer Specifies the drive bay number. device

lnn Integer Specifies the node the drive is on. device

down Boolean Determines if the device is currently down. affected

restriping Boolean Determines if the device is currently being repaired. affected

smartfailed Boolean Determines if the device is currently smartfailed. affected

type String Specifies the type of device that is affected. affected

drives Array Identifies the drives that are part of the disk pool. diskpool

bay Integer Specifies the drive bay number. drives

lnn Integer Specifies the node the drive is on, by Logical NodeNumber (LNN).

drives

id Integer Specifies the system ID given to the disk pool. diskpool

name String Specifies the disk pool name. diskpool

nodepool_id Integer Specifies the system ID of the node pool for the diskpool. If the disk pool is not in a node pool, this valueis null.

diskpool

protection_policy String Specifies the protection policy for the disk pool. diskpool

ssd_drives Array Specifies the SSDs that are part of the disk pool. diskpool

bay Integer Specifies the drive bay number. ssd_drives

lnn Integer Specifies the node the drive is on. ssd_drives

health_flags Array Specifies the health status for the disk pool. Optionsinclude: underprovisioned, missing_drives,

devices_down, devices_smartfailed, and

waiting_repair.

diskpool

unprovisioned Array Identifies drives that are currently not provisioned intoa disk pool.

unhealthy

bay Integer Specifies the drive bay number. drives




lnn Integer Specifies the node the drive is on. drives

Storage pools API examplesYou can see examples for some storage pools API calls.

Modify storage pool settings

You can modify the global storage pool settings on the system.

Request exampleYou must specify at least one property in the request.

PUT /platform/1/storagepool/settingsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'global_namespace_acceleration_enabled': false, 'automatically_manage_protection': 'all' }


204 NO CONTENTContent-type: text/plain, Allow: 'GET, PUT, HEAD'

Create a tier

Create a tier on the system.

Request example

POST /platform/1/storagepool/tiersAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'name': 'myTier' }

Response example

201 CREATEDContent-type: application/json, Allow: 'GET, POST, HEAD, DELETE'

{ "id":"myTier" }



Modify a tier

Modify a tier.

Request exampleWhen you modify a set of nodes that belong to a tier, you must also set the tierproperty on that node pool through the /platform/1/storagepool/nodepools URI.

PUT /platform/1/storagepool/tiers/myTierAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ "name": myTier }

PUT /platform/1/storagepool/nodepoolsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ "tier": myTier }


204 NO CONTENTContent-type: application/json, Allow: 'GET, POST, PUT, DELETE'

Create a node pool

Create and manually manage a node pool.

Request exampleYou must specify a minimum of three lnns. After these nodes are added to the newlycreated node pool and removed from their current node pool, the number of nodes in theoriginal node pool must either be 0 or greater than 2.

POST /platform/1/storagepool/nodepoolsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'name': 'myPool', 'lnns': [2, 3, 1] }

Response example

201 CREATEDContent-type: application/json, Allow: 'GET, POST, HEAD, DELETE' { "id":"myPool" }

Modify a node pool

You can modify a node pool on the system.

Request exampleYou must specify at least one property in the body. Additionally, you can only specify lnnsfor manually managed node pools and you must specify a minimum of three lnns when



modifying a manually managed node pool. If nodes are moved to a new node pool andremoved from their current node pool, the number of nodes in the original node poolmust either be 0 or greater than 2.

PUT /platform/1/storagepool/nodepools/myPoolAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ 'tier': 'myTier', 'name': 'myNewPoolName' }


204 No ContentContent-type: application/json, Allow: 'GET, POST, PUT, DELETE'

SmartQuotas overviewThe SmartQuotas module is an optional quota-management tool that monitors andenforces administrator-defined storage limits. Using accounting and enforcement quotalimits, reporting capabilities, and automated notifications, SmartQuotas managesstorage use, monitors disk storage, and issues alerts when disk-storage limits areexceeded.

Quotas help you manage storage usage according to criteria that you define. Quotas areused as a method of tracking—and sometimes limiting—the amount of storage that auser, group, or project consumes. Quotas are a useful way of ensuring that a user ordepartment does not infringe on the storage that is allocated to other users ordepartments. In some quota implementations, writes beyond the defined space aredenied, and in other cases, a simple notification is sent.

The SmartQuotas module requires a separate license. For additional information aboutthe SmartQuotas module or to activate the module, contact your EMC Isilon salesrepresentative.

Quotas resourcesYou can retrieve, create, modify, or delete SmartQuotas configurations and settings.

Quota license resource

Retrieves license information for the SmartQuotas feature.


Get license information for SmartQuotas GET /platform/1/quota/license

View the detailed JSON schema for this resource GET /platform/1/quota/license?describe




Object properties


duration Integer Specifies the total duration inseconds for temporary licenses.

N/A

expiration Integer Specifies the UNIX Epoch time whenthe license expires.

N/A

status Array Specifies the current status of thelicense. Possible states are:activated, evaluation,

expired, inactive, and

unknown.

N/A

name String Specifies the name of the licensedfeature.

N/A

Quota summary resource

Applies the standard collection summary pattern to OneFS quotas.


Get summary information about quotas GET /platform/1/quota/quotas-summary

View detailed JSON schema for this resource GET /platform/1/quota/quotas-summary?describe


Object properties


count Integer Specifies the total number of quotas. summary

default_group_quotas_count

Integer Specifies the total number of default-group quotas.

summary

default_user_quotas_count Integer Specifies the total number of default-user quotas.

summary

directory_quotas_count Integer Specifies the total number ofdirectory quotas.

summary

group_quotas_count Integer Specifies the total number of groupquotas.

summary

linked_quotas_count Integer Specifies the total number of userand group totals that are linked.

summary

user_quotas_count Integer Specifies the total number of userquotas.

summary


SmartQuotas overview 211

Quota quotas notification rules resource

Applies the standard collection pattern to the notification rules for a quota.


Get all notification rules for aquota

GET /platform/1/quota/quotas/<quota-id>/notifications

Get a notification rule for aquota

GET /platform/1/quota/quotas/<quota-id>/notifications/<notification-id>

Create notification rules for aquota

POST /platform/1/quota/quotas/<quota-id>/notifications

Create empty overridenotification rules for a quota

PUT /platform/1/quota/quotas/<quota-id>/notifications

Modify notification rules for aquota

PUT /platform/1/quota/quotas/<quota-id>/notifications/<notification-id>

Delete all notification rules for aquota

DELETE /platform/1/quota/quotas/<quota-id>/notifications

Delete notification rules for aquota

DELETE /platform/1/quota/quotas/<quota-id>/notifications/<notification-id>

View detailed JSON schema forquota notification rules

GET /platform/1/quota/quotas/<quota-id>/notifications?describe

View detailed JSON schema fora single quota notification ruleobject

GET /platform/1/quota/quotas/<quota-id>/notifications/<notification-id>?describe


Object properties


id String Specifies the system ID given to therule. In a POST request, this is the IDof the created item that refers to theitem in the collection item resourcepath.

notifications

action_alert String Sends an alert when the rulematches.

notifications

action_email_address String Sends an email to a specific addresswhen the rule matches.

notifications

action_email_owner String Sends an email to the quota domainowner when the rule matches.

notifications

email_template String Specifies the path of theoptional /ifs template file used for

email.

notifications




condition Array Specifies the condition that mustoccur on the quota to triggernotification actions. Options include:exceeded, denied, violated,

expired.

notifications

holdoff Integer Specifies the time to wait betweendetections for rules that are triggeredby user actions.

notifications

Quotas resource

Applies the standard collection pattern to file system quotas.


Get all quotas GET /platform/1/quota/quotas

Get one quota GET /platform/1/quota/quotas/<quota-id>

Create a quota POST /platform/1/quota/quotas

Modify a quota PUT /platform/1/quota/quotas/<quota-id>

Delete all quotas DELETE /platform/1/quota/quotas

Delete a quota DELETE /platform/1/quota/quotas/<quota-id>

View the detailed JSON schema forall quotas

GET /platform/1/quota/quotas?describe

View the detailed JSON schema for asingle quota

GET /platform/1/quota/quotas/<quota-id>?describe

Query Parameters

path=<string>

Only applies to quotas matching this path (see recurse_path_*).

type=[directory|user|group|default-user|default-group]

Only applies to quotas matching this type.

persona=<string>

Only applies to user or group quotas that match this persona. This parameter must beused with the corresponding type argument).

include_snapshots=<Boolean>

Only applies to quotas with the setting for include_snapshots.

enforced=<Boolean>

Only applies to quotas with this enforcement (non-accounting).

exceeded=<Boolean>

Only list quotas which have exceeded one or more of their thresholds.

recurse_path_parents=<Boolean>



If used with the path argument, this parameter applies to all quotas at that path or atany parent directory.

recurse_path_children=<Boolean>

If used with the path argument, this parameter applies to all quotas at that path or atany descendent subdirectory.

report_id=<string>

Uses the named report as a source rather than the live quotas. See the quota reportsresource for a list of valid reports.

zone=<string>

An optionally named zone for user and group resolution.


If true, resolves group and user names in personas.

resume=<string>

Continue returning results from a previous request (cannot be used with otherparameters).

Object Properties and Structure


total Integer Specifies the total number of quotasavailable.

N/A

resume Integer Specifies the value for the resumeargument to be used for continuationrequests.

N/A

container Boolean Enables the SMB shares using thequota directory to see the quotathreshold as the share size.

N/A

id String Specifies the system ID given to thequota. In a POST request, this is theID of the created item that refers tothe item in the collection itemresource path.

quotas

enforced Boolean True if the quota providesenforcement, otherwise anaccounting quota.

quotas

force String Forces the creation of quotas on theroot of /ifs.

quotas

include_snapshots Boolean True if the quota governs snapshotdata as well as head data.

quotas

linked Boolean True if the quota for a user or group islinked and controlled by a parentdefault-* quota. Linked quotascannot be modified until they areunlinked.

quotas

notifications Array Specifies a summary of notifications:custom indicates that one or morenotification rules are available fromthe notifications sub-resource;

quotas




default indicates that the systemdefault rules are used; disabledindicates that no notifications areused for this quota.

path String The /ifs path governed. quotas

ready Boolean True if the accounting is accurate onthe quota. If false, this quota iswaiting on the completion of aQuotaScan job.

quotas

thresholds_include_overhead

Boolean True if thresholds apply to the dataplus file system overhead that isrequired to store the data (such asphysical usage).

quotas

type Array Specifies the type of quota. quotas


persona

name String Specifies the persona name, whichmust be combined with a type.

persona

type String Specifies the type of persona, whichmust be combined with a name.

persona

inodes Integer Specifies the number of inodes (filesystem entities) used by governeddata.

usage

logical Integer Specifies the apparent bytes used bygoverned data.

usage

physical Integer Specifies the bytes used for governeddata and file system overhead.

usage

advisory Integer Specifies the usage bytes at whichnotifications are sent but writes arenot denied.

threshold

advisory_exceeded Boolean True if the advisory threshold was hit. threshold

hard Integer Specifies the usage bytes at whichfurther writes are denied.

threshold

hard_exceeded Boolean True if the hard threshold was hit. threshold

soft Integer Specifies the usage bytes at whichnotifications are sent and soft gracetime is started.

threshold

soft_exceeded Boolean True if the soft threshold was hit. threshold

soft_grace Integer Specifies the time in seconds afterwhich the soft threshold is hit andbefore writes are denied

threshold



Quota reports resource

Applies the standard collection pattern to quota reports.


Get all quota reports GET /platform/quota/reports

Get a quota report GET /platform/quota/reports/<report-id>?contents

Create a quota report POST /platform/quota/reports/<report-id>?contents

Delete a quota report DELETE /platform/quota/reports/<report-id>

View detailed JSON schema aboutquota reports.

GET /platform/quota/reports?describe

View detailed JSON schema about asingle quota reports object.

GET /platform/quota/reports/<report-id>?describe

Query parameters

type=[summary|detail|all]

Only applies to reports matching this type.

generated=[manual|scheduled|all]

Applies to reports that match the source type (scheduled, manual, or all).

dir=[ASC|DESC]


limit=<integer>


resume=<string>


Object properties



N/A


N/A

id String Specifies the system ID given to thereport. In a POST request, this valueis the ID that refers to the createditem in the collection item resourcepath.

reports




generated String Indicates whether the report wasgenerated manually (live) orscheduled.

reports

type String Indicates whether the report is asummary report or detail report.

reports

time Integer Specifies the UNIX Epoch time thatthe report was generated.

reports

Quota about reports resource

Applies the standard system object pattern to return metadata for individual quotareports.


Get metadata about a report GET /platform/1/quota/reports/<report-id>/about


GET /platform/1/quota/reports/<report-id>/about?describe


Object properties


id String Provides the system ID given to thereport. In a POST request, this is theID of the created item that refers tothe item in the collection itemresource path.

reports

generated String Indicates whether the report wasgenerated manually (live) or by aschedule.

reports

type String Indicates whether the report is asummary report or detail report.

reports

time Integer Provides the UNIX Epoch time thereport was taken.

reports

Quota report settings resource

Applies the standard system object pattern to quota report settings.


Get quota report settings GET /platform/1/quota/settings/reports




Modify quota report settings PUT /platform/1/quota/settings/reports


GET /platform/1/quota/settings/reports?describe


Object properties


id String Specifies the system ID given to therule. In a POST request, this is the IDof the created item that is used torefer to the item in the collection itemresource path.

settings

live_dir String Specifies the directory on /ifswhere manual or live reports areplaced.

settings

live_retain Integer Specifies the number of manualreports to keep.

settings

schedule String Specifies the isidate schedule

used to generate reports.

settings

scheduled_dir String Specifies the directory on /ifswhere schedule reports are placed.

settings

scheduled_retain Integer Specifies the number of scheduledreports to keep.

settings

schedule String Specifies the schedule for repeatednotification rules.

settings

threshold Integer Specifies the detected quotathreshold.

settings

Quota default notifications rules resource

Applies the standard collection pattern to default quota notification rules.


Get default global notification rules GET /platform/1/quota/settings/notificationsor GET /platform/1/quota/quotas/<quota-id>/notifications

Get a default global notification rule GET /platform/1/quota/settings/notifications/<notification-id>




or GET /platform/1/quota/quotas/<quota-id>/notifications

Create a default global notificationrule

POST /platform/1/quota/settings/notifications/<notification-id>or POST /platform/1/quota/quotas/<quota-id>/notifications/<notification-id>

Modify a default global notificationrule

PUT /platform/1/quota/settings/notifications/<notification-id>or PUT /platform/1/quota/quotas/<quota-id>/notifications/<notification-id>

Delete default global notificationrules

DELETE /platform/1/quota/settings/notificationsor DELETE /platform/1/quota/quotas/<quota-id>/notifications

Delete a default global notificationrule

DELETE /platform/1/quota/settings/notifications/<notification-id>or DELETE /platform/1/quota/quotas/<quota-id>/notifications/<notification-id>

View the detailed JSON schemaabout global notification rules

GET /platform/1/quota/settings/notifications?describe

View the detailed JSON schemaabout a global notification rule

GET /platform/1/quota/settings/notifications/<notification-id>?describe


Object properties


id String Specifies the system ID given to therule. In a POST request, this is the IDof the created item that refers to theitem in the collection item resourcepath.

notifications

action_alert String Sends an alert when the rulematches.

notifications

action_email_address String Sends an email to a specific addresswhen the rule matches.

notifications

action_email_owner String Sends an email to the quota domainowner when the rule matches.

notifications

email_template String Specifies the path of theoptional /ifs template file used for

email.

notifications




condition Array Specifies the condition that mustoccur on the quota to triggernotification actions. Options consistof: exceeded, denied, violated,

and expired.

notifications

holdoff Integer Specifies the time to wait betweendetections for rules triggered by useractions.

notifications

schedule String Specifies the schedule for repeatednotification rules.

notifications

threshold Integer Specifies the detected quotathreshold.

notifications

Quota mappings settings resource

Applies the standard collection pattern to quota notification email mapping rules.


Get quota email mapping settings GET /platform/1/quota/settings/mappings

Create quota email mapping settings POST /platform/1/quota/settings/mappings/<domain>

Modify quota email mapping setting PUT /platform/1/quota/settings/mappings/<domain>

Delete all quota email mapping settings DELETE /platform/1/quota/settings/mappings

Delete a quota email mapping setting DELETE /platform/1/quota/settings/mappings/<domain>

View the detailed JSON schema forquota email mapping settings

GET /platform/1/quota/settings/mappings?describe

View the detailed JSON schema for aquota email mapping settings object

GET /platform/1/quota/settings/mappings/<domain>?describe


Object properties


id Integer Specifies the system ID given to thedomain. In a POST request, this is theID of the created item that refers tothe item in the collection itemresource path.

mappings




domain String Specifies the fully qualified domainname of the source domain to map.

mappings

mapping String Specifies the fully qualified domainname of the destination domain tomap to.

mappings

type Array Specifies the authentication providertype. Options include: ADS, local,NIS, LDAP, and file.

mappings

Snapshots overviewA OneFS snapshot is a logical pointer to data that is stored on a cluster at a specific pointin time.

A snapshot references a directory on a cluster, including all data stored in the directoryand its subdirectories. If the data referenced by a snapshot is modified, the snapshotstores a physical copy of the data that was modified. Snapshots are created according touser specifications or are automatically generated by OneFS to facilitate systemoperations.

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 toactivate a SnapshotIQ license; by default, these snapshots are automatically deletedwhen OneFS no longer needs them. However, if you activate a SnapshotIQ license, youcan retain these snapshots. You can view snapshots generated by other modules withoutactivating a SnapshotIQ license.

You can identify and locate snapshots by name or ID. A snapshot name is specified by auser and assigned to the virtual directory that contains the snapshot. A snapshot ID is anumerical identifier that OneFS automatically assigns to a snapshot.

Snapshots resourcesYou can retrieve, create, modify, or delete snapshot configurations and settings.

Snapshot license resource

Retrieves license information for SnapshotIQ.


Get license information for SnapshotIQ GET /platform/1/snapshot/license


GET /platform/1/snapshot/license?describe



Snapshots overview 221

Object properties


duration Integer Specifies the total duration inseconds for temporary licenses.

N/A

expiration Integer Specifies the UNIX Epoch time whenthe license expires.

N/A

status Array Specifies the current status of thelicense. Possible states are:activated, evaluation,

expired, inactive, and

unknown.

N/A

name String Specifies the name of the licensedfeature.

N/A

Snapshot summary resource

Retrieves summary information about file system snapshots.


Get summary information about file systemsnapshots

GET /platform/1/snapshot/snapshots-summary


GET /platform/1/snapshot/snapshots-summary?describe


Object properties


count Integer Specifies the total number ofsnapshots.

summary

active_count Integer Specifies the total number ofsnapshots that are not aliases orpending for deletion.

summary

deleting_count Integer Specifies the total number ofsnapshots that are pending fordeletion.

summary

aliases_count Integer Specifies the total number ofsnapshot aliases.

summary

shadow_bytes Integer Specifies the number of bytes in asnapshot that are referenced in ashadow store.

summary

size Integer Specifies the sum of sizes in bytes ofall snapshots.

summary




active_size Integer Specifies the sum of sizes ofsnapshots that are not aliases orpending for deletion.

summary

deleting_size Integer Specifies the sum of sizes ofsnapshots that are pending fordeletion.

summary

Snapshots resource

Create, modify, delete, or retrieve information about file system snapshots.


Get a list of all snapshots GET /platform/1/snapshot/snapshots

Get a single snapshot GET /platform/1/snapshot/snapshots/<id|snapshot name>

Create a snapshot POST /platform/1/snapshot/snapshots

Modify a snapshot PUT /platform/1/snapshot/snapshots/<id|snapshot name>

Delete all snapshots DELETE /platform/1/snapshot/snapshots

Delete a snapshot DELETE /platform/1/snapshot/snapshots/<id|snapshot name>

View the detailed JSON schemafor a single snapshot

GET /platform/1/snapshot/snapshots/<id|snapshot name>?describe

View the detailed JSON schemafor all snapshots

GET /platform/1/snapshot/snapshots?describe

Query parameters

sort=<string>

Order results by this field. Options consist of id, name, path, created, expires,size, has_locks, schedule, alias_target, alias_target_name,pct_filesystem, pct_reserve, and state. The default value is id.

schedule=<string>

Only list snapshots that were created by this schedule.

type=[all|active|deleting]

Only return snapshots that match this type.

state=[all|alias|real]

Only return snapshots that match this state.

dir=[ASC|DESC]


limit=<integer>




resume=<string>


Object properties


total Integer Specifies the total number ofsnapshots available.

N/A


N/A

id Integer Specifies the system ID that is givento the snapshot. This ID is useful fortracking the status of delete pendingsnapshots, because after beingmarked for deletion, a snapshot canno longer be referenced by name. In aPOST request, this value is the ID thatrefers to the item in the collectionitem resource path.

snapshots

name String Specifies the user or system suppliedsnapshot name. This value is null forsnapshots that are pending delete.

snapshots

shadow_bytes Integer Specifies the number of bytes in asnapshot that is referenced in ashadow store.

snapshots

schedule String Specifies the name of the scheduleused to create this snapshot, ifapplicable.

snapshots

created Integer Specifies the Unix Epoch time thesnapshot was created.

snapshots

expires Integer Specifies the Unix Epoch time thesnapshot expires and is eligible forautomatic deletion.

snapshots

path String Specifies a snapshot of the /ifspath.

snapshots

size Integer Specifies the amount of storage (inbytes) used to store this snapshot.

snapshots

pct_filesystem Integer Specifies the percentage of the /ifsdirectory that is storing this snapshot.

snapshots

pct_reserve Integer Specifies the percentage of theconfigured snapshot that is reservedto store this snapshot.

snapshots

alias_target Integer Specifies the ID of the snapshotpointed to if this value is an alias.

snapshots

alias_target_name String Specifies the name of the snapshotpointed to if this value is an alias.

snapshots




has_locks Boolean True if the snapshot has one or morelocks present. See the locks resourceof a snapshot for a list of locks.

snapshots

state String Specifies the snapshot state. Theoptions are active or deleting.

snapshots

Snapshot schedules resource

Create, modify, delete, or retrieve information about snapshot schedules.


Get a list of all snapshot schedules GET /platform/1/snapshot/schedules

Get a single snapshot schedule GET /platform/1/snapshot/schedules/<id|schedule name>

Create a snapshot schedule POST /platform/1/snapshot/schedules

Modify a snapshot schedule PUT /platform/1/snapshot/schedules/<id|schedule name>

Delete all snapshot schedules DELETE /platform/1/snapshot/schedules

Delete a snapshot schedule DELETE /platform/1/snapshot/schedules/<id|schedule name>

View the detailed JSON schema for asnapshot schedule

GET /platform/1/snapshot/schedules/<id|schedule name>?describe

View the detailed JSON schema forsnapshot schedules

GET /platform/1/snapshot/schedules?describe

Query parameters

sort=<string>

Order results by this field. Options consist of id, name, path, pattern,schedule, duration, alias, next_run, and next_snapshot. The defaultoption is id.

dir=[ASC|DESC]


limit=<integer>


resume=<string>




Object properties


total Integer Specifies the total number ofschedules to display.

N/A


N/A

id Integer Specifies the system ID given to theschedule. In a POST request, thisvalue is the ID that refers to the itemin the collection item resource path.

schedules

name String Specifies the name of the schedule. schedules

pattern String Creates names for snapshotschedules according to a pattern withthe strftime function.

schedules

path String Specifies the path to take a snapshotof.

schedules

schedule String Specifies the isidate compatible

natural language description of theschedule.

schedules

duration Integer Specifies the amount of time before asnapshot is automatically deleted bya schedule. This duration is notadjusted for Daylight Saving Time(DST).

schedules

alias String Specifies the alternative name tocreate for each snapshot.

schedules

next_run Integer Specifies the UNIX Epoch time of nextsnapshot to be created.

schedules

next_snapshot String Specifies the formatted name of thenext snapshot to be created.

schedules

Snapshot locks resource

Create, modify, remove, or retrieve information about locks on an individual snapshot.


Get a list of locks on asnapshot

GET /platform/1/snapshot/snapshots/<id|snapshot name>/locks

Get a single lock on asnapshot

GET /platform/1/snapshot/snapshots/<snapshot-name|id>/locks/<lock-id>

Create a lock on a snapshot POST /platform/1/snapshot/snapshots/<snapshot-name|id>/locks

Modify a lock on a snapshot PUT /platform/1/snapshot/snapshots/<snapshot-name|id>/locks/<lock-id>




Remove a lock from asnapshot

DELETE /platform/1/snapshot/snapshots/<lock-id>/locks

View the detailed JSONschema for a snapshot lock

GET /platform/1/snapshot/snapshots/<snapshot-name|id>/locks/<lock-id>?describe

View the detailed JSONschema for snapshot locks

GET /platform/1/snapshot/snapshots/<id|snapshot name>/locks?describe

Query parameters

sort=<string>

Order results by this field; options consist of id, expires, and comment. Thedefault option is id.

dir=[ASC|DESC]


limit=<integer>


resume=<string>


Object properties


total Integer Specifies the number of items available. N/A

resume String Specifies the value for the resume argument to be used forcontinuation calls.

N/A

id Integer Specifies the system generated lock ID. In a POST request, thisvalue refers to the item in the collection item resource path.

locks

comment String Specifies the user-supplied lock comment. locks

expires Integer Specifies the UNIX Epoch time the snapshot lock expires and iseligible for automatic deletion.

locks

Snapshot pending resource

Retrieve information about snapshots that will be generated by a snapshot schedule.


Get a list of scheduled pending snapshots GET /platform/1/snapshot/pending

View the detailed JSON schema for this resource GET /platform/1/snapshot/pending?describe

Query parameters

schedule=<string>



Limit output to the named schedule.

begin=<integer>

UNIX Epoch time to start generating matches. The default option is now.

end=<integer>

UNIX Epoch time to end generating matches. The default option is forever.

limit=<integer>


resume=<string>


Object properties



N/A

id String Specifies the system supplied uniqueID used for sorting and paging.

pending

schedule String Specifies the name of the schedulethat created this snapshot.

pending

time Integer Specifies the UNIX Epoch time thesnapshot will be created.

pending

snapshot String Specifies the system snapshot nameformed from the schedule formate.

pending

path String Specifies the /ifs path of the

snapshot that is taken.

pending

Snapshot aliases resource

Create, delete, or retrieve information about snapshot aliases.


Get all snapshot aliases GET /platform/1/snapshot/aliases

Get a snapshot alias GET /platform/1/snapshot/aliases/<snapshot alias name or ID>

Create a snapshot alias POST /platform/1/snapshot/aliases

Modify a snapshot alias PUT /platform/1/snapshot/aliases/<snapshot alias name or ID>

Delete all snapshot aliases DELETE /platform/1/snapshot/aliases/

Delete a snapshot alias DELETE /platform/1/snapshot/aliases/<snapshot alias name or ID>


GET /platform/1/snapshot/aliases?describe





GET /platform/1/snapshot/aliases/<snapshot alias name or ID>?describe

Query parameters

sort=<string>

Order results by this field; options consist of id, name, snapshot, and created.The default option is id.

dir=[ASC|DESC]


limit=<integer>


resume=<string>


Object properties


total Integer Specifies the number of snapshotaliases.

N/A


N/A

created Integer Specifies the time that the snapshotalias was created in Unix Epoch time.

snapshots

id Integer Specifies the system ID assigned tothe snapshot alias.

snapshots

name String Specifies the user or system assignedname to the snapshot alias.

snapshots

target_id Integer Specifies the target snapshot ID. snapshots

target_name String Specifies the target snapshot name. snapshots

target String Specifies the name of the snapshottarget for the alias.

N/A

name String Specifies the user or system assignedname for the snapshot alias.

N/A

Snapshot changelists resource

Create or retrieve information about snapshot changelists.


Get all snapshot changelists GET /platform/1/snapshot/changelists




Get a snapshot changelist GET /platform/1/snapshot/changelists/<changelist>

Delete a snapshot changelist DELETE /platform/1/snapshot/changelists/<changelist>


GET /platform/1/snapshot/changelists?describe


Object properties


total Integer Specifies the number of snapshotchangelists returned.

N/A


N/A

id String Specifies the system ID given to thechangelist.

changelists

job_id Integer Specifies the ID of the job thatcreated the changelist.

changelists

num_entries Integer Specifies the number of LIN entries inthe changelist.

changelists

root_path String Specifies the root path to all of theLINs in the changelist.

changelists

snap1 Integer Specifies the job that computed thechangelist. The job specifies thesnap1 property as the lower

snapshot ID boundary.

changelists

snap2 Integer Specifies the job that computed thechangelist. The job specifies thesnap2 property as the higher


changelists

status String Specifies the status of the changelist. changelists

Snapshot changelists changelist lins resource

Retrieve information about a snapshot changelist entry.


Get snapshot changelist entries GET /platform/1/snapshot/changelists/<changelist>/lins




Get a snapshot changelist entry GET /platform/1/snapshot/changelists/<changelist>/lins/<lin>


GET /platform/1/snapshot/changelists/<changelist>/lins?describe


GET /platform/1/snapshot/changelists/<changelist>/lins/<lin>?describe


Object properties


total Integer Specifies the number of lins returned. N/A


N/A

atime Object Specifies the access time, whichindicates when a file was lastaccessed. The atime property is

disabled by default and must bemanually enabled.

lins

nsec Integer Specifies the timespec innanoseconds.

atime

sec Integer Specifies the timespec in seconds. atime

ctime Object Specifies the changed time, whichindicates when the file was lastchanged.

lins


ctime

sec Integer Specifies the timespec in seconds. ctime

id String Specifies the logical inode number(LIN) of the file associated with thesnapshot changelist entry.

lins

mtime Object Specifies the modified time, whichindicates when a file was lastmodified.

lins


mtime

sec Integer Specifies the timespec in seconds. mtime

path String Specifies the path to the file that isassociated with the snapshotchangelist entry.

lins




size Integer Specifies the size of the file that isassociated with the snapshotchangelist entry.

lins

type String Specifies the type of file that isassociated with the snapshotchangelist entry.

lins

Snapshot repstates resource

Create or retrieve information about snapshot repstates.


Get all snapshot repstates GET /platform/1/snapshot/repstates

Get a snapshot repstate GET /platform/1/snapshot/repstates/<repstate>

Delete a snapshot repstate POST /platform/1/snapshot/repstates/<repstate>


GET /platform/1/snapshot/repstates?describe


GET /platform/1/snapshot/repstates/<repstate>?describe


Object properties


total Integer Specifies the number of snapshotrepstates returned.

N/A


N/A

id String Specifies the system-generated IDassigned to the repstate.

repstates

snap1 Integer Specifies the job that computed thechangelist. The job specifies thesnap1 property as the lower


repstates

snap2 Integer Specifies the job that computed thechangelist. The job specifies thesnap2 property as the higher


repstates



Snapshot settings resource

Modify or retrieve information about global snapshot settings.


Get the current snapshot settings GET /platform/1/snapshot/settings

Modify the current snapshot settings PUT /platform/1/snapshot/settings


GET /platform/1/snapshot/settings?describe




Object properties


service Boolean True if the system allows snapshotcreation.

settings

autocreate Boolean True if the scheduled snapshotcreation services is enabled.

settings

autodelete Boolean True if the scheduled snapshotdeletion services is enabled.

settings

reserve Integer Specifies the percentage of space toreserve for snapshots.

settings

global_visible_accessible Boolean Enables a global switch foraccessibility and visibility settings ofsnapshot directories.

settings

nfs_root_accessible Boolean True if the root .snapshot directory isaccessible over NFS.

settings

nfs_root_visible Boolean True if the root .snapshot directory isvisible over NFS.

settings

nfs_subdir_accessible Boolean True if the subdirectory .snapshotdirectories are accessible over NFS.

settings

local_root_accessible Boolean True if the root .snapshot directory isaccessible locally.

settings

local_root_visible Boolean True if the root .snapshot directory isvisible locally.

settings

local_subdir_accessible Boolean True if the subdirectory .snapshotdirectories are accessible locally.

settings

smb_root_accessible Boolean True if the root .snapshot directory isaccessible over SMB.

settings

smb_root_visible Boolean True if the root .snapshot directory isvisible over SMB.

settings

smb_subdir_accessible Boolean True if the subdirectory .snapshotdirectories are accessible over SMB.

settings

Snapshots API examplesYou can see examples for some snapshots API requests.

Create a file pool policy

You can create a file pool policy.

Request example

POST /platform/1/filepool/policies Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{ "action_param":"true"



"action_type":"set_requested_protection" }

Response example


{"id" : "224731515-2571109568-2823010237-1003"}

Modify a snapshot alias

You can modify a snapshot alias.

Request example

PUT /platform/1/snapshot/aliases/snapshot2541Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name" : "snapshot2641"}



Access zones overviewAlthough the default view of an EMC Isilon cluster is that of one physical machine, youcan partition a cluster into multiple virtual containers called access zones. Access zonesallow you to isolate data and control who can access data in each zone.

Access zones support all configuration settings for authentication and identitymanagement services on a cluster, so you can configure authentication providers andprovision SMB shares and NFS exports on a zone-by-zone basis. When you create anaccess zone, a local provider is created automatically, which allows you to configure eachaccess zone with a list of local users and groups. You can also authenticate through adifferent authentication provider in each access zone.

To control data access, you can direct incoming connections to the access zone through aspecific IP address pool. Associating an access zone with an IP address pool restrictsauthentication to the associated access zone and reduces the number of available andaccessible SMB shares and NFS exports. Another advantage to multiple access zones isthe ability to configure audit protocol access for individual access zones. You can modifythe default list of successful and failed protocol audit events and then generate reportsthrough a third-party tool for an individual access zone.

A cluster includes a built-in access zone named System, where you manage all aspects ofa cluster and other access zones. By default, all cluster IP addresses connect to theSystem zone. Even if you create additional access zones, you configure all access zonesin the System zone. Role-based access, which primarily allows configuration actions, isavailable through only the System zone. All administrators, including those givenprivileges by a role, must connect to the System zone to configure a cluster.

Configuration management of a non-System access zone is not permitted through SSH,the OneFS Platform API, or the web administration interface. However, you can create anddelete SMB shares in an access zone through the Microsoft Management Console (MMC).


Access zones overview 235

Access zone resourcesRetrieve, 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.


Get all access zones GET /platform/1/zones

Get one access zone GET /platform/1/zones/<zone-id>

Create an access zone POST /platform/1/zones

Modify an access zone PUT /platform/1/zones/<zone-id>

Delete an access zone DELETE /platform/1/zones/<zone-id>

View the detailed JSON schema for all accesszones

GET /platform/1/zones?describe

View the detailed JSON schema for a singleaccess zone

GET /platform/1/zones/<zone-id>?describe


Object properties


id String Specifies the system ID for theaccess zone. In a POST request, thisvalue is the ID that refers to the itemin the collection item resource path.

zones

all_auth_providers Boolean Enables all authentication providersthat are available.

zones

alternate_system_provider String Specifies an alternate systemprovider.

zones

audit_failure String Specifies a list of failed operations toaudit.

zones

audit_success String Specifies a list of successfuloperations to audit.

zones

auth_providers Array[<string>] Specifies the list of authenticationproviders used on this access zone.

zones

cache_size Integer Specifies the maximum size of zonein-memory cache.

zones

create_path Boolean Determines if a path is created whena path does not exist.

zones

hdfs_authentication String Specifies the authentication type forthe HDFS protocol.

zones




hdfs_keytab String Specifies the Kerberos keytab forHDFS authentication.

zones

hdfs_root_directory String Specifies the root directory for theHDFS protocol.

zone

home_directory_umask Integer Specifies the permissions set onautomatically created user homedirectories.

zones

ifs_restricted Array[<persona>]

Specifies a list of users and groupsthat have restricted read/writeaccess to /ifs”.

zones

map_untrusted String Maps untrusted domains to theNetBIOS domain duringauthentication.

zones

name String Specifies the access zone name. zones

netbios_name String Specifies the NetBIOS name. zones

path String Specifies the access zone basedirectory path.

zones

protocol_audit_enabled Boolean Determines if I/O auditing is enabledon this access zone.

zones

skeleton_directory String Specifies the skeleton directory thatis used for user home directories.

zones

syslog_audit_events String Specifies a list of audit operations toforward to the syslog.

zones

syslog_forwarding_enabled Boolean Determines if zone events areforwarded to the syslog.

zones

system_provider String Specifies the system provider for theaccess zone.

zones

user_mapping_rules Array Specifies the current ID mappingrules.

zones

webhdfs_enabled Boolean Determines if WebHDFS is enabledon the access zone.

zones

zone_id Integer Specifies the access zone ID on thesystem.

zones

Access zones summary resource

Retrieve summary information about the access zones on a cluster.


Get information about all access zones GET /platform/1/zones-summary

Get non-privileged information about a specificaccess zone.

GET /platform/1/zones-summary/<ZONE>


Access zones overview 237


View the detailed JSON schema for this resource GET /platform/1/zones-summary?describe

View detailed JSON schema for this resource GET /platform/1/zones-summary/<ZONE>?describe


Object properties


count Integer Specifies the total number of accesszones on the cluster.

summary

list String Returns a list of access zone names. summary

path String Specifies the base path for a specificaccess zone.

summary

Access zone API examplesYou can see examples for some access zone API calls.

Create an access zone

Create an access zone on the cluster.

Request example

POST /platform/1/zonesAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

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

Response example


{"id":"MyZone"}

Modify an access zone

Modify the properties for an access zone on the cluster.

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

PUT /platform/1/zones/ZoneAAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

{"name":"ZoneB"}



Response example

204 No ContentContent-type: 'text/plain

Cluster statisticsYou can view performance, historical, and in-depth usage statistics for your EMC Isiloncluster, and control the output for each mode of statistics reporting.

Statistics resourcesYou can retrieve information about OneFS statistics through the following resources.

Note

Statistic API resources are available, but are currently unsupported.

Statistics current resourceThis resource enables you to query OneFS current statistics. Current statistics are themost currently available metrics at the time of the request. For a list of available statisticskeys with descriptions, see the /platform/1/statistics/keys or /platform/1/statistics/keys/<KEY> resources.


Get all current statistics GET /platform/1/statistics/current


GET /platform/1/statistics/current?describe

Query parameters

degraded=<boolean>

If true, try to continue even if some nodes are unavailable. If some nodes areunavailable, errors will be present in the per-key returned data.

devid=<string>

Query the specified node by device id (devid). This parameter can be set to either aninteger representing the devid or set to all. You can repeat this parameter to querymultiple nodes or set this parameter to the all option to query all nodes. Set thisvalue to 0 to query the local node.

key=<string>

Query multiple keys by name. You can repeat this parameter to query for multiplekeys.

timeout=<integer>

Wait for the specified amount of time for results from remote nodes.

expand_clientid=<boolean>

If true, use name resolution to expand client addresses and other IDs.


Cluster statistics 239

Object properties


stats Object Specifies properties for statisticshistory.

N/A

devid Integer Specifies the devid of the node forstatistics or 0 for cluster-scopedstatistics.

stats

error String Specifies the key specific error string. stats

error_code Integer Specifies the key specific errornumber.

stats

key String Specifies the key name of thestatistics.

stats

time Integer Specifies the UNIX Epoch time thestatistic was collected.

stats

value Any Specifies the key-dependent value. stats

Statistics keys resourceThis retrieves meta-data for matching statistics keys.


Get all statistic keys GET /platform/1/statistics/keys

Get a statistics key GET /platform/1/statistics/keys/<KEY>


GET /platform/1/statistics/keys?describe


GET /platform/1/statistics/keys/<KEY>?describe

Query parameters

count=<boolean>

Only count matching keys; do not return meta-data.

queryable=<boolean>

Only list keys that can or cannot be queries. The default value is set to true.

limit=<integer>


resume=<string>




Object properties


total Integer Specifies the total number of keysavailable.

N/A


N/A

keys Object Specifies properties for statisticskeys.

N/A

aggregation_type String Specifies the type of aggregationused in down-sampling. Optionsinclude: last, min, max, avg, sum,

and custom.

keys

base_name String Specifies the name of any key thatthis key is derived from.

keys

default_cache_time Integer Specifies the default time in secondsthat the system will use cachedvalues.

keys

description String Specifies the description of thestatistics key.

keys

key String Specifies the key name. keys

policies Array Specifies the effective history policiesfor the key.

keys

interval Integer Specifies the time in secondsbetween samples.

policies

persistent Boolean Determines whether history ispersistent.

policies

retention Integer Specifies the time in seconds to keepdata.

policies

policy_cache_time Integer Specifies the configured time inseconds that the system will usecached values.

keys

real_name String Specifies the name of the real key,when an alias is used.

keys

scope String Specifies the scope of the key keys

type String Specifies the data type of the keyvalues.

keys

units String Specifies the units of key values. keys

Statistics history resourceThis resource enables you to query OneFS time-series statistics over custom time ranges.Not all statistics will have time-series enabled, and for those statistics with time-seriesenabled, the full extent of the requested time range may not be available due toconfiguration or system uptime. For a list of available statistics keys with descriptions,


Statistics resources 241

see the /platform/1/statistics/keys or /platform/1/statistics/keys/<KEY> resources. These resource also describe available history policies for each key.


Get all statistics history GET /platform/1/statistics/history


GET /platform/1/statistics/history?describe

Query parameters

begin=<integer>

Set the earliest time in UNIX Epoch seconds of interest if available. Negative times areinterpreted as relative to before now.

end=<integer>

Set the latest time in UNIX Epoch seconds of interest if available. Negative times areinterpreted as relative to before now. If unspecified, use now as the end time.

devid=<string>

Query the specified node by device id (devid). This parameter can be set to either aninteger representing the devid or set to all. You can repeat this parameter to querymultiple nodes or set this parameter to the all option to query all nodes. Set thisvalue to 0 to query the local node.

key=<string>

Query multiple keys by name. You can repeat this parameter to query for multiplekeys.

timeout=<integer>

Wait for the specified amount of time for results from remote nodes.

interval=<integer>

Set the minimum sampling interval time in seconds. If native statistics are of a higherresolution, the data will be down-sampled.

memory_only=<boolean>

Only use statistics sources that reside in memory. These sources are faster, but haveless retention.

degraded=<boolean>

If true, try to continue even if some statistics are unavailable. If some statistics areunavailable, errors will be present in the per-key returned data.

expand_clientid=<boolean>

If true, use name resolution to expand client addresses and other IDs.

Object properties


stats Object Specifies properties for statisticshistory.

N/A

devid Integer Specifies the devid of the node forstatistics or 0 for cluster-scopedstatistics.

stats

error String Specifies the key specific error string. stats




error_code Integer Specifies the key specific errornumber.

stats

key String Specifies the key name of thestatistics.

stats

values Array Specifies the time-series values. stats

time Integer Specifies the UNIX Epoch time thestatistic was collected.

values

value Any Specifies the key-dependent value. values

Statistics protocols resourceThis resource returns a list of protocol and client statistics for OneFS.


Get all protocols GET /platform/1/statistics/protocols


GET /platform/1/statistics/protocols?describe


Object properties


protocols Object Specifies properties for this resource. N/A

name String Specifies the abbreviated name of theprotocol.

protocols

type String Specifies whether the protocol isinternal or external. Internal protocolsexpose metrics for internal OneFSsystems; external protocols arecustomer-facing.

protocols

Code samples for file system configurationCode samples illustrate the basic syntax of OneFS API requests for file systemconfiguration.

You can download a zip file that contains code samples for the Python programminglanguage and for curl commands from EMC Online Support. The sample code providesbrief examples on how to access, modify, and delete configuration settings on yourcluster through OneFS API requests.


Code samples for file system configuration 243

https://support.emc.com/docu54231

CHAPTER 4

File system access API


l File system access API overview.......................................................................... 246l Troubleshooting..................................................................................................248l File system access operations............................................................................. 250l Code samples for file system access................................................................... 316

File system access API 245

File system access API overviewYou 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.

Through the OneFS API, you can perform the types of file system operations listed in thefollowing 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 thefile 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

Additionally, you can create an external client or application to access the OneFS API inany major language, such as C, C++, Python, Java, or .Net.

Common response headersYou 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 serverthat responded to the request.

String

x-isi-ifs-target-type

Provides the resource type. This value can be a containeror an object.

String

Common request headersWhen you send a request to the OneFS API, you can access data through customizedheaders along with standard HTTP headers.

The following table provides information about common HTTP request headers:

Name Description Type Required

Authorization Specifies the authenticationsignature.

String Yes

Content-length Specifies the length of the messagebody.

Integer Conditional



Name Description Type Required

Date Specifies the current date accordingto the requestor.

HTTP-date No. A client shouldonly send a Dateheader in a requestthat includes an entity-body, such as in PUTand POST requests. Aclient without a clockmust not send a Dateheader in a request.

x-isi-ifs-spec-version

Specifies the protocol specificationversion. The client specifies theprotocol version and the serverdetermines if the protocol version issupported. You can test backwardscompatibility with this header.

String Conditional


Specifies the resource type. For PUToperations, this value can becontainer or object. For GET

operations, this value can becontainer, object, or any, or this

parameter can be omitted.

String Yes, for PUToperations.

Conditional, for GEToperations.

Common namespace attributesThe 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 HTTPdate/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 HTTPdate/time format.

HTTP date

change_time Specifies the date when the object was last changed (includingdata and metadata changes) in HTTP date/time format.

String

type Specifies the object type, which can be one of the followingvalues: container, object, pipe, character_device, block_device,symbolic_link, socket, or whiteout_file.

String


Common namespace attributes 247

Attribute Description Type

mtime_val Specifies the time when the object data was last modified in UNIXEpoch format.

Integer

btime_val Specifies the time when the object data was created in UNIX Epochformat.

Integer

atime_val Specifies the time when the object was last accessed in UNIXEpoch format.

Integer

ctime_val Specifies the time when the object was last changed (includingdata and metadata changes) in UNIX Epoch format.

Integer

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

TroubleshootingYou can troubleshoot failed requests to the namespace by resolving common errors andviewing activity logs.

Common error codesThe 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 errorcode that is treated as OK.

200 OK

AEC_BAD_REQUEST

The specified request returned a bad requesterror.

400 Bad Request

AEC_ARG_REQUIRED

The specified request requires an argument forthe operation.

400 Bad Request



Error Code Description HTTP status

AEC_ARG_SINGLE_ONLY

The specified request requires only a singleargument for the operation.

400 Bad Request

AEC_UNAUTHORIZED

The specified request requires userauthentication.

401 Unauthorized

AEC_FORBIDDEN The specified request was denied by the server.Typically, this response includes permissionerrors on OneFS.

403 Forbidden

AEC_NOT_FOUND The specified request has a target object that wasnot found.

404 Not Found

AEC_METHOD_NOT_ALLOWED

The specified request sent a method that is notallowed for the target object.

405 Method Not Allowed

AEC_NOT_ACCEPTABLE

The specified request is unacceptable. 406 Not Acceptable

AEC_CONFLICT The specified request has a conflict that preventsthe operation from completing.

409 Conflict

AEC_PRE_CONDITION_FAILED

The specified request has failed a precondition. 412 Precondition failed

AEC_INVALID_REQUEST_RANGE

The specified request has requested a range thatcannot be satisfied.

416 Requested Rangenot Satisfiable

AEC_NOT_MODIFIED

The specified request was not modified. 304 Not Modified

AEC_LIMIT_EXCEEDED

The specified request exceeded the limit set onthe server side.

403 Forbidden

AEC_INVALID_LICENSE

The specified request has an invalid license. 403 Forbidden

AEC_NAMETOOLONG

The specified request has an object name sizethat is too long.

403 Forbidden

AEC_SYSTEM_INTERNAL_ERROR

The specified request has failed because theserver encountered an unexpected condition.

500 Internal Server Error

Activity LogsActivity logs capture server and object activity, and can help identify problems. Thefollowing table shows the location of different types of activity logs.

Server Logs Object Daemon Log Generic Log

l /var/log<server>/webui_httpd_error.log

l /var/log/<server>/webui_httpd_access.log

For <server>, type the path to the server directory. Forexample: /apache2.

/var/log/isi_object_d.log

/var/log/message


Troubleshooting 249

File system access operationsYou can make requests through the OneFS API to perform operations on the file system.

Access pointsYou can access the file system namespace through an access point. The defaultnamespace access point for the OneFS file system is /ifs.

Root users can create an access point on the namespace, and initially only the root userhas 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 non-root users with writeprivileges are unable to reconfigure the path of an existing access point.

Additionally, each file or directory in an access point has its own permissions, so even ifa user has privileges for an access point, the user must still be given permissions foreach file and directory.

Configure a user accounts for read privilegesYou must configure user accounts with read privileges before users can access an accesspoint. User access privileges (such as read, write, or read-write) for files and directoriesthat 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 begiven to a user, or the user will be unable to access the access point.

Procedure

1. Create a user account by running the following command, where user1 is the new useraccount 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 PUTmethod to the URI.

In the following example, user1 is granted access to the ifs-ap1 access point bymodifying the ACL read-privilege on the access point.

PUT /namespace/ifs-ap1?acl&nsaccess=true HTTP/1.1Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==Host: 10.245.107.17:8080Content-Type:application/jsonContent-Length: 140{"authoritative":"acl", "acl":[{"trustee": {"name":"user1","type":"user"}, "accesstype":"allow", "accessrights":["file_read"], "op":"add"}]}'

Create a namespace access pointCreates a namespace access point in the file system. Only root users can create orchange namespace access points.

Request syntax

PUT /namespace/<access_point> HTTP/1.1Host <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 directoryof the OneFS file system.

Request query parametersThere are no query parameters for this request.

Request headersThis call sends common request headers.

Response headersThis call returns common response headers.

Response bodyNo message body is returned upon success.

Example requestThe following request creates an access point named 'accesspoint1' on the namespace.

PUT /namespace/accesspoint1 HTTP/1.1Host my_cluster:8080Date: Fri, 15 Mar 2013 21:51:50 GMTContent-Type: text/xml

{ "path": "/ifs/home/" }

Example response

HTTP/1.1 200 OKDate: Fri, 15 Mar 2013 21:51:50 GMTServer: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0 mod_fastcgi/2.4.6Allow: DELETE, GET, HEAD, POST, PUTx-isi-ifs-spec-version: 1.0Vary: Accept-EncodingContent-Encoding: gzipKeep-Alive: timeout=15, max=335Connection: Keep-AliveTransfer-Encoding: chunkedContent-Type: text/plain

Get namespace access pointsRetrieves the namespace access points available for the authenticated user.

Request syntax

GET /namespace/ HTTP/1.1Host <hostname>[:<port>]Date: <date>Authorization: <signature>


Access points 251



Response headerThis call returns common response headers.

Response bodyAn array of namespace access points is output in JSON. Only the access points that theuser has privileges for are returned.

Example requestThis example retrieves a list of all access points for the namespace on this cluster by theroot user.

GET /namespace/ HTTP/1.1Host my_cluster:8080Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <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/" } ]}

Get or set an access control list for a namespace access pointRetrieves or sets the access control list for a namespace access point.

Request syntax

GET /namespace/<access_point>?acl&nsaccess=true HTTP/1.1Host <hostname>[:<port>]Content-Length: <length>Date:<date>Authorization: <signature>

PUT /namespace/<access_point>?acl&nsaccess=true HTTP/1.1Host <hostname>[:<port>]Content-Length: <length>



Date: <date>Authorization: <signature>

Request query parameters

ParameterName

Description Default Type Required

acl This parameter is a functionalkeyword that does not have a value.

N/A N/A Yes

nsaccess Indicates that the operation is on theaccess point instead of the storepath.

This value must be set to true. If set tofalse or left blank, the requestbehaves similarly to a GET or PUToperation.

N/A Boolean Yes



Response bodyThe 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 1In this example, the GET operation retrieves the access control list from the namespace.

GET /namespace/ifs-ap1?acl&nsaccess=true HTTP/1.1Host: my_cluster:8080Authorization: <key>

Example response 1

HTTP/1.1 200 OKDate: Mon, 25 Mar 2013 18:42:16 GMTx-isi-ifs-spec-version: 1.0Transfer-Encoding: chunkedContent-Type: application/json { "acl":[ { "accessrights":[ "file_read" ], "accesstype":"allow", "inherit_flags":[

], "trustee":{ "id":"UID:2000", "name":"user1", "type":"user" }


Access points 253

} ], "authoritative":"acl", "group":{ "id":"GID:0", "name":"wheel", "type":"group" }, "mode":"0060", "owner":{ "id":"UID:0", "name":"root", "type":"user" }}

Example request 2In this example, the request sets an access control list for the access point.

PUT /namespace/ifs-ap1?acl&nsaccess=true HTTP/1.1Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==Host: 10.245.107.17:8080Content-Type:application/jsonContent-Length: 140

{ "authoritative":"acl", "acl":[ { "trustee":{ "name":"user1", "type":"user" }, "accesstype":"allow", "accessrights":[ "file_read" ], "op":"add" } ]}

Example response 2

HTTP/1.1 200 OKDate: Mon, 25 Mar 2013 17:24:55 GMTTransfer-Encoding: chunkedContent-Type: text/plainx-isi-ifs-spec-version: 1.0

Get version information for the namespace access protocolRetrieves the protocol versions that are supported for the current namespace accessserver.

Request syntax

GET /namespace/?versions HTTP/1.1Host <hostname>[:<port>]Content-Length: <length>Date: <date>Authorization: <signature>




Parametername


versions This parameter is a functionalkeyword that does not have a value.

N/A N/A Yes



Response bodyAn array of version strings that are supported by the current namespace API server isoutput in JSON.

Example requestThis example retrieves a list of all versions supported for the namespace access server.

GET /namespace/?versions HTTP/1.1Host my_cluster:8080Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization:<signature>

Example responseThis example shows that the namespace access server supports only version 1.0.

HTTP/1.1 200 OKDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19

{"versions": ["1.0"]}

Delete a namespace access pointDeletes a namespace access point. Only root users can delete namespace access points.Additionally, the deletion of a namespace access point does not delete the namespaceresource that the access point references.

Request syntax

DELETE /namespace/<access_point> HTTP/1.1Host <hostname>[:<port>]Content-Length: <length>Date: <date>Authorization: <signature>





Access points 255


Example requestThis example shows the delete operation for an access point named 'user1.'

DELETE /namespace/user1 HTTP/1.1Host my_cluster:8080Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response


Directory operationsYou can perform directory operations on the namespace.

Create a directoryCreates a directory with a specified path.

Request syntax

PUT /namespace/<access_point>/<container_path>[?recursive=<boolean>][?overwrite=<boolean>] HTTP/1.1Host <hostname>[:<port>]Content-Length: <length>Date: <date>Authorization: <signature>x-isi-ifs-target-type: container


ParameterName


recursive Creates intermediate foldersrecursively, when set to true.

False Boolean No

overwrite Deletes and replaces the existinguser attributes and ACLs of thedirectory with user-specifiedattributes and ACLS from the header,when set to true.

Returns an error if the directoryalready exists, when set to false.

If the directory does not already exist,the directory is created and set withthe user-specified attributes andACLs from the header. If no ACLs areset in the header, the default mode isset to 0700.

True Boolean No



Request headers

HeaderName


x-isi-ifs-access-control

Specifies a pre-defined ACL value orPOSIX mode with a string. If thisparameter is not provided, the modefor the directory is set to 0700 bydefault.

0700 (read,write, andexecute withownerpermissions)

String No

x-isi-ifs-node-pool-name

Specifies the OneFS node pool name.When set to ANY, OneFS selects thepool for the directory. Only users withroot access can set this header.

N/A String No

x-isi-ifs-attr-<attr_name>

Specifies extended user attributes onthe directory. The attributes namesare stored in upper case, and alldashes (-) are converted tounderscores (_).

N/A String No



Example requestThis request creates a directory on the namespace named 'folder1/folder2'.

PUT /namespace/ifs/folder1/folder2/?recursive=true HTTP/1.1Host my_cluster:8080x-isi-ifs-target-type: containerContent-Length: <length>Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response


Get the attributes for a directory with the HEAD methodRetrieves the attribute information for a specified directory without transferring thecontents 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.1Host <hostname>[:<port>]Date: <date>Authorization: <signature>


Directory operations 257


Request headers

HeaderName


If-Modified-Since

Returns directory content only if thedirectory was modified since thespecified time. If no directory contentwas modified, a 304 message isreturned.

None HTTP date No

If-Unmodified-Since

Returns directory content only if thedirectory was not modified since thespecified time. If there is nounmodified directory content, a 412message is returned to indicate thatthe precondition failed.

None HTTP date No

Response headers

HeaderName


Content-Encoding

Provides the content encoding thatwas applied to the object content, sothat decoding can be applied whenretrieving the content.

None String No

Content-Type

Provides a standard MIME-typedescription of the content format.

binary/octet-stream

String No


Provides the extended attributes thatwere set in the message header. Theattribute names are stored inuppercase, and all dashes (-) areconverted to underscores (_).

None String No

x-isi-ifs-missing-attr

Provides the number of attributesthat cannot be displayed in the HTTPheader. Missing attributes can beretrieved through the followingoperation: GET the extendedattributes of a directory.

None String No


Provides the access mode for thedirectory in octal notation.

None String No




Example request

HEAD /namespace/ifs/my_folder/ HTTP/1.1Host my_cluster:8080Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response

HTTP/1.1 200 OKDate: Thu, 22 Sep 2011 12:00:00 GMTConnection: closeServer: Apache2/2.2.19Last-Modified: Wed, 21 Sep 2011 12:00:00 GMTx-isi-ifs-access-control: 0600x-isi-ifs-attr-color: redx-isi-ifs-missing-attr: 1x-isi-ifs-spec-version: 1.0x-isi-ifs-target-type: containerVary: Accept-EncodingContent-Encoding: gzipContent-Type: text/xml; charset=UTF-8

Get the extended attributes of a directoryRetrieves the attribute information for a specified directory with the metadata queryargument.

Request syntax

GET /namespace/<access_point>/<container_path>?metadata HTTP/1.1Host <hostname>[:<port>]Date: <date>Authorization: <signature>


ParameterName


metadata This parameter is a functionalkeyword and does not have a value.

N/A N/A Yes



Response bodyThe 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 isconsidered to be a system defined attribute. When the <name_space> value is set to user,the attribute is considered a user defined attribute.

Example request

GET /namespace/ifs/my_folder/?metadata HTTP/1.1Host my_cluster:8080Content-Length : <length>Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response

HTTP/1.1 200 OKDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Length: <Length>Content-Type: application/JSONConnection: closeServer: Apache2/2.2.19

{ "attrs":[ { "name":"is_hidden", "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" }, { "name":"mode", "value":511 } ]}

Get the contents of a directoryRetrieves a list of files and subdirectories from a directory.

Request syntax

GET /namespace/<access_point>/<container_path>[?<query>] HTTP/1.1Host <hostname>[:<port>]Date: <date>Authorization: <signature>

Note

The query argument is optional and can include the parameters in the following table.


ParameterName


detail Specifies which object attributes aredisplayed. If the detail parameter

None String No



ParameterName


is excluded, only the name of theobject is returned.

You can specify multiple attributenames in CSV format.

If you set this value to default, thefollowing attributes are included:name, size, owner, last_modified,type, group, and mode.

limit Specifies the maximum number ofobjects to send to the client. You canset the value to a negative number toretrieve all objects.

Additionally, you can specify themaximum number of objects to returnwhen sorting directory entries byopening a secure shell (SSH)connection to any node in the cluster,logging in, and running the followingcommand:

isi_gconfig -t oapi max_sort_dir_sz=<integer>

1000 Integer No

resume Specifies a token to return in theJSON result to indicate when there isa next page. The client can includethe resume token to access the nextpage.

None String No

sort Specifies one or more attributes tosort on the directory entries. You canspecify multiple attributes byseparating the attributes with acomma, such as name, size,last_modified.

When sorting is on, the maximumnumber of objects returned is 1000.The entries are sorted in the orderthat the attributes appear in the list,from left to right.

None String No

dir Specifies the sort direction. Thisvalue can be either ascending(ASC) or descending (DESC).

None String No

type Specifies the object type to return,which can be one of the followingvalues: container, object, pipe,character_device, block_device,symbolic_link, socket, orwhiteout_file.

None String No



ParameterName


hidden Specifies if hidden objects arereturned.

None Boolean No

Request headers

HeaderName


If-Modified-Since

Returns directory content only if thedirectory was modified since thespecified time. If no directory contentwas modified, a 304 message isreturned.

None HTTP date No

If-Unmodified-Since

Returns directory content only if thedirectory was not modified since thespecified time. If there is nounmodified directory content, a 412message is returned to indicate thatthe precondition failed.

None HTTP date No

Response headers

HeaderName


Content-Encoding


None String No

Content-Type


application/json

String No


Provides the extended attributes thatwere set in the message header.

None String No


Provides the number of attributesthat cannot be displayed in the HTTPheader.

None Integer No


Provides the POSIX mode in octalnotation.

None String No

Response bodyAn array of objects in the directory is output in JSON format.



Example requestThe following request returns the contents of a directory named 'folder1/folder2'.

GET /namespace/folder1/folder2 HTTP/1.1Host my_cluster:8080Content-Length: <length>Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response

HTTP/1.1 200 OKDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Type: application/JSONConnection: closeServer: Apache2/2.2.19

{ "children":[ { "name":"cover" }, { "name":"f2" }, { "name":"cover.txt" }, { "name":"cover8" } ]}

Request example 2This request returns object details for the directory named 'folder1/folder2'.

GET /namespace/folder1/folder2/?limit=500&detail=default HTTP/1.1Host my_cluster:8080Content-Length: 0Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Response example 2

HTTP/1.1 200 OKDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Type: application/JSONConnection: 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",

} ]}

Copy a directoryRecursively copies a directory to a specified destination path. Symbolic links are copiedas regular files.

Request syntax

PUT /namespace/<access_point>/<container_path> HTTP/1.1x-isi-ifs-copy-source: /namespace/<access_point>/<source_path>Host <hostname>[:<port>]Date: <date>Authorization: <signature>


ParameterName


overwrite Specifies if the existing file should beoverwritten when a file with the samename exists.

False Boolean No

merge Specifies if the contents of a directoryshould be merged with an existingdirectory with the same name.

False Boolean No

continue Specifies whether to continue thecopy operation on remaining objectswhen there is a conflict or error.

False Boolean No

Request headers

HeaderName


x-isi-ifs-copy-source

Specifies the full path to the sourcedirectory.

The source and destination mustshare the same access point.

None String Yes





For this operation, the HTTP status code 200 OK does not always indicate a completesuccess. If the response body contains a JSON message, the operation has partiallyfailed, 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), anerror is returned. If the server initiates the copy, and then fails, "copy_errors" are returnedin structured JSON format.

Because the copy operation is synchronous, the client cannot stop an ongoing copy orcheck the status of a copy asynchronously.

Example request 1

PUT /namespace/ifs/dest1/ / HTTP/1.1x-isi-ifs-copy-source: /namespace/ifs/src1/Host my_cluster:8080Content-Length: <length>Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response 1

HTTP/1.1 200 OkDate: Thu, 22 Sep 2011 12:00:00 GMTServer: Apache2/2.2.19Content-Encoding: gzipx-isi-ifs-spec-version: 1.0Connection: Keep-AliveTransfer-Encoding: chunkedContent-Type: text/plain

Example request 2In 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.1x-isi-ifs-copy-source: /namespace/ifs/src1/Host my_cluster:8080Content-Length: <length>Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response 2

HTTP/1.1 200 OKDate: Thu, 22 Sep 2011 12:00:00 GMTServer: Apache2/2.2.19x-isi-ifs-spec-version: 1.0Connection: Keep-AliveTransfer-Encoding: chunkedContent-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)" } ],

}

Move a directoryMoves a directory from an existing source to a new destination path.

Request syntax

POST /namespace/<access_point>/<container_path> HTTP/1.1x-isi-ifs-set-location: /namespace/<access_point>/<dest_path>Host <hostname>[:<port>]Date: <date>Authorization: <signature>


Request headers

HeaderName


x-isi-ifs-set-location

Specifies the full path for thedestination directory.

The source and destinationdirectories must be in the sameaccess point.

None String Yes



Example request

POST /namespace/ifs/folder1/folder2/ HTTP/1.1x-isi-ifs-set-location: /namespace/ifs/dest1/dest2/Host my_cluster:8080Content-Length: <length>Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response

HTTP/1.1 204 No ContentDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19



Delete a directoryDeletes the directory at the specified path.

Request syntax

DELETE /namespace/<access_point>/<container_path>[?recursive=<Boolean>] HTTP/1.1Host <hostname>[:<port>]Date: <date>Authorization: <signature>


ParameterName


recursive Deletes directories recursively, whenset to true.

Returns an error if you attempt todelete a directory that is not empty,when set to false.

When the recursive parameter is

set to true, and there is an errordeleting a child, the operationcontinues to delete other children.Only the last error is returned.

False Boolean No




Example request

DELETE /namespace/folder1/folder2 HTTP/1.1Host my_cluster:8080Content-Length: <length>Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response




Set attributes on a directorySets attributes on a specified directory with the metadata query argument. You can alsoset 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.1Host <hostname>[:<port>]Content-Length : <length>Content-Type : application/JSONDate: <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.


ParameterName


metadata The metadata argument must be

placed at the first position of theargument list in the URI.

N/A String No

Request body parameters

ParameterName


action The values for the <action_value> fieldare replace or update. Note that

the <action_value> field operates inconjunction with the <operation_value>field.

To modify the existing attributes, setboth <action_value>and<operation_value> to update.

To delete the existing attributes, set<action_value> to update and

<operation_value> to delete.

update String No



ParameterName


To remove all extended attributesfirst, and then replace the attributeswith the values specified in theattrs 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 or delete. The

<operation_value> field is onlyapplicable when <action_value> is setto update.

update String No

namespace Specifies the namespace associatedwith the attributes set for thedirectory. The only supported valuefor this parameter is user.

user String No




Example request

PUT /namespace/ifs/my_folder/?metadata HTTP/1.1Host my_cluster:8080Content-Length : <length>Date: <date>Authorization: <signature>

{ "action":"replace", "attrs":[ { "name":"Manufacture", "value":"Foo", "namespace":"user" } ]}

Example response

HTTP/1.1 200 OKDate: Wed, 20 Mar 2013 17:19:15 GMTServer: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0 mod_fastcgi/2.4.6Allow: DELETE, GET, HEAD, POST, PUTx-isi-ifs-spec-version: 1.0Vary: Accept-Encoding



Content-Encoding: gzipKeep-Alive: timeout=15, max=500Connection: Keep-AliveTransfer-Encoding: chunkedContent-Type: text/plain

File operationsYou can perform file operations on the namespace.

Create a file objectCreates a file object with a given path. The file is either successfully created in whole, orno file is created at all. Partial files cannot be created.

Request syntax

PUT /namespace/<access_point>/<file_path>[?overwrite=<Boolean>] HTTP/1.1Host <hostname>[:<port>]Content-Length : <length>Date: <date>Authorization: <signature>

[Message Body]


ParameterName


overwrite If the overwrite parameter is set to

true, the preset user attributes andACLs of the file are deleted andreplaced with the user-specifiedattributes and ACLs from the header.If the overwrite parameter is set to

false and the file already exists, anerror message is returned. If the filedoes not already exist, the file iscreated and set with the user-specified attributes and ACLs fromthe header.

True Boolean No

Request headers

HeaderName


Content-Encoding

Specifies the content encoding thatwas applied to the object content, sothat decoding can be applied whenretrieving the content.

None String No

Content-Type

Specifies a standard MIME-typedescription of the content format.

binary/octet-stream

String Conditional


File operations 271

HeaderName



Specifies the resource type. Thisvalue can be container orobject.

None String Yes.

The valuemust be setto 'object.'


Specifies a pre-defined ACL value orPOSIX mode with a string in octalstring format.

0600 (read,write withownerpermissions)

String No


Specifies the extended attributes thatwere set in the message header. Theattributes names are stored in uppercase, and all dashes (-) are convertedto underscores (_).

None String No



Example request

PUT /namespace/ifs/my_folder/picture.jpg HTTP/1.1Host my_cluster:8080x-isi-ifs-target-type: objectContent-Type: image/jpegContent-Length: 65536Date: Thu Sep 22 16:06:32 GMT 2011Authorization: <signature>

[Byte Streams of pictue.jpg]

Example response

HTTP/1.1 201 CreatedDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19

Get the contents of a fileRetrieves the contents of a file from a specified path.

Request syntax

GET /namespace/<access_point>/<file_path> HTTP/1.1Host <hostname>[:<port>]Date: <date>Authorization: <signature>Range: bytes=<byte_range>




Request headers

HeaderName


Range Returns the specified range bytes ofan object. Only the basic range issupported. The format is defined as:

first-byte-pos "-" last-byte-pos

The first-byte-pos value in a byte-range-spec gives the byte-offset ofthe first byte in a range. The last-byte-pos value gives the byte-offset of thelast byte in the range; that is, the bytepositions specified are inclusive. Byteoffsets start at zero.

None String No

If-Modified-Since

Returns only files that were modifiedsince the specified time. If no fileswere modified since this time, a 304message is returned.

None HTTP date No

If-Unmodified-Since

Returns only files that were notmodified since the specified time. Ifthere are no unmodified files sincethis time, a 412 message is returnedto indicate that the preconditionfailed.

None HTTP date No

Response headers

Header Name Description

Content-Encoding Provides the content encoding that was applied to the objectcontent, so that decoding can be applied when retrieving thecontent.

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 messageheader when the file was created.

x-isi-ifs-missing-attr Provides the number of attributes that cannot be displayed in theHTTP header.

x-isi-ifs-access-control Provides the access mode for the file in octal number format.


Example request

GET /namespace/ifs/my_folder/picture.jpg HTTP/1.1Host my_cluster:8080


File operations 273

Date: Thu Sep 22 16:06:32 GMT 2011Authorization: <signature>

Example response

HTTP/1.1 200 OKDate: Thu Sep 22 16:06:32 GMT 2011Content-Length: 54380Content-Type: image/jpegConnection: closeServer: Apache2/2.2.19

[54380 bytes of data]

Copy a fileCopies a file to the specified destination path.

Request syntax

PUT /namespace/<access_point>/<file_path>[?overwrite=<Boolean>] HTTP/1.1x-isi-ifs-copy-source: /namespace/<access_point>/<source_path>Host <hostname>[:<port>]Date: <date>Authorization: <signature>


ParameterName


overwrite Specifies if the existing file should beoverwritten when a file with the samename exists.

False Boolean No

Request headers

HeaderName



Specifies the full path of the source.

The source and destination pathsmust be in the same access point.

N/A String Yes


Response bodyNo message body is returned upon success. For this operation, the HTTP status code 200OK may not indicate a complete success.

If the response body contains a JSON message, the operation has partially failed. If theserver fails to initiate a copy due to an error (such as an invalid copy source), an error isreturned. If the server initiates the copy, and then fails, "copy_errors" are returned instructured JSON format. Because the copy operation is synchronous, the client cannotstop an ongoing copy operation or check the status of a copy operation asynchronously.



Example request 1This example shows a successful copy.

PUT /namespace/ifs/folder1/myfile HTTP/1.1x-isi-ifs-copy-source: /namespace/ifs/source1/myfileHost my_cluster:8080Content-Length: <length>Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response 1

HTTP/1.1 200 OkDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19

Example request 2This example shows a failed copy, where the file is not overwritten.

PUT /namespace/accesspoint1/directory1/file2_copy HTTP/1.1Host 10.245.105.110:8080x-isi-ifs-copy-source: /namespace/accesspoint1/directory1/file2Date: Wed, 20 Mar 2013 21:33:55 GMTAuthorization: <signature>

Example response 2

HTTP/1.1 200 OKDate: Wed, 20 Mar 2013 21:33:55 GMTServer: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0 mod_fastcgi/2.4.6Allow: DELETE, GET, HEAD, POST, PUTx-isi-ifs-spec-version: 1.0Keep-Alive: timeout=15, max=500Connection: Keep-AliveTransfer-Encoding: chunkedContent-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 fileMoves a file to a destination path that does not yet exist.

Request syntax

POST /namespace/<access_point>/<file_path> HTTP/1.1x-isi-ifs-set-location: /namespace/<access_point>/<dest_path>Host <hostname>[:<port>]Date: <date>Authorization: <signature>


File operations 275


Request headers

HeaderName


x-isi-ifs-set-location

Specifies the full path of thedestination file. The source anddestination paths must be in thesame access point.

If the x-isi-ifs-set-location points to afile name that is different than thesource file name, the user canrename the file.

None String Yes



Example request

POST /namespace/ifs/folder1/myfile HTTP/1.1x-isi-ifs-set-location: /namespace/ifs/dest1/myfileHost my_cluster:8080Content-Length: <length>Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response

HTTP/1.1 204 Non ContentDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19

Delete a fileDeletes the specified file.

Request syntax

DELETE /namespace/<access_point>/<file_path> HTTP/1.1Host <hostname>[:<port>]Date:<date>Authorization: <signature>







Example request

DELETE /namespace/ifs/my_folder/test.txt HTTP/1.1Host my_cluster:8080Content-Length: <length>Date: Thu, 22 Sep 2011 12:00:00 GMTAuthorization: <signature>

Example response


Clone a fileClone a file to the destination path. If the parameter is set as a snapshot name, the file iscloned from that snapshot.

Request syntax

PUT /namespace/<access_point>/<file_path>[?<clone>][&<snapshot>][&<overwrite>] HTTP/1.1x-isi-ifs-copy-source: <source_file_path>Host <hostname>[:<port>]Date: <date>Authorization: <signature>


ParameterName


clone You must set this parameter to true inorder to clone a file.

False Boolean No

snapshot Specifies a snapshot name to clonethe file from. If a snapshot name isnot given, a temporary snapshot iscreated. The temporary snapshot isdeleted after the cloning operation iscomplete.

N/A String No

overwrite Specifies if an existing file should beoverwritten by a new file with thesame name.

False Boolean No

Request headers

HeaderName



Specifies the full path of the source. N/A String Yes


File operations 277

HeaderName


The source and destination pathsmust be in the same access point.


Response bodyNo response body is returned upon success.

Example request

PUT /namespace/ifs/folder1/myfile?clone=true HTTP/1.1x-isi-ifs-copy-source: /namespace/ifs/source1/myfileHost my_cluster:8080Content-Length : 0Date: <date>Authorization: <signature>

Example response

HTTP/1.1 200 OKDate: Thu, 21 Mar 2013 14:33:29 GMTContent-Length: 0Connection: close

Set attributes on a fileSets attributes on a specified file with the metadata query argument through the JSONbody. You can also set attributes with a header when the file is created through a headerwith the format: x-isi-ifs-<name>=<value>.

Request syntax

PUT /namespace/<access_point>/<file_path>?metadata HTTP/1.1Host <hostname>[:<port>]Content-Length : <length>Content-Type : application/JSONDate: <date>Authorization: <signature>

{ "action":"<action_value>", "attrs":[ { "name":"<key_name>", "value":"<key_value>", "namespace":"<namespace_value>", "op":"<operation_value>" }, ... ]}

Note

You can modify only the <content_type> and user specified attributes. All other systemattributes are ignored.




ParameterName




N/A String No


ParameterName


action The values for the <action_value> fieldare replace or update. The

<action_value> field operates inconjunction with the <operation_value>field.

To modify the existing attributes, setboth <action_value> and<operation_value> fields to update.

To delete the existing attribute, setthe <action_value> field to updateand <operation_value> to delete.

To remove all extended attributes firstand then replace the attributes withthe values specified in the attrsparameter, set <action_value> toreplace. When <action_value> is set

to replace, the <operation_value>

field is ignored.

update String No

op The values for the <operation_value>field are update or delete. The

<operation_value> field is onlyapplicable when <action_value> is setto update.

update String No

namespace Specifies the value for thenamespace that the attributeassociates with a directory. Thisparameter must be set to user if the

attributes are specified by users.

user String No



Response bodyNo response body is returned upon success.


File operations 279

Example request

PUT /namespace/accesspoint1/my_folder/mytest.txt?metadata HTTP/1.1Host my_cluster:8080Content-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 OKDate: Thu, 21 Mar 2013 14:33:29 GMTServer: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0 mod_fastcgi/2.4.6Allow: DELETE, GET, HEAD, POST, PUTx-isi-ifs-spec-version: 1.0Vary: Accept-EncodingContent-Encoding: gzipKeep-Alive: timeout=15, max=500Connection: Keep-AliveTransfer-Encoding: chunkedContent-Type: text/plain

Get the attributes for a file with the HEAD methodRetrieves the attribute information for a specified file. Attributes are returned as headersonly if they can be displayed.

Request syntax

HEAD /namespace/<access_point>/<file_path> HTTP/1.1Host <hostname>[:<port>]Date: <date>Authorization: <signature>


Request headers

HeaderName


If-Modified-Since

Returns only file content that wasmodified since the specified time. Ifno file content was modified, a 304message is returned.

None HTTP date No



HeaderName


If-Unmodified-Since

Returns only file content that was notmodified since the specified time. Ifthere is no unmodified file content, a412 message is returned to indicatethat the precondition failed.

None HTTP date No

Response headers

HeaderName


Content-Encoding


None String No

Content-Type


binary/octet-stream

String No


Provides the extended attributes thatwere set in the message header.

None String No


Provides the number of attributesthat cannot be displayed in the HTTPheader.

The missing attributes can beretrieved through the operation: GETextended attributes of a fileoperation.

None Integer No


Provides a pre-defined ACL value orPOSIX mode with a string, such asprivate, private_read, public_read,public_read_write, or public.

0700 String No


Example request

HEAD /namespace/ifs/my_folder/picture.jpg HTTP/1.1Host my_cluster:8080Date: Thu Sep 22 16:06:32 GMT 2011Authorization: <signature>

Example response

HTTP/1.1 200 OKDate: Thu Sep 22 16:06:32 GMT 2011Server: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0 mod_fastcgi/2.4.6Allow: DELETE, GET, HEAD, POST, PUTLast-Modified: Wed, 20 Mar 2013 18:16:17 GMT


File operations 281

x-isi-ifs-access-control: 0600x-isi-ifs-attr-color: redx-isi-ifs-missing-attr: 1x-isi-ifs-spec-version: 1.0x-isi-ifs-target-type: object

Get the extended attributes of a fileRetrieves the attribute information for a specified file with the metadata query argument.

Request syntax

GET /namespace/<access_point>/<file_path>?metadata HTTP/1.1Host <hostname>[:<port>]Date: <date>Authorization: <signature>


ParameterName




N/A String No



Response bodyThe 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 isconsidered to be a system defined attribute. When the <namespace_value> field is set touser, the attribute is considered a user-defined attribute.

Example request

GET /namespace/accesspoint1/directory1/file1?metadata HTTP/1.1Host: 10.245.105.110:8080User-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.8Accept-Language: en-US,en;q=0.5Accept-Encoding: gzip, deflateCookie: _SID_=20130321154838-cffed57ca0a91f15a7dca80fc88ed0a8; isisessid=7651c367-71d1-4ff1-9dd0-1eee09a4b03d; legacy=1; ys-lastStatusDashView=n%3A1; ys-monitoringView=s%3ALIVE; ys-monitoringData=s%3AAVGConnection: keep-aliveCache-Control: max-age=0

Example response

HTTP/1.1 200 OkDate: Thu, 21 Mar 2013 19:58:11 GMTServer: Apache/2.2.21 (FreeBSD) mod_ssl/2.2.21 OpenSSL/0.9.8x mod_webkit2/1.0 mod_fastcgi/2.4.6Allow: DELETE, GET, HEAD, POST, PUTx-isi-ifs-spec-version: 1.0Keep-Alive: timeout=15, max=436Connection: Keep-AliveTransfer-Encoding: chunkedContent-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 }, {


File operations 283

"name": "ctime_val", "value": 1363803377 }, { "name": "atime_val", "value": 1363803377 }, { "name": "btime_val", "value": 1363803377 }, { "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 listsYou can configure access control lists (ACLs) or permissions modes for namespacedirectories and files.

For detailed information on access control lists, see the OneFS Administration Guide.



Access control personasPersonas are a union of a user ID (UID), name, and type. Personas represent users andgroups for access control list (ACL) operations.

The JSON format for personas is:

{ "id":"<ID>", "name":"<name>", "type":"<type>"}

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 valuetakes precedence when all fields are available.

Access rights for directoriesThe following table lists the access rights for directories.

Accessrights

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 readaccess control lists

dir_gen_write The right to create files, create subdirectories, write attributes, write extendedattributes, 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 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 control lists 285

Access rights for filesThe 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.

execute The right to execute 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 readaccess control lists.

file_gen_write The right to write to the file, append to the file, write file attributes, writeextended file attributes, and read access control lists.

file_gen_execute

The right to execute files, and read access control lists.

file_gen_all Includes the rights 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 directoriesThe following table describes the access rights for both files and directories.

Accessrights

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 andstd_write_owner.



Accessrights

Functionality

Includes the following access rights for a file: file_write, append,file_write_ext_attr, file_write_attr, std_delete, std_write_dac andstd_write_owner.

Inherited access rightsThe following table lists the inheritance flags for directories and sub-directories.Inheritance flags specify the access rights inherited by the children of a directory.

InheritanceFlags

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 childdirectories and files when they are inherited.

inherited_ace Indicates that the access control list of the current directory or file wasinherited from a parent directory or file.

Get the ACL of a directoryRetrieves the access control list of the directory for the authenticated user.

Request syntax

GET /namespace/<access_point>/<container_path>/<container_name>?acl HTTP/1.1Host: <hostname>[:<port>]Date: <date>Authorization: <signature>


ParameterName


acl The acl argument must be placed at

the first position of the argument listin the URI.

N/A String Yes





Response body

HTTP/1.1 200 OKDate: Tue, 22 May 2012 12:00:00 GMTContent-Length: <length>Connection: closeServer: 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 asmode.

mode Provides the POSIX mode.

acl Provides the JSON array of access rights.

accesstype 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.

accessrights 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.1Host: my_cluster:8080Date: Tue, 22 May 2012 12:00:00 GMTAuthorization: <signature>

Example response


{ "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":[ "dir_gen_read" ] } ]}

Get the ACL of a fileRetrieves 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>


ParameterName




N/A String Yes



Response body


{ "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>" } ]}



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 asmode.

acl Provides the JSON array of access rights.


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.

accessrights Provides the list of access rights 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.1Host: my_cluster:8080Date: Tue, 22 May 2012 12:00:00 GMTAuthorization: <signature>

Example response

HTTP/1.1 200 OKDate: Thu, 12 Jan 2011 12:00:00 GMTContent-Length: <length>Connection: closeServer: 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", "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 createdSets the access control list for a directory by setting the headers when the directory iscreated.

Request syntax

PUT /namespace/<access_point>/<container_path>/<container_name> HTTP/1.1Host: <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 pre-defined ACL value or to a POSIXmode in octal string. If this header is not specified, the directory mode is set to 0700 bydefault when the directory is created.

Pre-defined ACLvalue

Access rights Access rights displayed

private_read The directory owner has the followingrights: list entries, read attributes,read extended attributes, access filesin subdirectories, read access controllist, and write access control list.

Directory owner: "accessrights":["dir_gen_read","dir_gen_execute","std_write_dac"],"inherit_flags":[]

private The directory owner has the followingrights: list entries, read attributes,read extended attributes, read accesscontrol list, create files, createsubdirectories, write attributes, writeextended attributes, access files insubdirectories, delete children(including read-only files), changeowner, write access control list, anddelete current directory.

Directory owner:"accessrights":["dir_gen_all"],"inherit_flags":[]

public_read The directory owner has the followingrights: list entries, read attributes,read extended attributes, read accesscontrol list, create files, create

Directory owner: "accessrights":["dir_gen_all"],"inherit_flags":[]





subdirectories, write attributes, writeextended attributes, access files insubdirectories, delete children(including read-only files), changeowner, write the access control list,and delete current directory.

All users have the following rights: listentries, read attributes, readextended attributes, read accesscontrol lists, and access files insubdirectories.

All users: "accessrights":["dir_gen_read","dir_gen_execute"],"inherit_flags":[]

public_read_write The directory owner has the followingrights: list entries, read attributes,read extended attributes, read accesscontrol list, create files, createsubdirectories, write attributes, writeextended attributes, access files insubdirectories, delete children(including read-only files), changeowner, write the access control list,and delete current directory.

All users have the following rights: listentries, read attributes, readextended attributes, read accesscontrol lists, create files, createsubdirectories, write attributes, writeextended attributes, and access filesin subdirectories.

Directory owner: "accessrights":["dir_gen_all"],"inherit_flags":[]

All users: "accessrights":["dir_gen_read","dir_gen_write","dir_gen_execute"],"inherit_flags":[]

public All users have the following rights: listentries, read attributes, readextended attributes, read accesscontrol list, create files, createsubdirectories, write attributes, writeextended attributes, access files insubdirectories, delete children(including read-only files), changeowner, write access control list, anddelete current directory.

All users: "accessrights":["dir_gen_all"],"inherit_flags":[]

The POSIX mode is an absolute mode that is constructed from the sum of one or moreoctal numbers listed in the following table.

Octalnumber

Description

4000 The set-user-ID-on-execution bit. Executable files with this bit have their UID set to theUID of the file owner.

2000 The set-group-ID-on-execution bit. Executable files with this bit have their GID set tothe GID of the file owner.



Octalnumber

Description

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 byowner.

0040 Allows read by group members.

0020 Allows write by group members.

0010 For files, allows execution by group members. For directories, allows directory queriesby group members.

0004 Allows read by others.

0002 Allows write by others.

0001 For files, allows execution by others. For directories, allows directory queries byothers.




Response bodyThere is no message body for this response.

Example request

PUT /namespace/ifs/dir1/dir2/dir HTTP/1.1Host: my_cluster:8080Content-Length: <length>Date: Tue, 22 May 2012 12:00:00 GMTAuthorization: <signature>x-isi-ifs-access-control: "public_read"

Example response




Set the ACL for a file when the file is createdSets 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.1Host: <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 pre-defined ACL value or to POSIXmode with octal string. By default, the mode for the file is set to 0600.



private_read The file owner has the following rights:read files, read attributes, readextended attributes, read accesscontrol lists, execute files, and writeaccess control list.

File owner: "accessrights":["file_gen_read","file_gen_execute","std_write_dac"],"inherit_flags":[]

private The file owner has the following rights:read file, read attributes, readextended attributes, read accesscontrol list, write to the file, append tothe file, write file attributes, writeextended file attributes, execute file,write or modify the access control list,change owner, and delete current file.

File owner:"accessrights":["file_gen_all"],"inherit_flags":[]

public_read The file owner has the following rights:read file, read attributes, readextended attributes, read accesscontrol list, write to the file, append tothe file, write file attributes, writeextended file attributes, execute file,write or modify the access control list,change owner, and delete current file.

All users have the following rights: readfiles, read attributes, read extendedattributes, read access control lists,and execute files.

File owner: "accessrights":["file_gen_all"],"inherit_flags":[]

All users: "accessrights":["file_gen_read","file_gen_execute"],"inherit_flags":[]

public_read_write The file owner has the following rights:read file, read attributes, readextended attributes, read accesscontrol list, write to the file, append tothe file, write file attributes, writeextended file attributes, execute file,

File owner: "accessrights":["file_gen_all"],"inherit_flags":[]

All users: "accessrights":["file_gen_read","file_gen_write","file_gen_execute"],"inherit_flags":[]





write/modify the access control list,change owner, and delete current file.

All users have the following rights: readfiles, read attributes, read extendedattributes, read access control lists,write to the file, append to the file,write file attributes, write extended fileattributes, and execute files.

public All users have the following rights: readfile, read attributes, read extendedattributes, read access control list,write to the file, append to the file,write file attributes, write extended fileattributes, execute file, write/modifythe access control list, change owner,and delete current file.

All users: "accessrights":["file_gen_all"],"inherit_flags":[]

The POSIX mode is an absolute mode, which consists of an octal number that isconstructed from the sum of one or more octal numbers listed in the following table.

Octalnumber

Description

4000 The set-user-ID-on-execution bit. Executable files with this bit have their uid set to theuid of the file owner.

2000 The set-group-ID-on-execution bit. Executable files with this bit have their gd set tothe 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 byowner.

0040 Allows read by group members.

0020 Allows write by group members.

0010 For files, allows execution by group members. For directories, allows directory queriesby group member.

0004 Allows read by others.

0002 Allows write by others.

0001 For files, allows execution by others. For directories, allows directory queries byothers.







Example request

PUT /namespace/ifs/dir1/dir2/file HTTP/1.1Host: my_cluster:8080Content-Length: <length>Date: Tue, 22 May 2012 12:00:00 GMTAuthorization: <signature>x-isi-ifs-access-control: "public_read"

Example response


Set the ACL of a directorySets the access control list of the directory.

Request syntax

PUT /namespace/<access_point>/<container_path>/<container_name>?acl HTTP/1.1Host: <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>", "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>" } ]}


ParameterName




N/A String Yes


ParameterName


owner Specifies the JSON object for theowner persona. You should onlyspecify the owner persona if you wantto change the owner of the target.

N/A JSON object No

group Specifies the JSON object for thegroup persona of the owner. Youshould only specify the grouppersona if you want to change thegroup of the target.

N/A JSON object No

authoritative The authoritative field is mandatoryand can take the value of either aclor mode.

acl: You can modify the owner,

group personas, or access rights forthe directory by setting theauthoritative field to acl and by

setting <action_value> to update.

When the authoritative field is set toacl, access rights are set for the

directory from the acl structure. Any

value specified for the modeparameter is ignored.

N/A String Yes



ParameterName


Note

When the authoritative field is set toacl, the default value for the

<action_value> field is replace. If the

<action_value> field is set toreplace, the system replaces the

existing access rights of the directorywith the access rights specified in theacl structure. If the acl structure is

empty, the existing access rights aredeleted and default access rights areprovided by the system. The defaultaccess rights for directories are readaccess 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 theauthoritative field to mode. When the

authoritative field is set to mode,

POSIX permissions are set on thedirectory. The <action_value> field andacl structure are ignored. If mode is

set on a directory that already hasaccess rights or if access rights areset on a directory that already hasPOSIX permissions set, the result ofthe operation varies based on theGlobal ACL Policy.

mode Specifies the POSIX mode. 0700 fordirectories

0600 forfiles

Octalnumber,specified asa string

No

action The <action_value> field is appliedwhen the authoritative field is set toacl. You can set the <action_value>

field to either update or replace.

When set to update, the existing

access control list of the directory ismodified with the access controlentries specified in the acl structure

of the JSON body.

When set to replace, the entire

access control list is deleted andreplaced with the access control

replace String No



ParameterName


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 andreplaced with the system set defaultaccess rights. The default accessrights for directories are read accesscontrol list (‘ std_read_dac’) and writeaccess control list (‘ std_write_dac’)for the owner.

acl Specifies the JSON array of accessrights.

N/A JSON object Conditional.

Mandatorywhen the<action_value> field is setto update;

optionalwhen the<action_value> is set toreplace


allow: Allows access to the directory

based on the access rights set for thetrustee.

deny: Denies access to the directory


N/A String Yes, unlessthe<action_value> field is setto replaceand the aclstructure isempty.

accessrights Specifies the access right valuesdefined for the directory.

N/A List of stringvalues

Conditional

Mandatorywhen the<action_value> field is setto updateand the<operation_value> field isset to eitheradd orreplaceand the<inherit_flags_list>field isunspecified.



ParameterName


Optionalwhen the<action_value> is set toupdate and

the<operation_value> field isset todelete, or

when the<action_value> field is setto replace.

inherit_flags Specifies the inherit flag values fordirectories.


Conditional

op The <operation_value> field is appliedwhen the <action_value> field is set toupdate. You can set the

<operation_value> field to add,

replace, or delete. If no

<operation_value> field is specified,the default value is add.

add: Creates a new access control

entry (ACE) if an ACE is not alreadypresent for a trustee and trusteeaccess type. If an entry is alreadypresent for that trustee and trusteeaccess type, this operation appendsthe access rights list to the currentACE for that trustee and trusteeaccess type.

delete: Removes the access rights

list provided from the existing ACE fora trustee and trustee access type. Ifthe input access rights list is empty ,the entire ACE that corresponds to thetrustee and trustee access type isdeleted.

replace: Replaces the entire ACE for

the trustee and trustee access typewith the input access rights list.

add, when

<action_value> is set toupdate.

String No






Example request 1This sample sets the ACL of a directory.

PUT /namespace/ifs/dir1/dir2/dir?acl HTTP/1.1Host: my_cluster:8080Content-Length: <length>Date: Tue, 22 May 2012 12:00:00 GMTAuthorization: <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


Example request 2This sample replaces the existing ACL of the directory with the access control entriesspecified in the acl structure. If the acl structure is empty, the existing ACL is replacedwith default system values. The directory owner has default read and write access to theaccess control list.

PUT /namespace/ifs/dir1/dir2/dir?acl HTTP/1.1Host: my_cluster:8080Content-Length: <length>Date: Tue, 22 May 2012 12:00:00 GMTAuthorization:<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


Set the ACL of a fileSets the access control list of a file.

Request syntax

PUT /namespace/<access_point>/<container_path>/<file_name>?acl HTTP/1.1Host: <hostname>[:<port>]Content-Length: <length>Date: <date>Authorization: <signature>x-isi-ifs-target-type: objectContent-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>", "op":"<operation_value>"



} ]}


ParameterName




N/A String Yes


ParameterName


owner Specifies the JSON object for theowner persona. You should onlyspecify the owner or group persona ifyou want to change the owner orgroup of the target.

N/A JSON object No

group Specifies the JSON object for thegroup persona of the owner. Youshould only specify the owner orgroup persona if you want to changethe owner or group of the target.

N/A JSON object No

authoritative The authoritative field is mandatoryand can take the value of either aclor mode.

acl: You can modify the owner,

group personas, or access rights forthe file by setting the authoritativefield to acl and by setting

<action_value>to update. When the

authoritative field is set to acl,

access rights are set for the file fromthe acl structure. Any value

specified for the mode parameter is

ignored.

N/A String Yes



ParameterName


Note

When the authoritative field is set toacl, the default value for the

<action_value> field is replace. If the

<action_value> field is set toreplace, the system replaces the

existing access rights of the file withthe access rights specified in the aclstructure. If the acl structure is

empty, the existing access rights aredeleted and default access rights areprovided by the system. The defaultaccess rights for files are read accesscontrol list (‘std_read_dac’) and writeaccess control list (‘std_write_dac’)for the owner.

mode: You can modify the owner and

group personas by setting theauthoritative field to mode. When the

authoritative field is set to mode,

POSIX permissions are set on the file.The <action_value> field and aclstructure are ignored. If mode is set

on a file that already has accessrights or if access rights are set on afile that already has POSIXpermissions set, the result of theoperation varies based on the GlobalACL Policy.

mode Specifies the POSIX mode. 0700 fordirectories

0600 forfiles

Octalnumber,specified asa string

No

action The <action_value> field is appliedwhen the authoritative field is set toacl. 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 ismodified with the access controlentries specified in the acl structure

of the JSON body.

When set to replace, the entire

access control list is deleted and

replace String No



ParameterName


replaced with the access controlentries 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 andreplaced with the system set defaultaccess rights. The default accessrights for files are read access controllist (‘ std_read_dac’) and write accesscontrol list (‘ std_write_dac’) for theowner.

acl Specifies the JSON array of accessrights.

N/A JSON object Conditional

Mandatorywhen the<action_value> field is setto updateand optionalwhen the<action_value> field is settoreplace.


allow: Allows access to the file


deny: Denies access to the file based

on the access rights set for thetrustee.

N/A String Yes, unlessthe<action_value> field is setto replaceand the aclstructure isempty.

accessrights Specifies the access right valuesdefined for the file.


Conditional

Mandatorywhen the<action_value> field is setto updateand the<operation_value>field isset to eitheradd or

replace,

and whenthe



ParameterName


<inherit_flags_list> field isunspecified.

Optionalwhen the<action_value> field is setto updateand the<operation_value> is set todelete.

inherit_flags Specifies the inherit flag values forthe file.


Conditional

Either the<accessrights_list> or<inherit_flags_list> mustbe specifiedwhen the<action_value> field is setto updateand the<operation_value> field isset to add orreplace.

op The <operation_value> field is appliedwhen the <action_value> field is set toupdate. You can set the

<operation_value> field to add,

replace, or delete. If no

<operation_value> field is specified,the default value is add.

add: Creates a new access control

entry (ACE) if an ACE is not alreadypresent for a trustee and trusteeaccess type. If an entry is alreadypresent for that trustee and trusteeaccess type, this operation appendsthe access rights list to the currentACE for that trustee and trusteeaccess type.

delete: Removes the access rights

list provided from the existing ACE fora trustee and trustee access type. Ifthe input access rights list is empty ,

add, when

the<action_value> field is setto update

String No



ParameterName


the entire ACE that corresponds to thetrustee and trustee access type isdeleted.

replace: Replaces the entire ACE for

the trustee and trustee access typewith the input access rights list.




Example requestThis sample sets the ACL of a file named 'file1'.

PUT /namespace/ifs/dir1/dir2/ns/file1?acl HTTP/1.1Host: my_cluster:8080Content-Length: <length>Date: Tue, 22 May 2012 12:00:00 GMTAuthorization: <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


Query operationsYou 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 objectQuery objects by system-defined and user-defined attributes in a directory.

Request syntax

POST /namespace/<access_point>/<container_path>?query[&<query_param>] HTTP/1.1Host <hostname>[:<port>]Date: <date>Authorization: <signature>

[JSON BODY]

Request query parametersThe query_param argument is optional and can be one or more of the parameters in thefollowing table, separated by an “&”.

ParameterName


limit Specifies the maximum number ofobjects to send to the client. You canset the value to a negative number toretrieve all objects.

1000 String No

detail Specifies which object attributes aredisplayed. If the detail parameter

is excluded, only the name of theobject is returned. If the detailparameter is set to yes, then systeminformation such as name, owner,group, mode, and size is returned.

You can specify multiple attributenames in CSV format. For example:

detail=size,container,content_type

No String No


Query operations 309

ParameterName


If you set this value to default, thefollowing attributes are included:name, size, owner, last_modified,type, group, and mode.

max-depth Specifies the maximum directory leveldepth to search for objects. If set to 0,only the specified directory issearched for objects. If set to -1, theentire hierarchy below the specifieddirectory is searched for objects.

0 String No



Response bodyAn 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.1Host my_cluster:8080Date: <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" } ]}

JSON query formatYou 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 anduser-defined attributes. For example:

["name", "last_modified", "user.color"]

In the results, the user-defined attribute is prefixed with "user."

The only logical operators supported are "and", "or", and "not", where "not" is an unaryoperator and only one condition is valid. The "not" operator negates the conditionevaluated 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 asfollows:

condition = scope_query|predicate

The predicate value is defined as follows:

predicate ={ "operator":"<comparison_operator>", "attr":"attr_name", "value":"attr_value" | string_array}


Query operations 311

The <comparison_operator> value can be any of the following operators: =, !=, <, <=, >, >=,like, or in.

The arithmetic comparison operators are self-explanatory. The "like" operator matchesthe specified attribute with a pattern of regular expressions. For example, the followingJSON 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 oneelement in the array. When only one element is in the array, the "in" operator behaves thesame way as the "=" operator. For example, the following query returns objects with theattribute "color" set to either "blue", "green", or "turquoise":

{ "operator":"in", "attr":"user.color", "value":[ "blue", "green", "turquoise" ]}

The attribute name can be the name of a user-defined attribute or one of the systemdefined 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." todifferentiate the attribute from a system attribute with the same name. For example, ifthere is a user defined attribute called "name", you should write the attribute as"user.name."

Multiple query predicates can be combined through logical operators. For example, thefollowing query returns objects that satisfy one of the following conditions: "Model" isprefixed 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 sub-query,which allows more complex queries. For example, the following query returns objects inwhich either the attribute "manufacture" is set to "ACME" or the "model" attribute is setto "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" } ] } ]}

SmartLock settingsOnly root users can configure SmartLock Write Once Read Many (WORM) retention dateand commit flag settings for a file in a SmartLock directory. A SmartLock license must beactive on the cluster to configure these settings.

Get the WORM properties of a fileRetrieves the WORM retention date and committed state of the file.

Request syntax

GET /namespace/<access_point>/<WORM_directory>/<file_name>?worm HTTP/1.1Host: <hostname>[:<port>]Date: <date>Authorization: <signature>


SmartLock settings 313


ParameterName


worm The worm argument must be placedat the first position of the argumentlist in the URI.

N/A String No



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}



worm_committed Indicates whether the file was committed to the WORM state.

worm_retention_date Provides the retention expiration date in CoordinatedUniversal 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 UNIXEpoch or UTC.

worm_override_retention_date Provides the override retention date that is set on theSmartLock directory where the file resides. If the date is notset or is earlier than or equal to the existing file retentiondate, this field has a null value. Otherwise, the date isexpressed in UTC/GMT, and is the retention expiration datefor 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 theSmartLock directory where the file resides. If the date is notset or if the date is set to earlier than or equal to the fileretention date, this field has a null value. Otherwise, the dateis expressed in seconds from UNIX Epoch and UTC, and is theretention expiration date set for the file if theworm_committed parameter is set to true.

This parameter is the same asworm_override_retention_date, but is expressed in

seconds from the Epoch or UTC.



Example request

GET /namespace/ifs/dir1/file?worm HTTP/1.1Host: my_cluster:8080Date: Tue, 22 May 2012 12:00:00 GMTAuthorization: <signature>

Example response


{ "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 directorySets the retention period and commits a file in a SmartLock directory.

Request syntax

PUT /namespace/<access_point>/<WORM_directory>/<file_name>?worm HTTP/1.1Host: <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 theSmartLock directory where the file resides, the file is automatically committed when theautocommit period elapses.

If the file is committed without setting a retention expiration date, the default retentionperiod specified for the SmartLock directory where the file resides is applied. Theretention date on the file can also be limited by the maximum retention period set on theSmartLock directory.

For details about SmartLock WORM behavior, refer to the OneFS Administration Guide.


ParameterName


worm The worm argument must be placedat the first position of the argumentlist in the URI.

N/A String No


SmartLock settings 315


ParameterName


worm_retention_date

Specifies the retention expirationdate string in Coordinated UniversalTime (UTC/GMT).

N/A Time, in thestring formatof: "YYYY-MM-DDhh:m:ssGMT"

No

commit_to_worm

Specifies whether to commit the fileto a WORM state after the retentiondate is set. If the file was committedbefore, the file remains committedregardless of the value in this field.

False Boolean No




Example requestSet the retention date for a file in a SmartLock directory.

PUT /namespace/ifs/dir1/file?worm HTTP/1.1Host: my_cluster:8080Date: Tue, 22 May 2012 12:00:00 GMTAuthorization: <signature>

{ "worm_retention_date":"2013-04-11 12:00:00 GMT", "commit_to_worm":true}

Example response

HTTP/1.1 200 OKDate: Tue, 22 May 2012 12:00:00 GMTContent-Length: 0Connection: closeServer: Apache2/2.2.19

Code samples for file system accessCode 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 programminglanguages and for curl commands from EMC Online Support. The sample code providesbrief examples on how to access, modify, and delete files and directories on your clusterthrough OneFS API requests.



https://support.emc.com/docu53714

isilon onefs 7.2.0 onefs api reference - dell emc us · onefs api overview the onefs application...

Documents