ViPR File Access Mode

Table of Contents

Back to Top

Introduction

ViPR file access mode enables objects stored in ViPR object storage to be exposed as files so that they can be read and modified. This article describes the API that enables file access mode.

This article applies to EMC ViPR 2.0.

Back to Top

Using File Access Mode

File access mode allows objects to be managed by applications that require them to be available as objects, and also allows the data to be accessed by applications that require them to be accessed as files. For example, an image file might need to be edited using a traditional file-based application, but might also need to be processed by an application that needs to access it as an object.

The ViPR extended object API allows a bucket, or a set of objects within a bucket, to be switched to file access mode. An NFS export that exposes the objects as files is made available and can be mounted. Once mounted, the files can be accessed with their original directory structure preserved, if required. The set of objects exported in this manner is fixed and new objects added via the REST protocol will not be visible in existing exports. Conversely, you cannot create or delete objects in the exported mount points, although when mounted read-write, you can modify existing objects. While objects are available over NFS, they are inaccessible via REST and vice versa.

The following API calls are provided and a link is provided to reference information for each method:

A resource can have one of the following values for file access mode:

  • disabled – Default file access mode. By default, accessing the file directly is disabled; the resource is in object mode and only REST access to this resource is allowed.
  • readOnly – The resource is available for read-only operations through file access mode. The resource can be accessed directly as a file, and the user can only perform read operations on it; there is also read-only REST access to the resource.
  • readWrite – The resource is available for read/write operations through file access mode. The resource can be accessed directly as a file and the user can perform read/write operations on it; there is no REST access to the resource.

A client can invoke a PUT request to transition a resource from a file access mode of Disabled to a file access mode of readOnly or readWrite. However, once the current file access mode for the resource is anything other than Disabled, there are only three possible transitions:

  • SwitchToDisabled - Either when there is a timeout for the file access mode, or an explicit REST request releasing the file access mode (setting it to Disabled)
  • SwitchToReadOnly - When the current file access mode is readOnly, and a PUT request is received with a TOKEN, which changes the # of objects granted read only file access.
  • SwitchToReadWrite - When the current file access mode is readWrite, and a PUT request is received with a TOKEN which changes the # of objects granted read write file access.

Note that from a ViPR point of view, file-mode state is a combination of file access mode plus allowed host list plus allowed users list. Which implies that once a state transition to a non-disabled file access mode has been triggered by the client, the only way to change the associated host/user permission list is to first transition to the disabled file mode state, and then trigger a subsequent transition to the required file access mode with appropriate user/host permission list.

Using tokens

To keep track of the file access state of a bucket, a token is generated by the ViPR system, and sent to the client through the response of the PUT request. The value of the token is the current number of the bucket whose access mode is being changed. ViPR maintains a number for each bucket hosted by the system. The version number of bucket is changed with each access mode request to readOnly or readWrite.

The set of objects to be exported is defined by a start-token and an end-token, which represent specific points in time for the bucket. These tokens are returned from any call ("get" or "set"). Only one token may be used in "set" calls with the following outcome:

  • When setting mode to readOnly or readWrite and a token is included, only enable access for objects *newer* than (created since) the specified token.
  • When setting mode to disabled and a token is included, only disable access for objects *older* than (created before) the specified token.

Supporting Tools

Java and Python clients are available to enable you to try out the functionality before integrating it into your applications and/or workflows. Refer to teh following articles for details:

Back to Top

PUT ?accessmode

The PUT ?accessmode is used to change the access mode for the objects stored in ViPR. Changes to the access mode are supported at the granularity of a bucket. That is, all the objects belonging to a bucket are granted file access. Once this request is accepted by ViPR, it starts the operation of changing the objects' access mode. The client needs to periodically check back to determine whether the steps required for access mode switch have been completed.

Syntax

For the S3 service:

PUT /?accessmode Host: <bucketname>.<namespace>.<ViPR address> or <namespace>.<ViPR address>/<bucketname>

For OpenStack Swift:

PUT /v1/​{account}​/​{container}​?accessmode

Request headers

The following request headers are involved in this PUT request for changing the object's access mode.

Response headers

The response can include the following headers:

The response can have the following special error headers.

Once the file access mode transition for a bucket has been completed (to be verified by the client by issuing a GET request as described below), the client can subsequently send another PUT request in order to "renew" the lease on the file-access mode. This prevents the ViPR object service from automatically switching the file access mode of that bucket to Disabled after the file access duration expires.

Note that duplicate requests are responded with a Success response. ViPR currently does not differentiate a duplicate request from a fresh request, and so a duplicate request has the side effect of increasing the current file access mode's timeout as tracked by the ViPR system.

Back to Top

GET ?accessmode

The GET ?accessmode request retrieves the file access mode that is currently being enforced by the ViPR system.

Syntax

For the S3 service:

GET /?accessmode Host: <bucketname>.<namespace>.<ViPR address> or <namespace>.<ViPR address>/<bucketname>

For OpenStack Swift:

GET /v1/​{account}​/​{container}​?accessmode

Request parameters

There are no specific request parameters.

Request headers

There are no specific request headers.

Response

The ViPR system responds with an OK message, and includes information about the current file access mode which is being enforced. It can have one of the following possible values: Disabled, SwitchingToDisabled, ReadOnly, SwitchingToReadOnly, ReadWrite, SwitchingToReadWrite.

Response headers

The response can contain the following headers:

Back to Top

GET ?fileaccess

The GET ?fileaccess request retrieves the file access details for the required resource. It responds with a list of objects belonging to the bucket, along with each object's access path if the bucket's file access mode is either ReadWrite or ReadOnly.

Syntax

For the S3 service:

GET /{object_name}?fileaccess Host: <bucketname>.<namespace>.<ViPR address> or <namespace>.<ViPR address>/<bucketname>

For OpenStack Swift:

PUT /v1/​{account}​/​{container}​?fileaccess

Request Parameters

The following request parameters can be specified.

Request Headers

There are no specific request headers.

Response

If the current file access mode is not ReadOnly or ReadWrite, the response is an error:

If the current file access mode is ReadOnly or ReadWrite, the ViPR system responds with:

  • Current file access mode.
  • List of hosts granted access for file access (if any).
  • List of users granted access for file access (if any).
  • Time in seconds left before the file access is disabled.
  • Mount point for each device hosting the required resource (bucket).
  • Fully qualified path name for each object within the resource.
  • Flag indicating whether the result set for objects is truncated.

Response Headers

Responses can contain the following headers:

Response body

The response body provides information about the mounted file system, as shown in the example below.

<fileaccess_response> <mountPoints>lglaz011:/ifs/vipr/rjm-isilon-vp01/rjm-isilon-datastore01</mountPoints> <hasMore>false</hasMore> <objects> <name>test_file.txt</name> <deviceExport>lglaz011:/ifs/vipr/rjm-isilon-vp01/rjm-isilon-datastore01</deviceExport> <relativePath>vipr/customDir/FileAccess/rjm-isilon-namespace01.test-bucket/1/test_file.txt/data</relativePath> <owner>1000</owner> </objects> </fileaccess_response>