Isilon OneFS 7.2.1 OneFS API Reference - Dell · on the cluster or to system configuration...
Transcript of Isilon OneFS 7.2.1 OneFS API Reference - Dell · on the cluster or to system configuration...
Copyright © 2001-2015 EMC Corporation. All rights reserved. Published in the USA.
Published December, 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.1 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..............................................................................................183IP address pools............................................................................ 189File system.....................................................................................189File pools....................................................................................... 191SmartLock......................................................................................198Storage pools.................................................................................202SmartQuotas..................................................................................215Snapshots..................................................................................... 226Access zones................................................................................. 239Cluster statistics............................................................................ 243
Code samples for file system configuration................................................. 247
File system access API 249
File system access API overview.................................................................. 250Common response headers............................................................250Common request headers.............................................................. 250Common namespace attributes......................................................251
Troubleshooting..........................................................................................252File system access operations..................................................................... 254
Chapter 1
Chapter 2
Chapter 3
Chapter 4
CONTENTS
OneFS 7.2.1 OneFS API Reference 3
Access points.................................................................................254Directory operations.......................................................................260File operations............................................................................... 275Access control lists........................................................................ 288Query operations........................................................................... 313SmartLock settings........................................................................ 317
Code samples for file system access........................................................... 320
CONTENTS
4 OneFS 7.2.1 OneFS API Reference
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 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
6 OneFS 7.2.1 OneFS API Reference
CHAPTER 2
Introduction to the OneFS API
This section contains the following topics:
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 (RBAC). After therequest is approved, access is provided to either file system configuration libraries ordirectories and 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, either through 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:
Introduction to the OneFS API
8 OneFS 7.2.1 OneFS API Reference
/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
Introduction to the OneFS API
OneFS API architecture 9
OneFS API terminologyThe following terms are relevant to understanding the OneFS API.
Term Definition
Access point Root path of the URL to the file system. You can define an access point for anydirectory in the file system.
Collection Group of objects of a similar type. For example, all of the user-defined quotas inthe system make up a collection of quotas.
Data object An object that contains content data, such as a file on the system.
Namespace The file system structure on the cluster.
Object Containers or data objects.
This term can refer to system configuration data that is created by users, or to aglobal setting on the system.
For example, a user-created object can be a file system snapshot, quota, share,export, logical unit, or synchronization policy.
An object can also be global settings on the system, such as default share settings,HTTP server settings, snapshot subsystem settings, and so on.
Resource An object, collection, or function that you can access by a URI.
OneFS API 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 following components.
Component Definition
my_cluster The IPv4 or IPv6 address or hostname for the cluster
obj_port The number of the port. The default setting is 8080
access_point The name of the access point, such as /ifs
resource_path The file path to the directory that you want to access
resource_version The version of the OneFS API
collection_pattern The namespace, collection name, and object ID of the resource that you wantto configure
In both types of API requests, you can append query parameters to the end of resourceURIs to refine your request. For example, you can revise a GET request to return only a set
Introduction to the OneFS API
10 OneFS 7.2.1 OneFS API Reference
number of entries. In the following example, a maximum of 1,000 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 predefined 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. Predefined keywords are 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 metadata 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.
l The PUT and POST methods do not return full resource entity bodies upon success;these methods return success or failure codes.
Introduction to the OneFS API
HTTP methods 11
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:
Action
Allows 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/Write
Allows a user to view or modify a configuration subsystem such as statistics,snapshots, or quotas. For example, the ISI_PRIV_SNAPSHOT privilege allows 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==
Introduction to the OneFS API
12 OneFS 7.2.1 OneFS API Reference
Session cookiesEstablish 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 that provides 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 for theaccount requesting access to thecluster.
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 thatyou want to access in the request body. In the services property, specifyplatform for system configuration or namespace for file system access.
Content-type: application/jsonBody:{"username": "<string>","password": "<string>",
Introduction to the OneFS API
Session cookies 13
"services": ["platform" | “namespace”]}
If the server validates your username and password, a Set-Cookie header is returned.
2. Obtain the isisessid value from the Set-Cookie header.
201 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 through a sessioncookie.
Results
A session is created on the node on which the POST request was executed.
Send a request for access through a session cookie
Authenticate to a session through 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 the specified 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}
Introduction to the OneFS API
14 OneFS 7.2.1 OneFS API Reference
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 that containsinformation about the session. If the server does not validate the session ID contained inthe cookie, the server returns 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 in 15minutes after a period of inactivity or in 4 hours after an absolute period of time.
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
Introduction to the OneFS API
Session cookies 15
If authorization fails:
401 UnauthorizedContent-Type: application/json{ "errors":[ { "message":"authorization required" } ]}
Introduction to the OneFS API
16 OneFS 7.2.1 OneFS API Reference
CHAPTER 3
System configuration API
This section contains the following topics:
l System configuration API overview........................................................................ 18l System configuration API resources.......................................................................21l Code samples for file system configuration......................................................... 247
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}
System configuration API
18 OneFS 7.2.1 OneFS API Reference
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}
System configuration API
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:
{Standard JSON success or error 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:
{Standard JSON success or error 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>, ... }, ... ]}
System configuration API
20 OneFS 7.2.1 OneFS API Reference
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.
System configuration API
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:
Property Type Description
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.
System configuration API
22 OneFS 7.2.1 OneFS API Reference
Property Type Description
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
System configuration API
Authentication and access control overview 23
Property Type Type Property of
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:
Property Type Description
id String Specifies the formal name of the privilege.
name String Specifies the name of the privilege.
read-only Boolean Determines if the privilege is specified 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
Query parametersThere are no parameters for this resource.
System configuration API
24 OneFS 7.2.1 OneFS API Reference
Object properties
Property Type Description Property of
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
System configuration API
Authentication and access control overview 25
Auth user access resource
Retrieve the access rights that a specified user has for a file.
Operation Method and URI
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
Property Type Description Property of
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
System configuration API
26 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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.
Operation Method and URI
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
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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.
Operation Method and URI
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>
System configuration API
Authentication and access control overview 27
Operation Method and URI
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
Property Type Description Property of
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.
Operation Method and URI
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>
System configuration API
28 OneFS 7.2.1 OneFS API Reference
Operation Method and URI
View the detailed JSON schema for thisresource
GET /platform/1/auth/users/<user-id>/member_of?describe
Query parameters
provider=<string>Filter groups by provider.
resolve_names=<Boolean>Retrieve additional information about the user ID and name, default is set to true.
zone=<string>Filter groups by access zone.
resume=<string>Continue returning results from the previous request (cannot be combined with otherparameters).
Object properties
Property Type Description Property of
resume String Specifies the value for the resumeargument for continuation requests.
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/auth/groups?describe
Query parameters
cached=<Boolean>If true, only return cached objects.
domain=<string>Filter groups by domain.
System configuration API
Authentication and access control overview 29
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.
resolve_names=<Boolean>Return both the group ID and name, default is set to true.
zone=<string>Filter groups 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
Property Type Type Property of
resume String Specifies the value for the resumeargument for continuation requests.
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/auth/groups/<group-id>/members?describe
Query parameters
provider=<string>Filter groups by the provider.
resolve_names=<Boolean>Retrieve additional information about the user ID and name, default is set to true.
zone=<string>Filter groups by access zone.
System configuration API
30 OneFS 7.2.1 OneFS API Reference
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
Property Type Description Property of
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.
Operation Method and URI
Get the members of a netgroup GET /platform/1/auth/netgroups/<netgroup>
View the detailed JSON schema for thisresource
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
Property Type Description Property of
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
System configuration API
Authentication and access control overview 31
Property Type Description Property of
username String Specifies the user who is valid for thisnetgroup.
netgroups
Auth settings mapping resource
Modify or retrieve information about identity mapping settings.
Operation Method and URI
Retrieve default identity mapping settings GET /platform/1/auth/settings/mapping/defaults
Modify the default identity mappingsettings
PUT /platform/1/auth/settings/mapping/defaults
View the detailed JSON schema for thisresource
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
Property Type Description Property of
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
System configuration API
32 OneFS 7.2.1 OneFS API Reference
Auth mapping identities resource
Set, modify, delete, or retrieve information about identity mappings.
Operation Method and URI
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
View the detailed JSON schema for thisresource
GET /platform/1/auth/mapping/identities?describe
View the detailed JSON schema for thisresource
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 setto true. The default is set to false, which leaves the existing identity mappingand returns 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.
System configuration API
Authentication and access control overview 33
Object properties
Property Type Description Property of
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.
Operation Method and URI
Get the user mapping rules GET /platform/1/auth/mapping/users/rules
Replace all user mapping rules PUT /platform/1/auth/mapping/users/rules
View the detailed JSON schema for thisresource
GET /platform/1/auth/mapping/users/rules?describe
Query parameters
zone=<string>The access zone that the rules apply to.
Object properties
Property Type Description Property of
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
System configuration API
34 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
user String Specifies the user name for thedomain.
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
user String Specifies the user name for thedomain.
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 String Specifies the user name for thedomain.
user
user1 Object Specifies the properties for theprimary user.
rules
domain Integer Specifies the domain name. user1
user String Specifies the user name for thedomain.
user1
user2 Object Specifies the properties for thesecondary user.
rules
domain Integer Specifies the domain name. user2
user String Specifies the user name for thedomain.
user2
Auth mapping users lookup resource
Retrieve the access token for any authenticated user.
Operation Method and URI
Lookup a user through the user mapper GET /platform/1/auth/mapping/users/lookup
System configuration API
Authentication and access control overview 35
Operation Method and URI
View the detailed JSON schema for thisresource
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
Property Type Description Property of
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.
Operation Method and URI
Get a summary of authentication providers GET /platform/1/auth/providers/summary
View the detailed JSON schema for thisresource
GET /platform/1/auth/providers/summary?describe
Query parametersThere are no parameters for this resource.
System configuration API
36 OneFS 7.2.1 OneFS API Reference
Object properties
Property Type Description Property of
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/auth/providers/krb5?describe
View the detailed JSON schema for thisresource
GET /platform/1/auth/providers/krb5/<ID>?describe
Query parameters
scope=[user|default|effective]The name of the access zone that is serving the request. If this parameter isspecified as effective, or if the parameter is unspecified, all fields are shown. If
System configuration API
Authentication and access control overview 37
the parameter is specified as user, only fields with non-default values are shown. Ifthe parameter is specified as default, the default values are returned.
Object properties
Property Type Description Property of
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.
Operation Method and URI
Retrieve default Kerberos authenticationsettings
GET /platform/1/auth/settings/krb5/default
System configuration API
38 OneFS 7.2.1 OneFS API Reference
Operation Method and URI
Modify the default Kerberos authenticationsettings
PUT /platform/1/auth/settings/krb5/default
View the detailed JSON schema for thisresource
GET /platform/1/auth/settings/krb5/default?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/auth/settings/krb5/realms?describe
View the detailed JSON schema for thisresource
GET /platform/1/auth/settings/krb5/realms/<realm name or ID>?describe
Query parametersThere are no query parameters for this resource.
System configuration API
Authentication and access control overview 39
Object properties
Property Type Description Property of
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/auth/settings/krb5/domains?describe
View the detailed JSON schema for thisresource
GET /platform/1/auth/settings/krb5/domains/<domain name or ID>?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
40 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/auth/providers/ads/<id>/domains?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
Authentication and access control overview 41
Property Type Description Property of
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.
Operation Method and URI
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>
View the detailed JSON schema forthis resource
GET /platform/1/auth/providers/ads/<domain>?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
Property Type Description Property of
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 not
ads
System configuration API
42 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
proactively assigned, but when auser's identity does not include a UID,the system may allocate one.
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
System configuration API
Authentication and access control overview 43
Property Type Description Property of
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
system Boolean Indicates that the provider instancewas created by OneFS and cannot beremoved.
ads
Auth ADS providers controllers resource
Retrieve information about all of the domain controllers for a trusted ADS domain.
Operation Method and URI
Get all domain controllers for a trustedADS domain
GET /platform/1/auth/providers/ads/<domain-id>/controllers
View the detailed JSON schema for thisresource
GET /platform/1/auth/providers/ads/<domain-id>/controllers?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
controllers Array Specifies properties the domaincontrollers.
N/A
System configuration API
44 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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.
Operation Method and URI
Get objects that are searchable in domains GET /platform/1/auth/providers/ads/<object>/search
View the detailed JSON schema for thisresource
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>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
Property Type Description Property of
resume String Specifies the value for the resumeargument for continuation requests.
N/A
System configuration API
Authentication and access control overview 45
Property Type Description Property of
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/auth/providers/file?describe
Query parameters
scope=[user|default|effective]If specified as effective, or unspecified, all fields are shown. If specified asuser, only fields with non-default values are shown. If specified as default, thedefault values are returned.
Object properties
Property Type Description Property of
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
create_home_directory Boolean Creates a home directory on the firstlogin.
file
System configuration API
46 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
System configuration API
Authentication and access control overview 47
Property Type Description Property of
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
system Boolean Indicates that the provider instancewas created by OneFS and cannot beremoved.
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.
Operation Method and URI
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>
View the detailed JSON schema forthis resource
GET /platform/1/auth/providers/ldap/<provider-id>?describe
System configuration API
48 OneFS 7.2.1 OneFS API Reference
Query parameters
scope=[user|default|effective]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
Property Type Description Property of
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
create_home_directory Boolean Creates a home directory on the firstlogin.
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
findable_groups String Specifies a list of groups that can beresolved.
ldap
System configuration API
Authentication and access control overview 49
Property Type Description Property of
findable_users String Specifies a list of users that can beresolved.
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
group_domain String Specifies the domain used to qualifygroups for this provider.
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
home_directory_template String Specifies the home directory templatepath.
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
listable_groups String Specifies groups that can be viewedin the provider.
ldap
listable_users String Specifies users that can be viewed inthe provider.
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
System configuration API
50 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
system Boolean Indicates that the provider instancewas created by OneFS and cannot beremoved.
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
unlistable_groups String Specifies a group that cannot belisted by the provider.
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
System configuration API
Authentication and access control overview 51
Property Type Description Property of
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/auth/providers/local?describe
Query parameters
scope=[user|default|effective]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
Property Type Description Property of
local Object Specifies the properties for a localauthentication provider.
N/A
authentication Boolean Enables authentication through theprovider.
local
create_home_directory Boolean Creates a home directory on the firstlogin.
local
home_directory_template String Specifies the home directory templatepath.
local
id String Specifies the ID for the local provider. local
System configuration API
52 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
system Boolean Indicates that the provider instancewas created by OneFS and cannot beremoved.
local
Auth NIS providers resource
Create, modify, delete, or retrieve information about an Network Information Service (NIS)authentication provider.
Operation Method and URI
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>
System configuration API
Authentication and access control overview 53
Operation Method and URI
Delete an NIS provider DELETE /platform/1/auth/providers/nis/<nis-name>
View the detailed JSON schema for thisresource
GET /platform/1/auth/providers/nis?describe
Query parameters
scope=[user|default|effective]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
Property Type Description Property of
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
findable_groups String Specifies a list of groups that can beresolved.
nis
findable_users String Specifies a list of users that can beresolved.
nis
group_domain String Specifies the domain used to qualifygroups for this provider.
nis
home_directory_template String Specifies the home directory templatepath.
nis
hostname_lookup Boolean Enables host name lookups. nis
id String Specifies the NIS provider ID. nis
System configuration API
54 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
listable_groups String Specifies groups that can be viewedin the provider.
nis
listable_users String Specifies users that can be viewed inthe provider.
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
unlistable_groups String Specifies a group that cannot belisted by the provider.
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
System configuration API
Authentication and access control overview 55
Property Type Description Property of
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/auth/roles/<role-id>/members?describe
Query parameters
resolve_names=<Boolean>Retrieve additional information about the user ID and name, default is set to true.
Object properties
Property Type Description Property of
resume String Specifies the value for the resume argument forcontinuation requests.
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/auth/roles?describe
System configuration API
56 OneFS 7.2.1 OneFS API Reference
Query parameters
resolve_names=<Boolean>Retrieve additional information about the user ID and name, default is set to true.
resume=<string>Continue returning results from the previous request (cannot be combined with otherparameters).
Object properties
Property Type Description Property of
resume String Specifies the value for the resume argument forcontinuation requests.
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/auth/roles/<id>/privileges?describe
Query parameters
resume=<string>Continue returning results from the previous request (cannot be combined with otherparameters).
Object properties
Property Type Description Property of
resume String Specifies the value for the resumeargument for continuation requests.
N/A
privileges Array[<privilege>]
Specifies the privileges that aregranted by the role.
N/A
System configuration API
Authentication and access control overview 57
Auth global settings resource
Retrieve or modify the global authentication settings on the cluster.
Operation Method and URI
Get global settings GET /platform/1/auth/settings/global
Modify global settings PUT /platform/1/auth/settings/global
View the detailed JSON schema for thisresource
GET /platform/1/auth/settings/global?describe
Query parameters
scope=[effective|user|default]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
Property Type Description Property of
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
System configuration API
58 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
System configuration API
Authentication and access control overview 59
Auth shells resource
Retrieve a list of user shells that are supported on the cluster.
Operation Method and URI
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
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
shells Array[<string>]
Specifies a list of supported shells. N/A
Auth wellknowns resource
Retrieve wellknown personas from the cluster.
Operation Method and URI
Get all wellknown personas GET /platform/1/auth/wellknowns
Get a wellknown persona GET /platform/1/auth/wellknowns/<wellknown>
View the detailed JSON schema for thisresource
GET /platform/1/auth/wellknowns?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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.
System configuration API
60 OneFS 7.2.1 OneFS API Reference
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
204 No ContentContent-type: text/plain
System configuration API
Authentication and access control overview 61
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
201 CreatedContent-type: application/json
{"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
201 CreatedContent-type: application/json
{"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
201 CreatedContent-type: application/json
{"id" : "SID:S-7-6-25-4784731515-2575609568-2323010237-2005"}
System configuration API
62 OneFS 7.2.1 OneFS API Reference
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
201 CreatedContent-type: application/json
{"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
204 No ContentContent-type: text/plain
System configuration API
Authentication and access control overview 63
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
201 CreatedContent-type: application/json
{"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
204 No ContentContent-type: text/plain
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
204 No ContentContent-type: text/plain
System configuration API
64 OneFS 7.2.1 OneFS API Reference
Create an authentication role
Create an authentication role.
Request example
POST /platform/1/auth/rolesAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==
{"name":"dba"}
Response example
201 CreatedContent-type: application/json
{"id" : "dba"}
Modify an authentication role
Modify an authentication role.
Request example
PUT /platform/1/auth/roles/dbaAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==
{"name":"dba2"}
Response example
204 No ContentContent-type: text/plain
Modify global authentication settings
Modify global authentication settings.
Request example
PUT /platform/1/auth/settings/globalAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==
{"send_ntlmv2":"true"}
Response example
204 No ContentContent-type: text/plain
Create a krb5 realm
Create a krb5 authentication realm.
Request example
POST /platform/1/auth/settings/krb5/realmsAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==
{"realm":"test_realm"}
System configuration API
Authentication and access control overview 65
Response example
201 CreatedContent-type: application/json
{"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
201 CreatedContent-type: application/json
{"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
204 No ContentContent-type: application/json
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"}
System configuration API
66 OneFS 7.2.1 OneFS API Reference
Response example
204 No ContentContent-type: application/json
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.
Audit settings resource
Applies the standard system object pattern to OneFS audit settings.
Operation Method and URI
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
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
config_auditing_enabled Boolean Enables logging for API configurationchanges when set to true.
settings
System configuration API
Auditing overview 67
Property Type Description Property of
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.
Operation Method and URI
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
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
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.
System configuration API
68 OneFS 7.2.1 OneFS API Reference
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==
{ '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 }
System configuration API
Auditing overview 69
Response exampleNo message body is returned for this request.
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:
Property Type Description
enabled Boolean True if the user mapping is applied.
user <persona> Specifies the name of the privilege.
primary_group <persona> Specifies persona properties for the 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:
Property Type Description
id <persona-id> Specifies the serialized form of the persona.
System configuration API
70 OneFS 7.2.1 OneFS API Reference
Property Type Description
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
View the detailed JSON schema for thisresource
GET /platform/2/protocols/nfs/exports-summary?describe
Query parameters
zone=<string>Filter exports by access zone.
Object properties
Property Type Description Property of
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.
Operation Method and URI
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
System configuration API
NFS 71
Operation Method and URI
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>Filter exports by access zone.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the total number of exportsconfigured.
N/A
resume String Specifies the value for the resumeargument for continuation requests.
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.
exports
System configuration API
72 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
This parameter does not affect serverbehavior, but is included toaccommodate legacy clientrequirements.
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 optimalsettings for the server, but is notenforced.
exports
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
System configuration API
NFS 73
Property Type Description Property of
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 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
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 advise
exports
System configuration API
74 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
the client of optimal settings for theserver, but is not enforced.
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
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
System configuration API
NFS 75
Property Type Description Property of
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,
filesync, and unstable.
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.
Operation Method and URI
Get all NFS aliases GET /platform/2/protocols/nfs/aliases
System configuration API
76 OneFS 7.2.1 OneFS API Reference
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/2/protocols/nfs/aliases?describe
View the detailed JSON schema for thisresource
GET /platform/2/protocols/nfs/aliases/<alias id>?describe
Query parameters
sort=<string>Order results by this field. The default value is id.
check=<boolean>Check for conflicts when listing exports.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
zone=<string>Filter exports by access zone.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the total number of aliasesconfigured.
N/A
resume String Specifies the value for the resumeargument for continuation requests.
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
System configuration API
NFS 77
Property Type Description Property of
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.
Operation Method and URI
Get a list of NFS advisory locks GET /platform/2/protocols/nfs/nlm/locks
View the detailed JSON schema forthis resource
GET /platform/2/protocols/nfs/nlm/locks?describe
Query parameters
sort=<string>Order results by this field.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the total number of locksavailable.
N/A
resume String Specifies the value for the resumeargument for continuation requests.
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
System configuration API
78 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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.
Operation Method and URI
Get a list of NLM lock waiters on NFS GET /platform/2/protocols/nfs/nlm/waiters
View the detailed JSON schema for thisresource
GET /platform/2/protocols/nfs/nlm/waiters?describe
Query parameters
sort=<string>Order results by this field.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the total number of lockwaiters available.
N/A
resume String Specifies the value for the resumeargument for continuation requests.
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
System configuration API
NFS 79
Property Type Description Property of
client String Specifies the client host name and IPaddress.
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.
Operation Method and URI
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>Order results by this field.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
total String Specifies the total number ofsessions to display.
N/A
System configuration API
80 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
resume String Specifies the value for the resumeargument for continuation requests.
N/A
sessions Array Specifies properties for NLMsessions.
N/A
id String Specifies the system ID assigned tothe session.
sessions
client String Specifies the client host name and IPaddress.
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.
Operation Method and URI
Get default NFS export settings GET /platform/2/protocols/nfs/settings/export
Modify default NFS export settings PUT /platform/2/protocols/nfs/settings/export
View the detailed JSON schema forthis resource
GET /platform/2/protocols/nfs/settings/export?describe
Query parameters
scope=[effective|user|default]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.
Object properties
Property Type Description Property of
total Integer Specifies the total number of exportsconfigured.
N/A
resume String Specifies the value for the resumeargument for continuation requests.
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 to
exports
System configuration API
NFS 81
Property Type Description Property of
accommodate legacy clientrequirements.
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,
exports
System configuration API
82 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
incoming UIDs are applied directly tofile operations.
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 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
readdirplus Boolean True if readdirplus requests are
enabled. Enabling this property mayimprove network performance and isonly available for NFSv3.
exports
System configuration API
NFS 83
Property Type Description Property of
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,
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
System configuration API
84 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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,
filesync, and unstable.
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.
Operation Method and URI
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
scope=[effective|user|default]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.
Object properties
Property Type Description Property of
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
System configuration API
NFS 85
Property Type Description Property of
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.
Operation Method and URI
Check NFS exports for configuration errors GET /platform/2/protocols/nfs/check
View the detailed JSON schema for thisresource
GET /platform/2/protocols/nfs/check?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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.
Operation Method and URI
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
Query parametersThere are no parameters for this resource.
System configuration API
86 OneFS 7.2.1 OneFS API Reference
Object properties
Property Type Description Property of
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.
Operation Method and URI
Reload NFS exports POST /platform/2/protocols/nfs/reload
View the detailed JSON schema for NFSexport reload
GET /platform/2/protocols/nfs/reload?describe
Query parametersThere are no parameters for this resource.
Object propertiesThere are no properties for this resource.
NFS API examplesYou can see examples for some NFS API requests.
System configuration API
NFS 87
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
201 CreatedContent-type: application/json
{"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
201 CreatedContent-type: application/json
{
System configuration API
88 OneFS 7.2.1 OneFS API Reference
"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
204 No Content Content-type: text/plain
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
204 No Content Content-type: text/plain
Modify global NFS settings
Modify the global NFS settings on the cluster.
Request example
PUT /platform/1/protocols/nfs/settings/globalAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==
{"nfsv3_enabled":true }
Response example
204 No Content Content-type: text/plain
System configuration API
NFS 89
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
204 No Content Content-type: text/plain
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 laterWindows 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
System configuration API
90 OneFS 7.2.1 OneFS API Reference
SMB version Supported operating systems
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.
Operation Method and URI
Get the SMB shares summary GET /platform/1/protocols/smb/shares-summary
View the detailed JSON schema for thisresource
GET /platform/1/protocols/smb/shares-summary?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
count Integer Specifies the total number of sharesin the system.
summary
SMB shares resource
Applies the standard collection pattern to SMB shares.
Operation Method and URI
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>
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
System configuration API
SMB 91
Operation Method and URI
View the detailed JSON schema foran SMB share object
GET /platform/1/protocols/smb/shares/<share-name>?describe
Query parameters
sort=<string>Order results by this field. The default value is id.
zone=<string>An optionally named zone to use for user and group resolution.
scope=[user|default|effective]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.
resolve_names=<Boolean>When this parameter is set to true, the group and user names are resolved.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
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
System configuration API
92 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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 accessto. This does not apply to the rootdirectory of the share.
share
System configuration API
SMB 93
Property Type Description Property of
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
id Integer Specifies the serialized form of thepersona (such as 'UID:0','USER:name', 'GID:0', 'GROUP:wheel','SID:S-1-1').
trustee
name String Specifies the persona name, whichmust be combined with type.
trustee
type String Specifies the type of persona, whichmust be combined with name.
trustee
System configuration API
94 OneFS 7.2.1 OneFS API Reference
SMB open files resource
Retrieves a listing of all files that are currently open through SMB on the queried node.
Operation Method and URI
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>Order results by this field. The default value is id.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
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
permissions String Provides the permissions on the filefor the user.
openfiles
System configuration API
SMB 95
SMB sessions resource
Retrieves a listing of all SMB sessions that are currently open on the queried node.
Operation Method and URI
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>Order results by this field. The default value is id.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
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
System configuration API
96 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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.
Operation Method and URI
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
scope=[user|default|effective]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
Property Type Description Property of
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
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
System configuration API
SMB 97
Property Type Description Property of
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
System configuration API
98 OneFS 7.2.1 OneFS API Reference
SMB global settings resource
Applies the standard system object pattern to the global SMB share settings.
Operation Method and URI
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
scope=[user|default|effective]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
Property Type Description Property of
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
System configuration API
SMB 99
Property Type Description Property of
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.
System configuration API
100 OneFS 7.2.1 OneFS API Reference
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.
Operation Method and URI
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>Order results by this field. The default value is id.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
show_all=<Boolean>Whether or not all job types are returned, including hidden job types. The defaultvalue is false.
Object properties
Property Type Description Property of
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 configuration API
System jobs overview 101
Property Type Description Property of
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.
Operation Method and URI
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>Order results by this field. The default value is id.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
show_all=<Boolean>Determines if all job types are returned, including hidden job types. The defaultvalue is false.
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the total number of policiesthat are available.
N/A
System configuration API
102 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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.
Operation Method and URI
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>
System configuration API
System jobs overview 103
Order results by this field. The default value is id.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
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>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the number of jobsavailable.
N/A
resume String Specifies the value of the resumeargument for continuation calls.
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 definedby each job implementation and canvary between the phases of the job.
jobs
System configuration API
104 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
System configuration API
System jobs overview 105
Property Type Description Property of
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.
Operation Method and URI
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 parameters
begin=<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>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
System configuration API
106 OneFS 7.2.1 OneFS API Reference
Object properties
Property Type Description Property of
total Integer Specifies the total number of reportsthat are available.
N/A
resume String Specifies the value of the resumeargument for continuation calls.
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.
Operation Method and URI
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>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
System configuration API
System jobs overview 107
Object properties
Property Type Description Property of
total Integer Specifies the total number of eventsthat are available.
N/A
resume String Specifies the value of the resumeargument for continuation calls.
N/A
id String Specifies the system-assigned ID forthe reported job event.
events
job_id Integer Specifies the system-assigned ID forthe job.
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.
Operation Method and URI
Get system job statistics GET /platform/1/job/statistics
View the detailed JSON schema for this resource. GET /platform/1/job/statistics?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
total Integer Specifies the total number of jobstatistics that are available.
N/A
System configuration API
108 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
job_id Integer Specifies the system-assigned ID forthe job.
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
System configuration API
System jobs overview 109
Property Type Description Property of
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.
System configuration API
110 OneFS 7.2.1 OneFS API Reference
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',
System configuration API
System jobs overview 111
'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
System configuration API
112 OneFS 7.2.1 OneFS API Reference
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.
System configuration API
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 "==".
The value must be in the following form: {<mm>/<dd>/<yyyy> [<HH>:<mm>] |<integer> {days | weeks | months | years} ago}
accessed_after No operator is required; every operation is set to "==".
The value must be in the following form: {<mm>/<dd>/<yyyy> [<HH>:<mm>] |<integer> {days | weeks | months | years} ago}
birth_time No operator is required; every operation is set to "==".
The value must be in the following form: {<mm>/<dd>/<yyyy> [<HH>:<mm>] |<integer> {days | weeks | months | years} ago}
birth_before No operator is required; every operation is set to "==".
The value must be in the following form: {<mm>/<dd>/<yyyy> [<HH>:<mm>] |<integer> {days | weeks | months | years} ago}
birth_after No operator is required; every operation is set to "==".
The value must be in the following form: {<mm>/<dd>/<yyyy> [<HH>:<mm>] |<integer> {days | weeks | months | years} ago}
changed_time No operator is required; every operation is set to "==".
The value must be in the following form: {<mm>/<dd>/<yyyy> [<HH>:<mm>] |<integer> {days | weeks | months | years} ago}
changed_before No operator is required; every operation is set to "==".
The value must be in the following form: {<mm>/<dd>/<yyyy> [<HH>:<mm>] |<integer> {days | weeks | months | years} ago}
changed_after No operator is required; every operation is set to "==".
The value must be in the following form: {<mm>/<dd>/<yyyy> [<HH>:<mm>] |<integer> {days | weeks | months | years} ago}
size Paired with all operators except for "!".
The value must be in the following form: An integer, followed by B, KB, MB,GB, or TB (such as 100B or 12TB).
file_type Paired with operators "==" or "!=".
The value must be in the following form: 'file', 'directory', or 'symlink'.
user_name Paired with operators "==" or "!=".
user_id Paired with operators "==" or "!=".
System configuration API
114 OneFS 7.2.1 OneFS API Reference
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.
Operation Method and URI
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>
System configuration API
SyncIQ backup and recovery overview 115
Operation Method and URI
View the detailed JSON schema for this resource GET /platform/1/sync/jobs?describe
Query parameters
sort=<string>Order results by this field. The default value is id.
state=[scheduled|running|paused|finished|failed|canceled|needs_attention|unknown]
Return only those jobs that are in the specified state.dir=[ASC|DESC]
Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
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
System configuration API
116 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
System configuration API
SyncIQ backup and recovery overview 117
Property Type Description Property of
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
System configuration API
118 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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 not
policy
System configuration API
SyncIQ backup and recovery overview 119
Property Type Description Property of
start any more replication jobs untilthis field is set to false.
Note
This field should not be changedwithout the help of Isilon TechnicalSupport.
description String Specifies a user-assigned descriptionfor the replication policy.
policy
disable_fofb Boolean Enables or disables data failover orfailback.
Note
This field should not be changedwithout the help of Isilon TechnicalSupport.
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
This field should not be changedwithout the help of Isilon TechnicalSupport.
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 logicallythrough the AND operator to form aset a criteria.
or_criteria
items Array Specifies criteria for finding a file. and_criteria
System configuration API
120 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
This field should not be changedwithout the help of Isilon TechnicalSupport.
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
System configuration API
SyncIQ backup and recovery overview 121
Property Type Description Property of
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
System configuration API
122 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
System configuration API
SyncIQ backup and recovery overview 123
Property Type Description Property of
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
System configuration API
124 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
System configuration API
SyncIQ backup and recovery overview 125
Property Type Description Property of
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
System configuration API
126 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
System configuration API
SyncIQ backup and recovery overview 127
Sync policies resource
Applies the standard collection pattern to SyncIQ replication policies.
Operation Method and URI
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>Order results by this field. The default value is id.
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]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
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>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
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 incorrectsettings. Conflicted policies will stopafter a failure until the problem is
policies
System configuration API
128 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
fixed 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
System configuration API
SyncIQ backup and recovery overview 129
Property Type Description Property of
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
target_compare_initial_sync
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
System configuration API
130 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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.
Operation Method and URI
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
Query parametersThere are no parameters for this resource.
Object propertiesThere are no properties for this resource.
Sync reports resource
Applies the standard collection pattern to SyncIQ reports.
Operation Method and URI
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>Order results by this field. The default value is id.
policy_name=<string>Return only those reports that have the specified replication policy name.
state=[scheduled|running|paused|finished|failed|canceled|needs_attention|unknown]
Return only those reports whose replication jobs are in the specified state.
System configuration API
SyncIQ backup and recovery overview 131
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 specifiednumber of days.
reports_per_policy=<integer>Return only the specified number of reports per replication policy. Ten replicationpolicies are returned by default.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
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.
reports
ads_streams_replicated String Specifies the number of streams thatare created by the replication job.
reports
block_specs_replicated Integer Specifies the number of blockspecifications that are required by thereplication job.
reports
bytes_recoverable Integer Specifies the number of bytes thatcan be recovered by the replicationjob.
reports
bytes_transferred Integer Specifies the number of bytes thatwere transferred by the replicationjob.
reports
char_specs_replicated Integer Specifies the number of characterspecification files that are replicatedby the replication job.
reports
directories_replicated Integer Specifies the number of directoriesthat are replicated by the replicationjob.
reports
System configuration API
132 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
dirs_changed Integer Specifies the number of directoriesthat were changed by the replicationjob.
reports
dirs_deleted Integer Specifies the number of directoriesthat were deleted by the replicationjob.
reports
dirs_moved Integer Specifies the number of directoriesthat were moved by the replicationjob.
reports
dirs_new Integer Specifies the number of directoriesthat were created by the replicationjob.
reports
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.
reports
end_time Integer Specifies the time that the replicationjob ended in Unix EPOCH seconds.This field is null if the replication jobhas not ended.
reports
error String Specifies the primary error messagefor the replication job.
reports
errors Array Specifies a list of error messages forthe replication job.
reports
error_checksum_files_skipped
Integer Specifies the number of files withchecksum errors that were skipped bythe replication job.
reports
error_io_files_skipped Integer Specifies the number of files with I/Oerrors that were skipped by thereplication job.
reports
error_net_files_skipped Integer Specifies the number of files withnetwork errors that were skipped bythe replication job.
reports
failed_chunks Integer Specifies the number of data chunksthat failed transmission.
reports
fifos_replicated Integer Specifies the number of First In FirstOut (FIFO) files that were replicatedby the replication job.
reports
file_data_bytes Integer Specifies the number of bytestransferred from the source to targetclusters.
reports
System configuration API
SyncIQ backup and recovery overview 133
Property Type Description Property of
files_changed Integer Specifies the number of files changedby the replication job.
reports
files_linked Integer Specifies the number of files that arelinked by the replication job.
reports
files_new Integer Specifies the number of files createdby the replication job.
reports
files_selected Integer Specifies the number of files that areselected for replication before theyare transferred.
reports
files_transferred Integer Specifies the number of files thatwere transferred by the replicationjob.
reports
files_unlinked Integer Specifies the number of files thatwere unlinked by the replication job.
reports
files_with_ads_replicated Integer Specifies the number of files withADS that were replicated by thereplication job.
reports
flipped_lins Integer Specifies the number of LINs thathave changed between replicationjobs.
reports
hard_links_replicated Integer Specifies the number of hard linksthat were replicated by the replicationjob.
reports
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.
reports
hash_exceptions_found Integer Specifies the number of hashexceptions that were found by thereplication job.
reports
id String Specifies a unique identifier for thereplication policy.
reports
job_id Integer Specifies an ID for the replication job. reports
lins_total Integer Specifies the number of LINs thatwere transferred by the replicationjob.
reports
network_bytes_to_source Integer Specifies the total number of bytessent to the source cluster by thereplication job.
reports
System configuration API
134 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
network_bytes_to_target Integer Specifies the total number of bytesthat were sent to the target cluster bythe replication job.
reports
new_files_replicated Integer Specifies the number of new files thatwere replicated by the replication job.
reports
num_retransmitted_files Integer Specifies the number of files thatwere retransmitted by the replicationjob.
reports
phases Array Specifies data for each phase of thereplication job.
reports
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
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.
policy
System configuration API
SyncIQ backup and recovery overview 135
Property Type Description Property of
Note
This field should not be changedwithout the help of Isilon TechnicalSupport.
disable_stf Boolean Enables or disables the SnapshotTracking File (STF) based data transferthrough a file system scan for OneFSversions 6.5 or greater.
Note
This field should not be changedwithout the help of Isilon TechnicalSupport.
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 logicallythrough the AND operator to form aset a criteria.
or_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, the
items
System configuration API
136 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
attribute_exists parameter must beset to true.
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
This field should not be changedwithout the help of Isilon TechnicalSupport.
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
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 completed
policy
System configuration API
SyncIQ backup and recovery overview 137
Property Type Description Property of
replication job. The value is null if noreplication jobs were successfullycompleted for the replication 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
System configuration API
138 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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_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
System configuration API
SyncIQ backup and recovery overview 139
Property Type Description Property of
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.
reports
policy_id String Specifies the system-assigned ID forthe replication policy.
reports
policy_name String Specifies the user-assigned name forthe replication policy.
reports
regular_files_replicated Integer Specifies the number of regular filesthat were replicated by the replicationjob.
reports
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.
reports
retry Integer Specifies the number of times thereplication job was retried.
reports
sockets_replicated Integer Specifies the number of sockets thatare being replicated by the replicationjob.
reports
source_bytes_recovered Integer Specifies the number of bytes thatwere recovered on the source cluster.
reports
System configuration API
140 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
source_directories_created Integer Specifies the number of directoriesthat were created on the sourcecluster.
reports
source_directories_deleted Integer Specifies the number of directoriesthat were deleted on the sourcecluster.
reports
source_directories_linked Integer Specifies the number of directoriesthat are linked on the source cluster.
reports
source_directories_unlinked
Integer Specifies the number of directoriesthat are unlinked on the sourcecluster.
reports
source_directories_visited Integer Specifies the number of sourcedirectories that were processed in theinitial replication job.
reports
source_files_deleted Integer Specifies the number of files thatwere deleted on the source cluster.
reports
source_files_linked Integer Specifies the number of files that arelinked on the source cluster.
reports
source_files_unlinked Integer Specifies the number of files that areunlinked on the source cluster.
reports
sparse_data_bytes Integer Specifies the number of sparse databytes that were transferred by thisreplication job.
reports
start_time Integer Specifies the time the replication jobstarted in Unix EPOCH seconds. Thisfield is null if the replication job hasnot started.
reports
state String Specifies the state of the replicationjob. Options include: scheduled,
running, paused, finished,
failed, canceled,
needs_attention, and unknown.
reports
subreport_count Integer Specifies the number of subreportsthat are available for the replicationjob.
reports
symlinks_replicated Integer Specifies the number of symlinks thatare replicated by the replication job.
reports
sync_type Integer Specifies the type of actionperformed by the job. Optionsinclude: invalid, legacy,
initial, incremental,
upgrade, fofb, and domainmark.
reports
System configuration API
SyncIQ backup and recovery overview 141
Property Type Description Property of
target_bytes_recovered Integer Specifies the number of bytes thatwere recovered on the target cluster.
reports
target_directories_created Integer Specifies the number of directoriesthat were created on the targetcluster.
reports
target_directories_deleted Integer Specifies the number of directoriesthat were deleted on the targetcluster.
reports
target_directories_linked Integer Specifies the number of directoriesthat are linked on the target cluster.
reports
target_directories_unlinked Integer Specifies the number of directoriesthat are unlinked on the targetcluster.
reports
target_files_deleted Integer Specifies the number of files thatwere deleted on the target cluster.
reports
target_files_linked Integer Specifies the number of files that arelinked on the target cluster.
reports
target_files_unlinked Integer Specifies the number of files that areunlinked on the target cluster.
reports
target_snapshots Array Specifies list of the target snapshotscreated by this replication job.
reports
total_chunks Integer Specifies the total number of datachunks that were transmitted by thisreplication job.
reports
total_data_bytes Integer Specifies the total number of bytestransferred by the replication job.
reports
total_files Integer Specifies the number of files thatwere changed by the replication job.
reports
total_network_bytes Integer Specifies the total number of bytesthat were sent over the network bythe replication job.
reports
total_phases Integer Specifies the total number of phasesfor the replication job.
reports
unchanged_data_bytes Integer Specifies the number of bytes thatwere unchanged by the replicationjob.
reports
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.
reports
System configuration API
142 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
updated_files_replicated Integer Specifies the number of updates filesthat are replicated by the replicationjob.
reports
user_conflict_files_skipped Integer Specifies the number of files withuser conflicts that are skipped by thereplication job.
reports
warnings Array Specifies a list of warning messagesfor the replication job.
reports
Sync reports subreports resource
Applies the standard collection pattern to subreports about replication jobs.
Operation Method and URI
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>
View the detailed JSON schema for thisresource.
GET /platform/1/sync/reports/<ID>/subreports?describe
Query parameters
sort=<string>Order results by this field. The default value is id.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). Thedefault setting is ascending.
newer_than=<integer>Return only those subreports for replication jobs that started before the specifiednumber of days.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
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
System configuration API
SyncIQ backup and recovery overview 143
Property Type Description Property of
action String Specifies the action taken by thereplication job. Options includeresync_prep, allow_write,
allow_write_revert, test, andrun.
subreports
ads_streams_replicated String Specifies the number of streams thatare created by the replication job.
subreports
block_specs_replicated Integer Specifies the number of blockspecifications that are required by thereplication job.
subreports
bytes_recoverable Integer Specifies the number of bytes thatcan be recovered by the replicationjob.
subreports
bytes_transferred Integer Specifies the number of bytes thatwere transferred by the replicationjob.
subreports
char_specs_replicated Integer Specifies the number of characterspecification files that are replicatedby the replication job.
subreports
directories_replicated Integer Specifies the number of directoriesthat are replicated by the replicationjob.
subreports
dirs_changed Integer Specifies the number of directoriesthat were changed by the replicationjob.
subreports
dirs_deleted Integer Specifies the number of directoriesthat were deleted by the replicationjob.
subreports
dirs_moved Integer Specifies the number of directoriesthat were moved by the replicationjob.
subreports
dirs_new Integer Specifies the number of directoriesthat were created by the replicationjob.
subreports
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.
subreports
end_time Integer Specifies the time that the replicationjob ended in Unix EPOCH seconds.
subreports
System configuration API
144 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
This field is null if the replication jobhas not ended.
error String Specifies the primary error messagefor the replication job.
subreports
errors Array Specifies a list of error messages forthe replication job.
subreports
error_checksum_files_skipped
Integer Specifies the number of files withchecksum errors that were skipped bythe replication job.
subreports
error_io_files_skipped Integer Specifies the number of files with I/Oerrors that were skipped by thereplication job.
subreports
error_net_files_skipped Integer Specifies the number of files withnetwork errors that were skipped bythe replication job.
subreports
failed_chunks Integer Specifies the number of data chunksthat failed transmission.
subreports
fifos_replicated Integer Specifies the number of First In FirstOut (FIFO) files that were replicatedby the replication job.
subreports
file_data_bytes Integer Specifies the number of bytestransferred from the source to targetclusters.
subreports
files_changed Integer Specifies the number of files changedby the replication job.
subreports
files_linked Integer Specifies the number of files that arelinked by the replication job.
subreports
files_new Integer Specifies the number of files createdby the replication job.
subreports
files_selected Integer Specifies the number of files that areselected for replication before theyare transferred.
subreports
files_transferred Integer Specifies the number of files thatwere transferred by the replicationjob.
subreports
files_unlinked Integer Specifies the number of files thatwere unlinked by the replication job.
subreports
files_with_ads_replicated Integer Specifies the number of files withADS that were replicated by thereplication job.
subreports
System configuration API
SyncIQ backup and recovery overview 145
Property Type Description Property of
flipped_lins Integer Specifies the number of LINs thathave changed between replicationjobs.
subreports
hard_links_replicated Integer Specifies the number of hard linksthat were replicated by the replicationjob.
subreports
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.
subreports
hash_exceptions_found Integer Specifies the number of hashexceptions that were found by thereplication job.
subreports
id String Specifies a unique identifier for thereplication policy.
subreports
job_id Integer Specifies an ID for the replication job. subreports
lins_total Integer Specifies the number of LINs thatwere transferred by the replicationjob.
subreports
network_bytes_to_source Integer Specifies the total number of bytessent to the source cluster by thereplication job.
subreports
network_bytes_to_target Integer Specifies the total number of bytesthat were sent to the target cluster bythe replication job.
subreports
new_files_replicated Integer Specifies the number of new files thatwere replicated by the replication job.
subreports
num_retransmitted_files Integer Specifies the number of files thatwere retransmitted by the replicationjob.
subreports
phases Array Specifies data for each phase of thereplication job.
subreports
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
action String Specifies the action taken by thisreplication policy. When set to copy,
source files are copied to the target
policy
System configuration API
146 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
cluster. 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.
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
This field should not be changedwithout the help of Isilon TechnicalSupport.
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
This field should not be changedwithout the help of Isilon TechnicalSupport.
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 files
policy
System configuration API
SyncIQ backup and recovery overview 147
Property Type Description Property of
with specific properties. For example,(a AND b) OR (x AND y).
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 logicallythrough the AND operator to form aset a criteria.
or_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.
policy
System configuration API
148 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
When this option is enabled, thenet.inet.ip.choose_ifa_by_ipsrc sysctlmust also be set.
Note
This field should not be changedwithout the help of Isilon TechnicalSupport.
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
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
System configuration API
SyncIQ backup and recovery overview 149
Property Type Description Property of
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_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 the
policy
System configuration API
150 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
source cluster before the snapshot isdeleted.
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 to
policy
System configuration API
SyncIQ backup and recovery overview 151
Property Type Description Property of
allow_write or
allow_write_revert.
policy_action String Specifies the action the replicationpolicy will perform. Options include:sync and copy.
subreports
policy_id String Specifies the system-assigned ID forthe replication policy.
subreports
policy_name String Specifies the user-assigned name forthe replication policy.
subreports
regular_files_replicated Integer Specifies the number of regular filesthat were replicated by the replicationjob.
subreports
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.
subreports
retry Integer Specifies the number of times thereplication job was retried.
subreports
sockets_replicated Integer Specifies the number of sockets thatare being replicated by the replicationjob.
subreports
source_bytes_recovered Integer Specifies the number of bytes thatwere recovered on the source cluster.
subreports
source_directories_created Integer Specifies the number of directoriesthat were created on the sourcecluster.
subreports
source_directories_deleted Integer Specifies the number of directoriesthat were deleted on the sourcecluster.
subreports
source_directories_linked Integer Specifies the number of directoriesthat are linked on the source cluster.
subreports
source_directories_unlinked
Integer Specifies the number of directoriesthat are unlinked on the sourcecluster.
subreports
source_directories_visited Integer Specifies the number of sourcedirectories that were processed in theinitial replication job.
subreports
source_files_deleted Integer Specifies the number of files thatwere deleted on the source cluster.
subreports
source_files_linked Integer Specifies the number of files that arelinked on the source cluster.
subreports
System configuration API
152 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
source_files_unlinked Integer Specifies the number of files that areunlinked on the source cluster.
subreports
sparse_data_bytes Integer Specifies the number of sparse databytes that were transferred by thisreplication job.
subreports
start_time Integer Specifies the time the replication jobstarted in Unix EPOCH seconds. Thisfield is null if the replication job hasnot started.
subreports
state String Specifies the state of the replicationjob. Options include: scheduled,
running, paused, finished,
failed, canceled,
needs_attention, and unknown.
subreports
symlinks_replicated Integer Specifies the number of symlinks thatare replicated by the replication job.
subreports
sync_type Integer Specifies the type of actionperformed by the job. Optionsinclude: invalid, legacy,
initial, incremental,
upgrade, fofb, and domainmark.
subreports
target_bytes_recovered Integer Specifies the number of bytes thatwere recovered on the target cluster.
subreports
target_directories_created Integer Specifies the number of directoriesthat were created on the targetcluster.
subreports
target_directories_deleted Integer Specifies the number of directoriesthat were deleted on the targetcluster.
subreports
target_directories_linked Integer Specifies the number of directoriesthat are linked on the target cluster.
subreports
target_directories_unlinked Integer Specifies the number of directoriesthat are unlinked on the targetcluster.
subreports
target_files_deleted Integer Specifies the number of files thatwere deleted on the target cluster.
subreports
target_files_linked Integer Specifies the number of files that arelinked on the target cluster.
subreports
target_files_unlinked Integer Specifies the number of files that areunlinked on the target cluster.
subreports
target_snapshots Array Specifies list of the target snapshotscreated by this replication job.
subreports
System configuration API
SyncIQ backup and recovery overview 153
Property Type Description Property of
total_chunks Integer Specifies the total number of datachunks that were transmitted by thisreplication job.
subreports
total_data_bytes Integer Specifies the total number of bytestransferred by the replication job.
subreports
total_files Integer Specifies the number of files thatwere changed by the replication job.
subreports
total_network_bytes Integer Specifies the total number of bytesthat were sent over the network bythe replication job.
subreports
total_phases Integer Specifies the total number of phasesfor the replication job.
subreports
unchanged_data_bytes Integer Specifies the number of bytes thatwere unchanged by the replicationjob.
subreports
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.
subreports
updated_files_replicated Integer Specifies the number of updates filesthat are replicated by the replicationjob.
subreports
user_conflict_files_skipped Integer Specifies the number of files withuser conflicts that are skipped by thereplication job.
subreports
warnings Array Specifies a list of warning messagesfor the replication job.
subreports
Sync reports rotate resource
Rotates the records in the database and periodically removes older reports from thesystem.
Operation Method and URI
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
System configuration API
154 OneFS 7.2.1 OneFS API Reference
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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.
Operation Method and URI
Get all target replication policies GET /platform/1/sync/target/policies
Get a target replication policy GET /platform/1/sync/target/policies/<policy-id>
View the detailed JSON schema for thisresource
GET /platform/1/sync/target/policies?describe
Query parameters
sort=<string>Order results by this field. The default value is id.
target_path=<string>Return only those replication policies with the specified target path.
dir=[ASC|DESC]Directions for the sort order are ascending ( ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the total number ofreplication policies available.
N/A
resume String Specifies the value of the resumeargument for continuation calls.
N/A
failover_failback_state String Specifies the condition of thereplication policy with respect to datafailover/failback. Options include:writes_disabled,
policies
System configuration API
SyncIQ backup and recovery overview 155
Property Type Description Property of
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,
running, paused, finished,
failed, canceled,
needs_attention, and unknown.
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
name String Specifies the user-assigned name ofthe replication policy.
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
System configuration API
156 OneFS 7.2.1 OneFS API Reference
Sync target policies cancel resource
Cancels the most recent replication job for a replication policy from the target cluster.
Operation Method and URI
Cancel the most recent replication job POST /platform/1/sync/target/policies/<policy>/cancel
View the detailed JSON schema for thisresource.
GET /platform/1/sync/target/policies/<policy>/cancel?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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.
Operation Method and URI
Get all replication target reports GET /platform/1/sync/target/reports
Get a replication target report GET /platform/1/sync/target/reports/<report-id>
View the detailed JSON schema for thisresource.
GET /platform/1/sync/target/reports?describe
Query parameters
sort=<string>Order results by this field. The default value is id.
policy_name=<string>Return only those target reports that have the specified policy name.
state=[scheduled|running|paused|finished|failed|canceled|needs_attention|unknown]
Return only those target 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 with replication jobs that started before the specifiednumber of days.
reports_per_policy=<integer>
System configuration API
SyncIQ backup and recovery overview 157
Return only the specified number of reports per replication policy. Ten reports arereturned by default.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
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.
reports
ads_streams_replicated String Specifies the number of streams thatare created by the replication job.
reports
block_specs_replicated Integer Specifies the number of blockspecifications that are required by thereplication job.
reports
bytes_recoverable Integer Specifies the number of bytes thatcan be recovered by the replicationjob.
reports
bytes_transferred Integer Specifies the number of bytes thatwere transferred by the replicationjob.
reports
char_specs_replicated Integer Specifies the number of characterspecification files that are replicatedby the replication job.
reports
directories_replicated Integer Specifies the number of directoriesthat are replicated by the replicationjob.
reports
dirs_changed Integer Specifies the number of directoriesthat were changed by the replicationjob.
reports
dirs_deleted Integer Specifies the number of directoriesthat were deleted by the replicationjob.
reports
System configuration API
158 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
dirs_moved Integer Specifies the number of directoriesthat were moved by the replicationjob.
reports
dirs_new Integer Specifies the number of directoriesthat were created by the replicationjob.
reports
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.
reports
end_time Integer Specifies the time that the replicationjob ended in Unix EPOCH seconds.This field is null if the replication jobhas not ended.
reports
error String Specifies the primary error messagefor the replication job.
reports
errors Array Specifies a list of error messages forthe replication job.
reports
error_checksum_files_skipped
Integer Specifies the number of files withchecksum errors that were skipped bythe replication job.
reports
error_io_files_skipped Integer Specifies the number of files with I/Oerrors that were skipped by thereplication job.
reports
error_net_files_skipped Integer Specifies the number of files withnetwork errors that were skipped bythe replication job.
reports
failed_chunks Integer Specifies the number of data chunksthat failed transmission.
reports
fifos_replicated Integer Specifies the number of First In FirstOut (FIFO) files that were replicatedby the replication job.
reports
file_data_bytes Integer Specifies the number of bytestransferred from the source to targetclusters.
reports
files_changed Integer Specifies the number of files changedby the replication job.
reports
files_linked Integer Specifies the number of files that arelinked by the replication job.
reports
System configuration API
SyncIQ backup and recovery overview 159
Property Type Description Property of
files_new Integer Specifies the number of files createdby the replication job.
reports
files_selected Integer Specifies the number of files that areselected for replication before theyare transferred.
reports
files_transferred Integer Specifies the number of files thatwere transferred by the replicationjob.
reports
files_unlinked Integer Specifies the number of files thatwere unlinked by the replication job.
reports
files_with_ads_replicated Integer Specifies the number of files withADS that were replicated by thereplication job.
reports
flipped_lins Integer Specifies the number of LINs thathave changed between replicationjobs.
reports
hard_links_replicated Integer Specifies the number of hard linksthat were replicated by the replicationjob.
reports
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.
reports
hash_exceptions_found Integer Specifies the number of hashexceptions that were found by thereplication job.
reports
id String Specifies a unique identifier for thereplication policy.
reports
job_id Integer Specifies an ID for the replication job. reports
lins_total Integer Specifies the number of LINs thatwere transferred by the replicationjob.
reports
network_bytes_to_source Integer Specifies the total number of bytessent to the source cluster by thereplication job.
reports
network_bytes_to_target Integer Specifies the total number of bytesthat were sent to the target cluster bythe replication job.
reports
new_files_replicated Integer Specifies the number of new files thatwere replicated by the replication job.
reports
System configuration API
160 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
num_retransmitted_files Integer Specifies the number of files thatwere retransmitted by the replicationjob.
reports
phases Array Specifies data for each phase of thereplication job.
reports
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_action String Specifies the action the replicationpolicy will perform. Options include:sync and copy.
reports
policy_id String Specifies the system-assigned ID forthe replication policy.
reports
policy_name String Specifies the user-assigned name forthe replication policy.
reports
regular_files_replicated Integer Specifies the number of regular filesthat were replicated by the replicationjob.
reports
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.
reports
retry Integer Specifies the number of times thereplication job was retried.
reports
sockets_replicated Integer Specifies the number of sockets thatare being replicated by the replicationjob.
reports
source_bytes_recovered Integer Specifies the number of bytes thatwere recovered on the source cluster.
reports
source_directories_created Integer Specifies the number of directoriesthat were created on the sourcecluster.
reports
source_directories_deleted Integer Specifies the number of directoriesthat were deleted on the sourcecluster.
reports
source_directories_linked Integer Specifies the number of directoriesthat are linked on the source cluster.
reports
System configuration API
SyncIQ backup and recovery overview 161
Property Type Description Property of
source_directories_unlinked
Integer Specifies the number of directoriesthat are unlinked on the sourcecluster.
reports
source_directories_visited Integer Specifies the number of sourcedirectories that were processed in theinitial replication job.
reports
source_files_deleted Integer Specifies the number of files thatwere deleted on the source cluster.
reports
source_files_linked Integer Specifies the number of files that arelinked on the source cluster.
reports
source_files_unlinked Integer Specifies the number of files that areunlinked on the source cluster.
reports
sparse_data_bytes Integer Specifies the number of sparse databytes that were transferred by thisreplication job.
reports
start_time Integer Specifies the time the replication jobstarted in Unix EPOCH seconds. Thisfield is null if the replication job hasnot started.
reports
state String Specifies the state of the replicationjob. Options include: scheduled,
running, paused, finished,
failed, canceled,
needs_attention, and unknown.
reports
subreport_count Integer Specifies the number of subreportsthat are available for the replicationjob.
reports
symlinks_replicated Integer Specifies the number of symlinks thatare replicated by the replication job.
reports
sync_type Integer Specifies the type of actionperformed by the job. Optionsinclude: invalid, legacy,
initial, incremental,
upgrade, fofb, and domainmark.
reports
target_bytes_recovered Integer Specifies the number of bytes thatwere recovered on the target cluster.
reports
target_directories_created Integer Specifies the number of directoriesthat were created on the targetcluster.
reports
target_directories_deleted Integer Specifies the number of directoriesthat were deleted on the targetcluster.
reports
System configuration API
162 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
target_directories_linked Integer Specifies the number of directoriesthat are linked on the target cluster.
reports
target_directories_unlinked Integer Specifies the number of directoriesthat are unlinked on the targetcluster.
reports
target_files_deleted Integer Specifies the number of files thatwere deleted on the target cluster.
reports
target_files_linked Integer Specifies the number of files that arelinked on the target cluster.
reports
target_files_unlinked Integer Specifies the number of files that areunlinked on the target cluster.
reports
target_path String Specifies the absolute file systempath on the target cluster for thereplication job.
reports
target_snapshots Array Specifies list of the target snapshotscreated by this replication job.
reports
total_chunks Integer Specifies the total number of datachunks that were transmitted by thisreplication job.
reports
total_data_bytes Integer Specifies the total number of bytestransferred by the replication job.
reports
total_files Integer Specifies the number of files thatwere changed by the replication job.
reports
total_network_bytes Integer Specifies the total number of bytesthat were sent over the network bythe replication job.
reports
total_phases Integer Specifies the total number of phasesfor the replication job.
reports
unchanged_data_bytes Integer Specifies the number of bytes thatwere unchanged by the replicationjob.
reports
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.
reports
updated_files_replicated Integer Specifies the number of updates filesthat are replicated by the replicationjob.
reports
System configuration API
SyncIQ backup and recovery overview 163
Property Type Description Property of
user_conflict_files_skipped Integer Specifies the number of files withuser conflicts that are skipped by thereplication job.
reports
warnings Array Specifies a list of warning messagesfor the replication job.
reports
Sync target reports subreports resource
Applies the standard collection pattern to SyncIQ subreports for replication jobs on thetarget cluster.
Operation Method and URI
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>
View the detailed JSON schema for thisresource.
GET /platform/1/sync/target/reports/<ID>/subreports?describe
Query parameters
sort=<string>Order results by this field. The default value is id.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). Thedefault setting is ascending.
state=[scheduled|running|paused|finished|failed|canceled|needs_attention|unknown]
Return only those subreports whose replication jobs are in the specified state.
newer_than=<integer>Return only those subreports for replication jobs that started before the specifiednumber of days.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
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
System configuration API
164 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
action String Specifies the action taken by thereplication job. Options includeresync_prep, allow_write,
allow_write_revert, test, andrun.
subreports
ads_streams_replicated String Specifies the number of streams thatare created by the replication job.
subreports
block_specs_replicated Integer Specifies the number of blockspecifications that are required by thereplication job.
subreports
bytes_recoverable Integer Specifies the number of bytes thatcan be recovered by the replicationjob.
subreports
bytes_transferred Integer Specifies the number of bytes thatwere transferred by the replicationjob.
subreports
char_specs_replicated Integer Specifies the number of characterspecification files that are replicatedby the replication job.
subreports
directories_replicated Integer Specifies the number of directoriesthat are replicated by the replicationjob.
subreports
dirs_changed Integer Specifies the number of directoriesthat were changed by the replicationjob.
subreports
dirs_deleted Integer Specifies the number of directoriesthat were deleted by the replicationjob.
subreports
dirs_moved Integer Specifies the number of directoriesthat were moved by the replicationjob.
subreports
dirs_new Integer Specifies the number of directoriesthat were created by the replicationjob.
subreports
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.
subreports
end_time Integer Specifies the time that the replicationjob ended in Unix EPOCH seconds.
subreports
System configuration API
SyncIQ backup and recovery overview 165
Property Type Description Property of
This field is null if the replication jobhas not ended.
error String Specifies the primary error messagefor the replication job.
subreports
errors Array Specifies a list of error messages forthe replication job.
subreports
error_checksum_files_skipped
Integer Specifies the number of files withchecksum errors that were skipped bythe replication job.
subreports
error_io_files_skipped Integer Specifies the number of files with I/Oerrors that were skipped by thereplication job.
subreports
error_net_files_skipped Integer Specifies the number of files withnetwork errors that were skipped bythe replication job.
subreports
failed_chunks Integer Specifies the number of data chunksthat failed transmission.
subreports
fifos_replicated Integer Specifies the number of First In FirstOut (FIFO) files that were replicatedby the replication job.
subreports
file_data_bytes Integer Specifies the number of bytestransferred from the source to targetclusters.
subreports
files_changed Integer Specifies the number of files changedby the replication job.
subreports
files_linked Integer Specifies the number of files that arelinked by the replication job.
subreports
files_new Integer Specifies the number of files createdby the replication job.
subreports
files_selected Integer Specifies the number of files that areselected for replication before theyare transferred.
subreports
files_transferred Integer Specifies the number of files thatwere transferred by the replicationjob.
subreports
files_unlinked Integer Specifies the number of files thatwere unlinked by the replication job.
subreports
files_with_ads_replicated Integer Specifies the number of files withADS that were replicated by thereplication job.
subreports
System configuration API
166 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
flipped_lins Integer Specifies the number of LINs thathave changed between replicationjobs.
subreports
hard_links_replicated Integer Specifies the number of hard linksthat were replicated by the replicationjob.
subreports
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.
subreports
hash_exceptions_found Integer Specifies the number of hashexceptions that were found by thereplication job.
subreports
id String Specifies a unique identifier for thereplication policy.
subreports
job_id Integer Specifies an ID for the replication job. subreports
lins_total Integer Specifies the number of LINs thatwere transferred by the replicationjob.
subreports
network_bytes_to_source Integer Specifies the total number of bytessent to the source cluster by thereplication job.
subreports
network_bytes_to_target Integer Specifies the total number of bytesthat were sent to the target cluster bythe replication job.
subreports
new_files_replicated Integer Specifies the number of new files thatwere replicated by the replication job.
subreports
num_retransmitted_files Integer Specifies the number of files thatwere retransmitted by the replicationjob.
subreports
phases Array Specifies data for each phase of thereplication job.
subreports
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_action String Specifies the action the replicationpolicy will perform. Options include:sync and copy.
subreports
System configuration API
SyncIQ backup and recovery overview 167
Property Type Description Property of
policy_id String Specifies the system-assigned ID forthe replication policy.
subreports
policy_name String Specifies the user-assigned name forthe replication policy.
subreports
regular_files_replicated Integer Specifies the number of regular filesthat were replicated by the replicationjob.
subreports
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.
subreports
retry Integer Specifies the number of times thereplication job was retried.
subreports
sockets_replicated Integer Specifies the number of sockets thatare being replicated by the replicationjob.
subreports
source_bytes_recovered Integer Specifies the number of bytes thatwere recovered on the source cluster.
subreports
source_directories_created Integer Specifies the number of directoriesthat were created on the sourcecluster.
subreports
source_directories_deleted Integer Specifies the number of directoriesthat were deleted on the sourcecluster.
subreports
source_directories_linked Integer Specifies the number of directoriesthat are linked on the source cluster.
subreports
source_directories_unlinked
Integer Specifies the number of directoriesthat are unlinked on the sourcecluster.
subreports
source_directories_visited Integer Specifies the number of sourcedirectories that were processed in theinitial replication job.
subreports
source_files_deleted Integer Specifies the number of files thatwere deleted on the source cluster.
subreports
source_files_linked Integer Specifies the number of files that arelinked on the source cluster.
subreports
source_files_unlinked Integer Specifies the number of files that areunlinked on the source cluster.
subreports
sparse_data_bytes Integer Specifies the number of sparse databytes that were transferred by thisreplication job.
subreports
System configuration API
168 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
start_time Integer Specifies the time the replication jobstarted in Unix EPOCH seconds. Thisfield is null if the replication job hasnot started.
subreports
state String Specifies the state of the replicationjob. Options include: scheduled,
running, paused, finished,
failed, canceled,
needs_attention, and unknown.
subreports
subreport_count Integer Specifies the number of subreportsthat are available for the replicationjob.
subreports
symlinks_replicated Integer Specifies the number of symlinks thatare replicated by the replication job.
subreports
sync_type Integer Specifies the type of actionperformed by the job. Optionsinclude: invalid, legacy,
initial, incremental,
upgrade, fofb, and domainmark.
subreports
target_bytes_recovered Integer Specifies the number of bytes thatwere recovered on the target cluster.
subreports
target_directories_created Integer Specifies the number of directoriesthat were created on the targetcluster.
subreports
target_directories_deleted Integer Specifies the number of directoriesthat were deleted on the targetcluster.
subreports
target_directories_linked Integer Specifies the number of directoriesthat are linked on the target cluster.
subreports
target_directories_unlinked Integer Specifies the number of directoriesthat are unlinked on the targetcluster.
subreports
target_files_deleted Integer Specifies the number of files thatwere deleted on the target cluster.
subreports
target_files_linked Integer Specifies the number of files that arelinked on the target cluster.
subreports
target_files_unlinked Integer Specifies the number of files that areunlinked on the target cluster.
subreports
target_path String Specifies the absolute file systempath on the target cluster for thereplication job.
subreports
System configuration API
SyncIQ backup and recovery overview 169
Property Type Description Property of
target_snapshots Array Specifies list of the target snapshotscreated by this replication job.
subreports
total_chunks Integer Specifies the total number of datachunks that were transmitted by thisreplication job.
subreports
total_data_bytes Integer Specifies the total number of bytestransferred by the replication job.
subreports
total_files Integer Specifies the number of files thatwere changed by the replication job.
subreports
total_network_bytes Integer Specifies the total number of bytesthat were sent over the network bythe replication job.
subreports
total_phases Integer Specifies the total number of phasesfor the replication job.
subreports
unchanged_data_bytes Integer Specifies the number of bytes thatwere unchanged by the replicationjob.
subreports
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.
subreports
updated_files_replicated Integer Specifies the number of updates filesthat are replicated by the replicationjob.
subreports
user_conflict_files_skipped Integer Specifies the number of files withuser conflicts that are skipped by thereplication job.
subreports
warnings Array Specifies a list of warning messagesfor the replication job.
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.
Operation Method and URI
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/
System configuration API
170 OneFS 7.2.1 OneFS API Reference
Operation Method and URI
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>Order results by this field. The default value is id.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
type=[bandwidth|file_count|cpu]Specifies the type of rule to delete.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the total number of rulesavailable.
N/A
resume String Specifies the value of the resumeargument to be used for continuationcalls.
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,
thursday, friday, saturday, orsunday.
rules
System configuration API
SyncIQ backup and recovery overview 171
Property Type Description Property of
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.
Operation Method and URI
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
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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 replicationpolicies unless otherwise specifiedwhen the replication policy is created.
N/A
System configuration API
172 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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.
Operation Method and URI
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.
System configuration API
SyncIQ backup and recovery overview 173
Object properties
Property Type Description Property of
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.
Operation Method and URI
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
Property Type Description Property of
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
System configuration API
174 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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, }
System configuration API
SyncIQ backup and recovery overview 175
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==
System configuration API
176 OneFS 7.2.1 OneFS API Reference
{ '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==
System configuration API
SyncIQ backup and recovery overview 177
Response example
201 CreatedContent-type: application/json, Allow: 'DELETE, GET, POST, HEAD'
{ "id":"a33006f364842eefb629fc6b95c92559" }
Cancel a target replication policy
You can cancel a replication policy from the target cluster.
Request example
POST /platform/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,
System configuration API
178 OneFS 7.2.1 OneFS API Reference
'thursday': True, 'sunday': False, 'saturday': False } }
Response example
201 CreatedContent-type: application/json, Allow: 'DELETE, GET, POST, HEAD'
{ "id":"fc-0" }
Modify a replication policy rule.
You can modify replication policy rules on the system.
Request example
PUT /platform/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.
System configuration API
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.
Operation Method and URI
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
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
180 OneFS 7.2.1 OneFS API Reference
Deduplication settings resource
Applies the standard system object pattern to OneFS deduplication settings.
Operation Method and URI
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
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
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.
Operation Method and URI
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>Order results by this field. The default value is id.
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]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
System configuration API
Deduplication overview 181
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
resume String Specifies the value of the resumeargument for continuation calls.
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' ]}
System configuration API
182 OneFS 7.2.1 OneFS API Reference
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/protocols/hdfs/racks?describe
View the detailed JSON schema for thisresource
GET /platform/1/protocols/hdfs/racks/<rack ID>?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
total Integer Specifies the number of HDFS rackson the cluster.
N/A
resume String Specifies the value for the resumeargument for continuation requests.
N/A
System configuration API
Hadoop overview 183
Property Type Description Property of
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.
Operation Method and URI
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>
View the detailed JSON schema forthis resource
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
Property Type Description Property of
total Integer Specifies the number of proxyusersconfigured.
N/A
System configuration API
184 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
resume String Specifies the value for the resumeargument for continuation requests.
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.
Operation Method and URI
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>
View the detailed JSON schema forthis resource
GET /platform/1/protocols/hdfs/proxyusers/<NAME>/members?describe
Query parameters
zone=<string>Specify an access zone for the user.
System configuration API
Hadoop overview 185
Object properties
Property Type Description Property of
resume String Specifies the value for the resumeargument to be used for continuationrequests.
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
name String Specifies the persona name, whichmust be combined with type.
members
type String Specifies the type of persona, whichmust be combined with name.
members
HDFS settings resource
Modify or retrieve information about global HDFS settings.
Operation Method and URI
Get the global HDFS settings GET /platform/1/protocols/hdfs/settings
Modify the global HDFS settings PUT /platform/1/protocols/hdfs/settings
View the detailed JSON schema for thisresource
GET /platform/1/protocols/hdfs/settings?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
186 OneFS 7.2.1 OneFS API Reference
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
201 CreatedContent-type: application/json
{"id" : "1-5-21-4224731515-2571109568-2823010237-1003"}
Modify an HDFS rack
You can modify the properties for an HDFS rack.
Request 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"}
Response exampleNo message body is returned for this request.
204 No Content Content-type: text/plain, Allow: 'GET, PUT, HEAD'
Modify global HDFS settings
You can modify the properties for global HDFS settings.
Request example
PUT /platform/1/protocols/hdfs/settings/Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==
{ "default_checksum_type":"crc32"}
System configuration API
Hadoop overview 187
Response exampleNo message body is returned for this request.
204 No Content Content-type: text/plain, Allow: 'GET, PUT, HEAD'
Create HDFS proxyusers
Create an HDFS proxyuser.
Request example
POST /platform/1/protocols/hdfs/proxyusersAuthorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==
{"name":"proxy_user_test"}
Response example
201 CreatedContent-type: application/json
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
204 No Content Content-type: text/plain
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
201 CreatedContent-type: application/json
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==
{}
System configuration API
188 OneFS 7.2.1 OneFS API Reference
Response example
204 No Content Content-type: text/plain
IP address poolsWithin a subnet, you can partition a cluster's external network interfaces into pools of IPaddress ranges. The pools enable you to customize your storage network to servedifferent groups of users. You can configure subnets in IPv4 or IPv6.
You can associate IP address pools with a node, a group of nodes, or NIC ports. Forexample, you can set up one subnet for storage nodes and another subnet for acceleratornodes. Similarly, you can allocate ranges of IP addresses on a subnet to different teams,such as engineering and sales. These options help you create a storage topology thatmatches the demands of your network.
In addition, network provisioning rules streamline the setup of external connections.After you configure the rules with network settings, you can apply the settings to newnodes.
As a standard feature, the OneFS SmartConnect module balances connections amongnodes by using a round-robin policy with static IP addresses and one IP address pool foreach subnet. Activating a SmartConnect Advanced license adds features, such asdefining IP address pools to support multiple DNS zones.
Cluster external IPs resourceThis resource contains the external IP addresses for the cluster.
Operation Method and URI
Get external IP addresses for the cluster GET /platform/2/cluster/external-ips
View the detailed JSON schema for this resource GET /platform/2/cluster/external-ips?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
items Array The list of external IP addresses forthe cluster.
N/A
Structure of the file systemOneFS presents all the nodes in a cluster as a global namespace—that is, as the defaultfile share, /ifs.
In the file system, directories are inode number links. An inode contains file metadataand an inode number, which identifies a file's location. OneFS dynamically allocatesinodes, and there is no limit on the number of inodes.
To distribute data among nodes, OneFS sends messages with a globally routable blockaddress through the cluster's internal network. The block address identifies the node andthe drive storing the block of data.
System configuration API
IP address pools 189
Note
It is recommended that you do not save data to the root /ifs file path but in directories
below /ifs. The design of your data storage structure should be planned carefully. A
well-designed directory optimizes cluster performance and cluster administration.
File system settings character-encodings resourceView and modify settings for character-encodings.
Operation Method and URI
Retrieve default character-encodings settingsfor the cluster
GET /platform/1/filesystem/settings/character-encodings
Modify the default character-encodingssettings for the cluster
PUT /platform/1/filesystem/settings/character-encodings
View the detailed JSON schema for thisresource
GET /platform/1/filesystem/settings/character-encodings?describe
Property Type Description Property of
total Integer Specifies the total number of itemsavailable.
N/A
character-encodings String Specifies the properties for characterencodings.
N/A
default-encoding String Specifies the default characterencoding.
character-encodings
encodings Array Specifies the list of supportedencoding values.
character-encodings
current-encoding String Specifies the current characterencoding.
character-encodings
File system settings access-time resourceView and modify settings for the file system access-time.
Operation Method and URI
Retrieve default access-time settings GET /platform/1/filesystem/settings/access-time
Modify the default access-time settings PUT /platform/1/filesystem/settings/access-time
View the detailed JSON schema for thisresource
GET /platform/1/filesystem/settings/access-time?describe
Query parametersThere are no query parameters for this resource.
System configuration API
190 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
total Integer Specifies the total number of itemsavailable.
N/A
access-time String Specifies properties for access-timesettings.
N/A
enabled Boolean Determines if the access-timetracking is enabled.
access-time
precision String Specifies the access time tracked inseconds for each enabled cluster file.
settings
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.
Operation Method and URI
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
Query parametersThere are no query parameters for this resource.
System configuration API
File pools 191
Object properties
Property Type Description Property of
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
be set as a string, Boolean, object, ornull.
actions
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.
Operation Method and URI
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
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
total Integer Specifies the number of file poolpolicies on the cluster.
N/A
resume String Specifies the value for the resumeargument for continuation requests.
N/A
policies Object Specifies a file pool policy. N/A
System configuration API
192 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
actions Array Specifies a list of actions that will betaken on matching files.
policies
action_param Object Specifies parameters for the actionthat vary by the definedaction_type. This parameter can
be set as a string, Boolean, object, ornull.
actions
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
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.
file_matching_pattern
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
System configuration API
File pools 193
Property Type Description Property of
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,
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
accessed_time, birth_time,
changed_time, or
metadata_changed_time.
and_criteria
value String orInteger
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.
Operation Method and URI
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
Query parametersThere are no query parameters for this resource.
System configuration API
194 OneFS 7.2.1 OneFS API Reference
Object properties
Property Type Description Property of
total Integer Specifies the number of file pooltemplates on the cluster.
N/A
resume String Specifies the value for the resumeargument for continuation requests.
N/A
templates Object Specifies a file pool policy template. N/A
actions Array Specifies a list of actions that will betaken on matching files.
templates
action_param Object Specifies parameters for the actionthat vary by the definedaction_type. This parameter can
be set as a string, Boolean, object, ornull.
actions
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
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.
file_matching_pattern
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 the
and_criteria
System configuration API
File pools 195
Property Type Description Property of
type parameter is set to either nameor path.
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,
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
accessed_time, birth_time,
changed_time, or
metadata_changed_time.
and_criteria
value String orInteger
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.
System configuration API
196 OneFS 7.2.1 OneFS API Reference
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" }
Response exampleNo message body is returned for this request.
204 No Content Content-type: text/plain, Allow: 'GET, PUT, HEAD'
System configuration API
File pools 197
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" }
Response exampleNo message body is returned for this request.
204 No Content Content-type: text/plain, Allow: 'GET, PUT, HEAD'
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/worm/domains?describe
View the detailed JSON schema for thisresource
GET /platform/1/worm/domains?describe
System configuration API
198 OneFS 7.2.1 OneFS API Reference
Query parameters
sort=<string>Order results by this field. The default value is id.
dir=[ASC|DESC]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be combined with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the number of SmartLockdomains on the cluster.
N/A
resume String Specifies the value for the resumeargument for continuation requests.
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
System configuration API
SmartLock overview 199
Property Type Description Property of
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
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 domains
domains
System configuration API
200 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
can be created on complianceclusters.
SmartLock settings resource
Modify or retrieve information about SmartLock global settings.
Operation Method and URI
Get SmartLock global settings GET /platform/1/worm/settings
Modify SmartLock global settings PUT /platform/1/worm/settings
View the detailed JSON schema for thisresource
GET /platform/1/worm/settings?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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
201 Created Content-type: application/json
{
System configuration API
SmartLock overview 201
"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"}
Response exampleNo message body is returned for this request.
204 No Content Content-type: text/plain
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" : }
Response exampleNo message body is returned for this request.
204 No Content Content-type: text/plain
Storage pools overviewOneFS organizes different node types into separate node pools, and you can organizethese node pools additionally 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. File data and metadata is stored across the entire cluster so 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 functions such asautoprovisioning, node class and SSD compatibilities, virtual hot spare (VHS), SSDstrategies, global namespace acceleration (GNA), L3 cache, and storage tiers.
When you activate a SmartPools license, you can manage your data set to improve theperformance of your cluster. With a SmartPools license, additional functions becomeavailable, including custom file pool policies and spillover management.
The following table summarizes storage pool functions based on whether a SmartPoolslicense is active.
System configuration API
202 OneFS 7.2.1 OneFS API Reference
Function Inactive SmartPoolslicense
Active SmartPoolslicense
Automatic storage pool provisioning Yes Yes
Node class compatibilities (nodeequivalency)
Yes Yes
SSD compatibilities Yes Yes
Virtual hot spare Yes Yes
SSD strategies Yes Yes
L3 cache Yes Yes
Tiers Yes Yes
GNA Yes Yes
File pool policies No Yes
Spillover management No Yes
Storage pools resourcesYou can retrieve, create, modify, or delete system storage pool settings andconfigurations.
Storage pool settings resource
Modify or retrieve information about OneFS storage pools.
Operation Method and URI
Get storage pool settings GET /platform/1/storagepool/settings
Modify storage pool settings PUT /platform/1/storagepool/settings
View the detailed JSON schema for thisresource
GET /platform/1/storagepool/settings?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
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 manually
settings
System configuration API
Storage pools overview 203
Property Type Description Property of
managed flag set will have their I/Ooptimization settings set by theSmartPools job.
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
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
System configuration API
204 OneFS 7.2.1 OneFS API Reference
Storage pools tiers resource
Applies the standard collection pattern to OneFS tiers.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/storagepool/tiers?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
Storage pools overview 205
Property Type Description Property of
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/storagepool/nodepools?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
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 a
usage
System configuration API
206 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
virtual hot spare is taken intoaccount.
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
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 resource
Applies the standard collection pattern to OneFS storage pools. You can supply atoplevels argument to filter out node pools within tiers.
Operation Method and URI
Get information for all storage pools GET /platform/1/storagepool/storagepools
View the detailed JSON schema for thisresource
GET /platform/1/storagepool/storagepools?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
Storage pools overview 207
Property Type Description Property of
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
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 suggested protection resource
Retrieve information about the suggested protection policy for a storage pool.
Operation Method and URI
Get information about the suggestedprotection policy
GET /platform/1/storagepool/suggested_protection/<NID>
View detailed JSON schema for thisresource
GET /platform/1/storagepool/suggested_protection/<NID>?describe
Query parametersThere are no parameters for this resource.
System configuration API
208 OneFS 7.2.1 OneFS API Reference
Object properties
Property Type Description Property of
suggested_protection String Specifies the suggested protectionpolicy.
suggested_protection
Storagepool compatibilities SSD active resource
Create, delete, or view active SSD compatibilities
Operation Method and URI
Get a list of active ssd compatibilities GET /platform/1/storagepool/compatibilities/ssd/active
Get an ssd compatibility by ID GET /platform/1/storagepool/compatibilities/ssd/active/<ID>
Create a new ssd compatibility POST /platform/1/storagepool/compatibilities/ssd/active
Delete an ssd compatibility DELETE /platform/1/storagepool/compatibilities/ssd/active/<ID>
View the detailed JSON schema for thisresource
GET /platform/1/storagepool/compatibilities/ssd/active?describe
View the detailed JSON schema for thisresource
GET /platform/1/storagepool/compatibilities/ssd/active/<ID>?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
total Integer Specifies the total number of itemsavailable.
N/A
active Object Specifies the properties for activessds.
N/A
class_2 String Specifies the optional second classthat is turned on in an ssdcompatibility.
active
class_1 String Specifies the node class of an ssdcompatibility. Required in a POSToperation.
active
id Integer Specifies the system-assigned ID forthe ssd compatibility.
active
assess Boolean Determines if an ssd compatibilitycan be created, but does not createthe compatibility.
N/A
System configuration API
Storage pools overview 209
Storagepool compatibilities SSD available resource
View a list of available ssd compatibilities.
Operation Method and URI
Get a list of available ssd compatibilities GET /platform/1/storagepool/compatibilities/ssd/available
View the detailed JSON schema for thisresource
GET /platform/1/storagepool/compatibilities/ssd/available?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
total Integer Specifies the total number of itemsavailable.
N/A
class String Specifies the node class of an ssdcompatibility.
available
Storagepool compatibilities class available resource
View a list of available class compatibilities.
Operation Method and URI
Get a list of available class compatibilities GET /platform/1/storagepool/compatibilities/class/available
View the detailed JSON schema for thisresource
GET /platform/1/storagepool/compatibilities/class/available?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
total Integer Specifies the total number of itemsavailable.
N/A
class_1 String Specifies the first node class of anavailable class compatibility.
available
class_2 String Specifies the second node class of anavailable class compatibility.
available
System configuration API
210 OneFS 7.2.1 OneFS API Reference
Storage pool compatibilities class active resource
View or create a storage pool compatibility.
Operation Method and URI
Get all storage pool compatibilities GET /platform/1/storagepool/compatibilities/class/active
Get a storage pool compatibility by ID GET /platform/1/storagepool/compatibilities/class/active/<ID>
Post storage pool compatibilities POST /platform/1/storagepool/compatibilities/class/active
Delete a storage pool compatibility by ID DELETE /platform/1/storagepool/compatibilities/class/active/<ID>
View the detailed JSON schema for thisresource
GET /platform/1/storagepool/compatibilities/class/active?describe
View the detailed JSON schema for thisresource
GET /platform/1/storagepool/compatibilities/class/active/<ID>?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
total Integer Specifies the total number of itemsavailable.
N/A
active String Specifies the properties for the activeproperties.
N/A
class_2 String Specifies the second class in anactive compatibility. Required in aPOST operation.
active
class_1 String Specifies the first class in an activecompatibility. Required in a POSToperation.
active
id Integer Specifies the system-assigned ID forthe active compatibility.
active
assess Boolean Determines if a compatibility ispossible, but does not trigger thecreation of a compatibility.
N/A
Storage pool status resource
Retrieves the heath status of the overall OneFS pool system.
Operation Method and URI
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
System configuration API
Storage pools overview 211
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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.
System configuration API
212 OneFS 7.2.1 OneFS API Reference
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' }
Response exampleNo message body is returned for this request.
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==
System configuration API
Storage pools overview 213
{ "tier": myTier }
Response exampleNo message body is returned for this request.
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 whenmodifying 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' }
System configuration API
214 OneFS 7.2.1 OneFS API Reference
Response exampleNo message body is returned for this request.
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 for tracking—and sometimes limiting—the amount of storage that a user, group, orproject consumes. Quotas are a useful way of ensuring that a user or department doesnot infringe on the storage that is allocated to other users or departments. In some quotaimplementations, writes beyond the defined space are denied, and in other cases, asimple notification is sent.
Note
Do not apply quotas to /ifs/.ifsvar/ or its subdirectories. If you limit the size of
the /ifs/.ifsvar/ directory through a quota, and the directory reaches its limit, jobs suchas File-System Analytics fail. A quota blocks older job reports from being deleted fromthe /ifs/.ifsvar/ subdirectories to make room for newer reports.
The SmartQuotas module requires a separate license. For more information about theSmartQuotas 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.
Operation Method and URI
Get license information for SmartQuotas GET /platform/1/quota/license
View the detailed JSON schema for this resource GET /platform/1/quota/license?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
duration Integer Specifies the total duration inseconds for temporary licenses.
N/A
System configuration API
SmartQuotas overview 215
Property Type Description Property of
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.
Operation Method and URI
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
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
216 OneFS 7.2.1 OneFS API Reference
Quota quotas notification rules resource
Applies the standard collection pattern to the notification rules for a quota.
Operation Method and URI
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
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
SmartQuotas overview 217
Property Type Description Property of
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.
Operation Method and URI
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 mustbe used 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>
System configuration API
218 OneFS 7.2.1 OneFS API Reference
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.
resolve_names=<Boolean>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
Property Type Description Property of
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;default indicates that the system
quotas
System configuration API
SmartQuotas overview 219
Property Type Description Property of
default 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
id Integer Specifies the serialized form of thepersona (such as 'UID:0','USER:name', 'GID:0', 'GROUP:wheel','SID:S-1-1').
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
System configuration API
220 OneFS 7.2.1 OneFS API Reference
Quota reports resource
Applies the standard collection pattern to quota reports.
Operation Method and URI
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]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be used with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the total number of reportsavailable.
N/A
resume String Specifies the value of the resumeargument to be used for continuationcalls.
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
System configuration API
SmartQuotas overview 221
Property Type Description Property of
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.
Operation Method and URI
Get metadata about a report GET /platform/1/quota/reports/<report-id>/about
View detailed JSON schema for thisresource
GET /platform/1/quota/reports/<report-id>/about?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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.
Operation Method and URI
Get quota report settings GET /platform/1/quota/settings/reports
System configuration API
222 OneFS 7.2.1 OneFS API Reference
Operation Method and URI
Modify quota report settings PUT /platform/1/quota/settings/reports
View the detailed JSON schema for thisresource
GET /platform/1/quota/settings/reports?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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.
Operation Method and URI
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>
System configuration API
SmartQuotas overview 223
Operation Method and URI
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
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
224 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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.
Operation Method and URI
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
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
SmartQuotas overview 225
Property Type Description Property of
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.
Operation Method and URI
Get license information for SnapshotIQ GET /platform/1/snapshot/license
View the detailed JSON schema for thisresource
GET /platform/1/snapshot/license?describe
Query parametersThere are no parameters for this resource.
System configuration API
226 OneFS 7.2.1 OneFS API Reference
Object properties
Property Type Description Property of
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.
Operation Method and URI
Get summary information about file systemsnapshots
GET /platform/1/snapshot/snapshots-summary
View the detailed JSON schema for thisresource
GET /platform/1/snapshot/snapshots-summary?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
Snapshots overview 227
Property Type Description Property of
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.
Operation Method and URI
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]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>
System configuration API
228 OneFS 7.2.1 OneFS API Reference
Continue returning results from previous request (cannot be combined with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the total number ofsnapshots available.
N/A
resume String Specifies the value for the resumeargument for continuation requests.
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
System configuration API
Snapshots overview 229
Property Type Description Property of
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.
Operation Method and URI
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]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be combined with otherparameters).
System configuration API
230 OneFS 7.2.1 OneFS API Reference
Object properties
Property Type Description Property of
total Integer Specifies the total number ofschedules to display.
N/A
resume String Specifies the value for the resumeargument to be used for continuationrequests.
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.
Operation Method and URI
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>
System configuration API
Snapshots overview 231
Operation Method and URI
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]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be combined with otherparameters).
Object properties
Property Type Description Property of
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.
Operation Method and URI
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.
System configuration API
232 OneFS 7.2.1 OneFS API Reference
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>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be combined with otherparameters).
Object properties
Property Type Description Property of
resume String Specifies the value for the resumeargument to be used for continuationrequests.
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.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/snapshot/aliases?describe
View the detailed JSON schema for thisresource
GET /platform/1/snapshot/aliases/<snapshot alias name or ID>?describe
System configuration API
Snapshots overview 233
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]Directions for the sort order are ascending (ASC) or descending (DESC). The defaultsetting is ASC.
limit=<integer>Return no more than this many results at one time (see resume).
resume=<string>Continue returning results from previous request (cannot be combined with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the number of snapshotaliases.
N/A
resume String Specifies the value for the resumeargument to be used for continuationrequests.
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.
Operation Method and URI
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>
System configuration API
234 OneFS 7.2.1 OneFS API Reference
Operation Method and URI
View the detailed JSON schema for thisresource
GET /platform/1/snapshot/changelists?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
total Integer Specifies the number of snapshotchangelists returned.
N/A
resume String Specifies the value for the resumeargument to be used for continuationrequests.
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
snapshot ID boundary.
changelists
status String Specifies the status of the changelist. changelists
Snapshot changelists changelist lins resource
Retrieve information about a snapshot changelist entry.
Operation Method and URI
Get snapshot changelist entries GET /platform/1/snapshot/changelists/<changelist>/lins
Get a snapshot changelist entry GET /platform/1/snapshot/changelists/<changelist>/lins/<lin>
View the detailed JSON schema for thisresource
GET /platform/1/snapshot/changelists/<changelist>/lins?describe
System configuration API
Snapshots overview 235
Operation Method and URI
View the detailed JSON schema for thisresource
GET /platform/1/snapshot/changelists/<changelist>/lins/<lin>?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
total Integer Specifies the number of lins returned. N/A
resume String Specifies the value for the resumeargument to be used for continuationrequests.
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
nsec Integer Specifies the timespec innanoseconds.
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
nsec Integer Specifies the timespec innanoseconds.
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
System configuration API
236 OneFS 7.2.1 OneFS API Reference
Snapshot repstates resource
Create or retrieve information about snapshot repstates.
Operation Method and URI
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>
View the detailed JSON schema for thisresource
GET /platform/1/snapshot/repstates?describe
View the detailed JSON schema for thisresource
GET /platform/1/snapshot/repstates/<repstate>?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
total Integer Specifies the number of snapshotrepstates returned.
N/A
resume String Specifies the value for the resumeargument to be used for continuationrequests.
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
snapshot ID boundary.
repstates
snap2 Integer Specifies the job that computed thechangelist. The job specifies thesnap2 property as the higher
snapshot ID boundary.
repstates
Snapshot settings resource
Modify or retrieve information about global snapshot settings.
Operation Method and URI
Get the current snapshot settings GET /platform/1/snapshot/settings
Modify the current snapshot settings PUT /platform/1/snapshot/settings
System configuration API
Snapshots overview 237
Operation Method and URI
View the detailed JSON schema for thisresource
GET /platform/1/snapshot/settings?describe
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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.
System configuration API
238 OneFS 7.2.1 OneFS API Reference
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
201 Created Content-type: application/json
{"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"}
Response exampleNo message body is returned for this request.
204 No Content Content-type: text/plain
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.
System configuration API
Access zones overview 239
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 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.
Operation Method and URI
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
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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
System configuration API
240 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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
System configuration API
Access zones overview 241
Access zones summary resource
Retrieve summary information about the access zones on a cluster.
Operation Method and URI
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>
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
Query parametersThere are no parameters for this resource.
Object properties
Property Type Description Property of
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
201 CreatedContent-type: application/json
{"id":"MyZone"}
System configuration API
242 OneFS 7.2.1 OneFS API Reference
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 resource
This 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.
Operation Method and URI
Get all current statistics GET /platform/1/statistics/current
View the detailed JSON schema for thisresource
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>
System configuration API
Cluster statistics 243
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.
Object properties
Property Type Description Property of
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 resource
This retrieves meta-data for matching statistics keys.
Operation Method and URI
Get all statistic keys GET /platform/1/statistics/keys
Get a statistics key GET /platform/1/statistics/keys/<KEY>
View the detailed JSON schema for thisresource
GET /platform/1/statistics/keys?describe
View detailed JSON schema for thisresource
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>Return no more than this many results at one time (see resume).
resume=<string>
System configuration API
244 OneFS 7.2.1 OneFS API Reference
Continue returning results from the previous request (cannot be combined with otherparameters).
Object properties
Property Type Description Property of
total Integer Specifies the total number of keysavailable.
N/A
resume String Specifies the value for the resumeargument for continuation requests.
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 resource
This 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-series
System configuration API
Cluster statistics 245
enabled, 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,see the /platform/1/statistics/keys or /platform/1/statistics/keys/<KEY> resources. These resource also describe available history policies for each key.
Operation Method and URI
Get all statistics history GET /platform/1/statistics/history
View the detailed JSON schema for thisresource
GET /platform/1/statistics/history?describe
Query parameters
begin=<integer>Set the earliest time in UNIX Epoch seconds of interest if available. Negative timesare interpreted 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 ahigher resolution, 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
Property Type Description Property of
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
System configuration API
246 OneFS 7.2.1 OneFS API Reference
Property Type Description Property of
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 resource
This resource returns a list of protocol and client statistics for OneFS.
Operation Method and URI
Get all protocols GET /platform/1/statistics/protocols
View the detailed JSON schema for thisresource
GET /platform/1/statistics/protocols?describe
Query parametersThere are no query parameters for this resource.
Object properties
Property Type Description Property of
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.
System configuration API
Code samples for file system configuration 247
CHAPTER 4
File system access API
This section contains the following topics:
l File system access API overview.......................................................................... 250l Troubleshooting..................................................................................................252l File system access operations............................................................................. 254l Code samples for file system access................................................................... 320
File system access API 249
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
File system access API
250 OneFS 7.2.1 OneFS API Reference
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
x-isi-ifs-target-type
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
File system access API
Common namespace attributes 251
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
File system access API
252 OneFS 7.2.1 OneFS API Reference
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
File system access API
Troubleshooting 253
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>]
File system access API
254 OneFS 7.2.1 OneFS API Reference
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>
File system access API
Access points 255
Request query parametersThere are no query parameters for this request.
Request headersThis call sends common request headers.
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>
File system access API
256 OneFS 7.2.1 OneFS API Reference
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
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
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" }
File system access API
Access points 257
} ], "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>
File system access API
258 OneFS 7.2.1 OneFS API Reference
Request query parameters
Parametername
Description Default Type Required
versions This parameter is a functionalkeyword that does not have a value.
N/A N/A Yes
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
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>
Request query parametersThere are no query parameters for this request.
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
File system access API
Access points 259
Response bodyNo message body is returned upon success.
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
HTTP/1.1 200 OKDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19
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
Request query parameters
ParameterName
Description Default Type Required
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
File system access API
260 OneFS 7.2.1 OneFS API Reference
Request headers
HeaderName
Description Default Type Required
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
Response headersThis call returns common response headers.
Response bodyNo message body is returned upon success.
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
HTTP/1.1 200 OKDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19
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>
File system access API
Directory operations 261
Request query parametersThere are no query parameters for this request.
Request headers
HeaderName
Description Default Type Required
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
Description Default Type Required
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
x-isi-ifs-attr-<attr_name>
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
x-isi-ifs-access-control
Provides the access mode for thedirectory in octal notation.
None String No
Response bodyNo message body is returned upon success.
File system access API
262 OneFS 7.2.1 OneFS API Reference
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>
Request query parameters
ParameterName
Description Default Type Required
metadata This parameter is a functionalkeyword and does not have a value.
N/A N/A Yes
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
Response bodyThe object attribute information is returned in JSON format.
{ "attrs":[ { "name":"<key_name>", "value":"<key_value>", "namespace":"<namespace_value>" }, ... ]}
File system access API
Directory operations 263
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 },
File system access API
264 OneFS 7.2.1 OneFS API Reference
{ "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.
Request query parameters
ParameterName
Description Default Type Required
detail Specifies which object attributes aredisplayed. If the detail parameter
None String No
File system access API
Directory operations 265
ParameterName
Description Default Type Required
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
File system access API
266 OneFS 7.2.1 OneFS API Reference
ParameterName
Description Default Type Required
hidden Specifies if hidden objects arereturned.
None Boolean No
Request headers
HeaderName
Description Default Type Required
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
Description Default Type Required
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.
application/json
String No
x-isi-ifs-attr-<attr_name>
Provides the extended attributes thatwere set in the message header.
None String No
x-isi-ifs-missing-attr
Provides the number of attributesthat cannot be displayed in the HTTPheader.
None Integer No
x-isi-ifs-access-control
Provides the POSIX mode in octalnotation.
None String No
Response bodyAn array of objects in the directory is output in JSON format.
File system access API
Directory operations 267
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,
File system access API
268 OneFS 7.2.1 OneFS API Reference
"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>
Request query parameters
ParameterName
Description Default Type Required
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
Description Default Type Required
x-isi-ifs-copy-source
Specifies the full path to the sourcedirectory.
The source and destination mustshare the same access point.
None String Yes
Response headersThis call returns common response headers.
Response bodyNo message body is returned upon success.
File system access API
Directory operations 269
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",
File system access API
270 OneFS 7.2.1 OneFS API Reference
"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 query parametersThere are no query parameters for this request.
Request headers
HeaderName
Description Default Type Required
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
Response headersThis call returns common response headers.
Response bodyNo message body is returned upon success.
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
File system access API
Directory operations 271
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>
Request query parameters
ParameterName
Description Default Type Required
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
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
Response bodyNo message body is returned upon success.
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
HTTP/1.1 204 No ContentDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19
File system access API
272 OneFS 7.2.1 OneFS API Reference
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.
Request query parameters
ParameterName
Description Default Type Required
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
Description Default Type Required
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
File system access API
Directory operations 273
ParameterName
Description Default Type Required
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
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
Response bodyNo message body is returned upon success.
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
File system access API
274 OneFS 7.2.1 OneFS API Reference
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]
Request query parameters
ParameterName
Description Default Type Required
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
Description Default Type Required
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 system access API
File operations 275
HeaderName
Description Default Type Required
x-isi-ifs-target-type
Specifies the resource type. Thisvalue can be container orobject.
None String Yes.
The valuemust be setto 'object.'
x-isi-ifs-access-control
Specifies a pre-defined ACL value orPOSIX mode with a string in octalstring format.
0600 (read,write withownerpermissions)
String No
x-isi-ifs-attr-<attr_name>
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
Response headersThis call returns common response headers.
Response bodyNo message body is returned upon success.
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 query parametersThere are no query parameters for this request.
File system access API
276 OneFS 7.2.1 OneFS API Reference
Request headers
HeaderName
Description Default Type Required
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.
Response bodyNo message body is returned upon success.
Example request
GET /namespace/ifs/my_folder/picture.jpg HTTP/1.1Host my_cluster:8080
File system access API
File operations 277
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>
Request query parameters
ParameterName
Description Default Type Required
overwrite Specifies if the existing file should beoverwritten when a file with the samename exists.
False Boolean No
Request headers
HeaderName
Description Default Type Required
x-isi-ifs-copy-source
Specifies the full path of the source.
The source and destination pathsmust be in the same access point.
N/A String Yes
Response headersThis call returns common response headers.
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.
File system access API
278 OneFS 7.2.1 OneFS API Reference
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 system access API
File operations 279
Request query parametersThere are no query parameters for this request.
Request headers
HeaderName
Description Default Type Required
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
Response headersThis call returns common response headers.
Response bodyNo message body is returned upon success.
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>
Request query parametersThere are no query parameters for this request.
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
File system access API
280 OneFS 7.2.1 OneFS API Reference
Response bodyNo message body is returned upon success.
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
HTTP/1.1 204 No ContentDate: Thu, 22 Sep 2011 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19
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>
Request query parameters
ParameterName
Description Default Type Required
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
Description Default Type Required
x-isi-ifs-copy-source
Specifies the full path of the source.
The source and destination pathsmust be in the same access point.
N/A String Yes
File system access API
File operations 281
Response headersThis call returns common response headers.
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.
File system access API
282 OneFS 7.2.1 OneFS API Reference
Request query parameters
ParameterName
Description Default Type Required
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
Description Default Type Required
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
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
Response bodyNo response body is returned upon success.
File system access API
File operations 283
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 query parametersThere are no query parameters for this request.
Request headers
HeaderName
Description Default Type Required
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
File system access API
284 OneFS 7.2.1 OneFS API Reference
HeaderName
Description Default Type Required
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
Description Default Type Required
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
x-isi-ifs-attr-<attr_name>
Provides the extended attributes thatwere set in the message header.
None String No
x-isi-ifs-missing-attr
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
x-isi-ifs-access-control
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
Response bodyNo message body is returned upon success.
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 system access API
File operations 285
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>
Request query parameters
ParameterName
Description Default Type Required
metadata The metadata argument must be
placed at the first position of theargument list in the URI.
N/A String No
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
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
File system access API
286 OneFS 7.2.1 OneFS API Reference
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 system access API
File operations 287
"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.
File system access API
288 OneFS 7.2.1 OneFS API Reference
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.
File system access API
Access control lists 289
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.
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.
File system access API
290 OneFS 7.2.1 OneFS API Reference
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>
Request query parameters
ParameterName
Description Default Type Required
acl The acl argument must be placed at
the first position of the argument listin the URI.
N/A String Yes
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
Response body
HTTP/1.1 200 OKDate: Tue, 22 May 2012 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19
{ "owner":{
File system access API
Access control lists 291
"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>
File system access API
292 OneFS 7.2.1 OneFS API Reference
Example response
HTTP/1.1 200 OKDate: Tue, 22 May 2012 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":"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.1Host: <hostname>[:<port>]Date: <date>Authorization: <signature>
File system access API
Access control lists 293
Request query parameters
ParameterName
Description Default Type Required
acl The acl argument must be placed at
the first position of the argument listin the URI.
N/A String Yes
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
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>" } ]}
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.
File system access API
294 OneFS 7.2.1 OneFS API Reference
Parameter Name Description
acl Provides the JSON array of access rights.
accesstype Can be set to allow or deny.
allow: Allows access to the file based on the access rights set for the
trustee.
deny: Denies access to the file based on the access rights set for the
trustee.
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",
File system access API
Access control lists 295
"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, createsubdirectories, write attributes, writeextended attributes, access files insubdirectories, delete children(including read-only files), change
Directory owner: "accessrights":["dir_gen_all"],"inherit_flags":[]
All users: "accessrights":["dir_gen_read","dir_gen_execute"],"inherit_flags":[]
File system access API
296 OneFS 7.2.1 OneFS API Reference
Pre-defined ACLvalue
Access rights Access rights displayed
owner, 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.
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.
1000 The sticky bit.
0400 Allows read by owner.
File system access API
Access control lists 297
Octalnumber
Description
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.
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 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
HTTP/1.1 200 OKDate: Tue, 22 May 2012 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19
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>
File system access API
298 OneFS 7.2.1 OneFS API Reference
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.
Pre-defined ACLvalue
Access rights Access rights displayed
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,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.
File owner: "accessrights":["file_gen_all"],"inherit_flags":[]
All users: "accessrights":["file_gen_read","file_gen_write","file_gen_execute"],"inherit_flags":[]
File system access API
Access control lists 299
Pre-defined ACLvalue
Access rights Access rights displayed
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.
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 bodyThere is no message body for this response.
File system access API
300 OneFS 7.2.1 OneFS API Reference
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
HTTP/1.1 200 OKDate: Tue, 22 May 2012 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19
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>" } ]}
File system access API
Access control lists 301
Request query parameters
ParameterName
Description Default Type Required
acl The acl argument must be placed at
the first position of the argument listin the URI.
N/A String Yes
Request body parameters
ParameterName
Description Default Type Required
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
File system access API
302 OneFS 7.2.1 OneFS API Reference
ParameterName
Description Default Type Required
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
File system access API
Access control lists 303
ParameterName
Description Default Type Required
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
accesstype Can be set to allow or deny.
allow: Allows access to the directory
based on the access rights set for thetrustee.
deny: Denies access to the directory
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 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.
File system access API
304 OneFS 7.2.1 OneFS API Reference
ParameterName
Description Default Type Required
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.
N/A List of stringvalues
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
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
File system access API
Access control lists 305
Response bodyThere is no message body for this response.
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
HTTP/1.1 200 OKDate: Tue, 22 May 2012 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19
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>
File system access API
306 OneFS 7.2.1 OneFS API Reference
Content-Type: application/json
{ "owner":{ "id":"UID:2001", "name":"foo1", "type":"user" }, "group":{ "id":"GID:0", "name":"wheel", "type":"group" }, "authoritative":"acl", "action":"replace", "acl":[]}
Example response 2
HTTP/1.1 200 OKDate: Tue, 22 May 2012 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19
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>"
File system access API
Access control lists 307
} ]}
Request query parameters
ParameterName
Description Default Type Required
acl The acl argument must be placed at
the first position of the argument listin the URI.
N/A String Yes
Request body parameters
ParameterName
Description Default Type Required
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
File system access API
308 OneFS 7.2.1 OneFS API Reference
ParameterName
Description Default Type Required
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
File system access API
Access control lists 309
ParameterName
Description Default Type Required
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.
accesstype Can be set to allow or deny.
allow: Allows access to the file
based on the access rights set for thetrustee.
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.
N/A List of stringvalues
Conditional
Mandatorywhen the<action_value> field is setto updateand the<operation_value>field isset to eitheradd or
replace,
and whenthe
File system access API
310 OneFS 7.2.1 OneFS API Reference
ParameterName
Description Default Type Required
<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.
N/A List of stringvalues
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
File system access API
Access control lists 311
ParameterName
Description Default Type Required
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.
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
Response bodyNo message body is returned upon success.
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" },
File system access API
312 OneFS 7.2.1 OneFS API Reference
"accesstype":"allow", "accessrights":"std_write_dac" ], "op":"replace" }]}
Example response
HTTP/1.1 200 OKDate: Tue, 22 May 2012 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19
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
Description Default Type Required
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
File system access API
Query operations 313
ParameterName
Description Default Type Required
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
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
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" :
File system access API
314 OneFS 7.2.1 OneFS API Reference
[ { "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}
File system access API
Query operations 315
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",
File system access API
316 OneFS 7.2.1 OneFS API Reference
"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>
File system access API
SmartLock settings 317
Request query parameters
ParameterName
Description Default Type Required
worm The worm argument must be placedat the first position of the argumentlist in the URI.
N/A String No
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
Response body
{ "worm_committed":<boolean>, "worm_override_retention_date":<"YYYY-MM-DD hh:mm:ss GMT">|null, "worm_override_retention_date_val":<seconds from the Epoch>|null, "worm_retention_date":<"YYYY-MM-DD hh:mm:ss GMT">|null, "worm_retention_date_val":<seconds from the Epoch>|null}
Response body parameters
Parameter Name Description
worm_committed Indicates whether the file was committed to the WORM state.
worm_retention_date Provides the retention expiration date in 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.
File system access API
318 OneFS 7.2.1 OneFS API Reference
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
HTTP/1.1 200 OKDate: Tue, 22 May 2012 12:00:00 GMTContent-Length: <length>Connection: closeServer: Apache2/2.2.19
{ "worm_committed":true, "worm_retention_date":"2013-01-22 15:11:36 GMT", "worm_override_retention_date":null, "worm_retention_date_val":1358885496, "worm_override_retention_date_val":null}
Set the retention period and commit a file in a SmartLock 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.
Request query parameters
ParameterName
Description Default Type Required
worm The worm argument must be placedat the first position of the argumentlist in the URI.
N/A String No
File system access API
SmartLock settings 319
Request body parameters
ParameterName
Description Default Type Required
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
Request headersThis call sends common request headers.
Response headersThis call returns common response headers.
Response bodyNo message body is returned upon success.
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.
File system access API
320 OneFS 7.2.1 OneFS API Reference