The Storage Resource Manager
Interface Specification
Version 2.2
2 April 2007
|
Collaboration Web: |
http://sdm.lbl.gov/srm-wg |
|
Document Location: |
http://sdm.lbl.gov/srm-wg/doc/SRM.v2.2.html |
|
|
|
|
Editors: |
|
|
Alex Sim |
Lawrence Berkeley National Laboratory |
|
Arie Shoshani |
Lawrence Berkeley National Laboratory |
|
|
|
|
Contributors: |
|
|
Timur Perelmutov Don Petravick |
Fermi National Accelerator Laboratory (FNAL), USA |
|
Ezio Corso Luca Magnoni |
International Centre for Theoretical Physics (ICTO), Italy Istituto Nazionale di Fisica Nucleare (INFN), Italy |
|
Junmin Gu |
Lawrence Berkeley National Laboratory (LBNL), USA |
|
Paolo Badino Olof Barring Jean-Philippe Baud Flavia Donno Maarten Litmaath |
LHC Computing Project (LCG, CERN), Switzerland |
|
Shaun De Witt Jens Jensen |
Rutherford Appleton Laboratory (RAL), England |
|
Michael Haddox-Schatz Bryan Hess Andy Kowalski |
Thomas Jefferson National Accelerator Facility (TJNAF), USA |
Copyright Notice
© Copyright Lawrence Berkeley National Laboratory (LBNL), Fermi National Accelerator Laboratory (FNAL), Jefferson National Accelerator Facility (JLAB), Rutherford Appleton Laboratory (RAL), Istituto Nazionale di Fisica Nucleare (INFN), International Centre for Theoretical Physics (ICTO), and European Organization for Nuclear Research (CERN) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007. All Rights Reserved.
Permission to copy and display this “The Storage Resource Manager Interface Specification” (“this paper"), in any medium without fee or royalty is hereby granted, provided that you include the following on ALL copies of this paper, or portions thereof that
you make:
1. A link or URL to this paper at this location.
2. This Copyright Notice as shown in this paper.
THIS PAPER IS PROVIDED "AS IS," AND Lawrence Berkeley National Laboratory, Fermi National Accelerator Laboratory, Jefferson National Accelerator Facility, Rutherford Appleton Laboratory and European Organization for Nuclear Research (COLLECTIVELY, THE “COLLABORATION”) MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT OR TITLE; THAT THE CONTENTS OF THIS PAPER ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
THE COLLABORATION WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS PAPER.
The names and trademarks of the Collaboration may NOT be used in any manner, including advertising or publicity pertaining to this paper or its contents, without specific, written prior permission. Title to copyright in this paper will at all times remain with the Collaboration.
No other rights are granted by implication, estoppel or otherwise.
PORTIONS OF THIS PAPER WERE PREPARED AS AN ACCOUNT OF WORK FUNDED BY U.S. Department of Energy AT UNIVERSITY OF CALIFORNIA'S LAWRENCE BERKELEY NATIONAL LABORATORY. NEITHER THE AUTHORS, NOR THE UNITED STATES GOVERNMENT OR ANY AGENCY THEREOF, NOR THE UNIVERSITY OF CALIFORNIA, NOR ANY OF THEIR EMPLOYEES OR OFFICERS, NOR ANY OTHER COPYRIGHT HOLDERS OR CONTRIBUTORS, MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR USEFULNESS OF ANY INFORMATION, APPARATUS, PRODUCT, OR PROCESS DISCLOSED, OR REPRESENTS THAT ITS USE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS. REFERENCE HEREIN TO ANY SPECIFIC COMMERCIAL PRODUCT, PROCESS, OR SERVICE BY TRADE NAME, TRADEMARK, MANUFACTURER, OR OTHERWISE, DOES NOT NECESSARILY CONSTITUTE OR IMPLY ITS ENDORSEMENT, RECOMMENDATION, THE UNITED STATES GOVERNMENT OR ANY AGENCY THEREOF OR ANY OTHER COPYRIGHT HOLDERS OR CONTRIBUTORS. THE VIEW AND OPINIONS OF AUTHORS EXPRESSED HEREIN DO NOT NECESSARILY STATE OR REFLECT THOSE OF THE UNITED STATES GOVERNMENT OR ANY AGENCY THEREOF, OR THE ENTITY BY WHICH AN AUTHOR MAY BE EMPLOYED.
This paper preparation has been partially supported by the Office of Energy Research, Office of Computational and Technology Research, Division of Mathematical, Information, and Computational Sciences, of the U.S. Department of Energy under Contract No. DE-AC03-76SF00098.
The U.S. Government retains for itself, and others acting on its behalf, a paid-up, nonexclusive, irrevocable worldwide license in said article to reproduce, prepare derivative works, distribute copies to the public, and perform publicly and display publicly, by or on behalf of the Government.
Table of Contents
1.19. Time in Seconds (Lifetime and RequestTime)
1.29. File Request for srmPrepareToGet
1.30. File Request for srmPrepareToPut
1.31. File Request for srmCopy
1.32. Return File Status for srmPrepareToGet
1.33. Return File Status for srmBringOnline
1.34. Return File Status for srmPrepareToPut
1.35. Return File Status for srmCopy
1.39. Return Permissions on SURL
1.41. Supported File Transfer Protocol
2.2. srmStatusOfReserveSpaceRequest
2.5. srmStatusOfUpdateSpaceRequest
2.8. srmStatusOfChangeSpaceForFilesRequest
2.9. srmExtendFileLifeTimeInSpace
5.4. srmStatusOfBringOnlineRequest
7.1. Status Code Specification
7.2. SRM WSDL discovery method
This document contains the interface specification of SRM 2.2. It incorporates the functionality of SRM 2.0 and SRM 2.1, but is much expanded to include additional functionality, especially in the area of dynamic storage space reservation and directory functionality in client-acquired storage spaces.
This document reflects the discussions and conclusions of a 2-day meeting in May 2006, as well as email correspondence and conference calls. The purpose of this activity is to further define the functionality and standardize the interface of Storage Resource Managers (SRMs) – a Grid middleware component.
The document is organized in four sections. The first, called “Defined Structures” contain all the type definitions used to define the functions (or methods). The next 5 sections contain the specification of “Space Management Functions”, “Permission Functions”, “Directory Functions”, “Data Transfer Functions” and “Discovery Functions”. All the “Discovery Functions” are newly added functions.
It is advisable to read the document SRM.v2.2.changes.doc posted at http://sdm.lbl.gov/srm-wg before reading this specification.
By “https” we mean http protocol with GSI authentication. It may be represented as “httpg”. At this time, any implementation of http with GSI authentication could be used. It is advisable that the implementation is compatible with Globus Toolkit 3.2 or later versions.
· The definition of the type “anyURI” used below is compliant with the XML standard. See http://www.w3.org/TR/xmlschema-2/#anyURI. It is defined as: "The lexical space of anyURI is finite-length character sequences which, when the algorithm defined in Section 5.4 of [XML Linking Language] is applied to them, result in strings which are legal URIs according to [RFC 2396], as amended by [RFC 2732]".
· In “localSURL”, we mean local to the SRM that is processing the request.
·
authorizationID : from the SASL RFC 2222
During the authentication protocol exchange, the mechanism performs
authentication, transmits an authorization identity (frequently known as a
userid) from the client to server…. The transmitted authorization identity may
be different than the identity in the client’s authentication credentials. This
permits agents such as proxy servers to authenticate using their own
credentials, yet request the access privileges of the identity for which they are
proxying. With any mechanism, transmitting an authorization identity of the
empty string directs the server to derive an authorization identity from the
client’s authentication credentials.
· Regarding file sharing by the SRM, it is a local implementation decision. An SRM can choose to share files by proving multiple users access to the same physical file, or by copying a file into another user’s space. Either way, if an SRM chooses to share a file (that is, to avoid reading a file over again from the source site) the SRM should check with the source site whether the user has a read/write permission. Only if permission is granted, the file can be shared.
· The word “pinning” is limited to the “copies” or “states” of SURLs and the Transfer URLs (TURLs).
· For each function, status codes are defined with basic meanings for the function. Only those status codes are valid for the function. Specific cases are not stated for each status code. If other status codes need to be defined for a specific function, send an email to the collaboration to discuss the usage.
Namespace SRM
Notation: underlined attributes are REQUIRED.
enum TFileStorageType {VOLATILE, DURABLE, PERMANENT}
o Volatile file has an expiration time and the storage may delete all traces of the file when it expires.
o Permanent file has no expiration time.
o Durable file has an expiration time, but the storage may not delete the file, and should raise error condition instead.
enum TFileType {FILE, DIRECTORY, LINK}
enum TRetentionPolicy { REPLICA , OUTPUT , CUSTODIAL }
o Quality of Retention (Storage Class) is a kind of Quality of Service. It refers to the probability that the storage system lose a file. Numeric probabilities are self-assigned.
· Replica quality has the highest probability of loss, but is appropriate for data that can be replaced because other copies can be accessed in a timely fashion.
· Output quality is an intermediate level and refers to the data which can be replaced by lengthy or effort-full processes.
· Custodial quality provides low probability of loss.
o The type will be used to describe retention policy assigned to the files in the storage system, at the moments when the files are written into the desired destination in the storage system. It will be used as a property of space allocated through the space reservation function. Once the retention policy is assigned to a space, the files put in the reserved space will automatically be assigned the retention policy of the space. The assigned retention policy on the file can be found thought the TMetaDataPathDetail structure returned by the srmLs function.
enum TAccessLatency { ONLINE, NEARLINE }
o Files may be Online, Nearline or Offline. These terms are used to describe how latency to access a file is improvable. Latency is improved by storage systems replicating a file such that its access latency is online.
· The ONLINE cache of a storage system is the part of the storage system which provides file with online latencies.
· ONLINE has the lowest latency possible. No further latency improvements are applied to online files.
· NEARLINE file can have their latency improved to online latency automatically by staging the file to online cache.
· For completeness, we also describe OFFLINE here.
· OFFLINE files need a human to be involved to achieve online latency.
· For the SRM we only keep ONLINE and NEARLINE.
o The type will be used to describe a space property that access latency can be requested at the time of space reservation. The content of the space, files may have the same or “lesser” access latency as the space.
enum TPermissionMode {NONE, X, W, WX, R, RX, RW, RWX}
enum TPermissionType {ADD, REMOVE, CHANGE}
enum TRequestType { PREPARE_TO_GET,
PREPARE_TO_PUT,
COPY,
BRING_ONLINE,
RESERVE_SPACE,
UPDATE_SPACE,
CHANGE_SPACE_FOR_FILES,
LS }
enum TOverwriteMode {NEVER,
ALWAYS,
WHEN_FILES_ARE_DIFFERENT}
o Use case for WHEN_FILES_ARE_DIFFERENT can be that files are different when the declared size for an SURL is different from the actual one, or that the checksum of an SURL is different from the actual one.
o Overwrite mode on a file is considered higher priority than pinning a file. Where applicable, it allows to mark a valid Transfer URL to become invalid when the owner of the SURL issues an overwrite request.
enum TFileLocality { ONLINE,
NEARLINE,
ONLINE_AND_NEARLINE,
LOST,
NONE.
UNAVAILABLE }
o Files may be located online, nearline or both. This indicates if the file is online or not, or if the file reached to nearline or not. It also indicates if there are online and nearline copies of the file.
· The ONLINE indicates that there is a file on online cache of a storage system which is the part of the storage system, and the file may be accessed with online latencies.
· The NEARLINE indicates that the file is located on nearline storage system, and the file may be accessed with nearline latencies.
· The ONLINE_AND_NEARLINE indicates that the file is located on online cache of a storage system as well as on nearline storage system.
· The LOST indicates when the file is lost because of the permanent hardware failure.
· The NONE value shall be used if the file is empty (zero size).
· The UNAVAILABLE indicates that the file is unavailable due to the temporary hardware failure.
o The type will be used to describe a file property that indicates the current location or status in the storage system.
enum TAccessPattern { TRANSFER_MODE, PROCESSING_MODE }
o TAccessPattern will be passed as an input parameter to the srmPrepareToGet and srmBringOnline functions. It will make a hint from the client to SRM how the Transfer URL (TURL) produced by SRM is going to be used. If the parameter value is “ProcessingMode”, the system may expect that client application will perform some processing of the partially read data, followed by more partial reads and a frequent use of the protocol specific “seek” operation. This will allow optimizations by allocating files on disks with small buffer sizes. If the value is “TransferMode” the file will be read at the highest speed allowed by the connection between the server and a client.
enum TConnectionType { WAN, LAN }
o TConnectionType indicates if the client is connected though a local or wide area network. SRM may optimize the access parameters to achieve maximum throughput for the connection type. This will be passed as an input to the srmPrepareToGet, srmPrepareToPut and srmBringOnline functions.
enum TStatusCode { SRM_SUCCESS,
SRM_FAILURE,
SRM_AUTHENTICATION_FAILURE,
SRM_AUTHORIZATION_FAILURE,
SRM_INVALID_REQUEST,
SRM_INVALID_PATH,
SRM_FILE_LIFETIME_EXPIRED,
SRM_SPACE_LIFETIME_EXPIRED,
SRM_EXCEED_ALLOCATION,
SRM_NO_USER_SPACE,
SRM_NO_FREE_SPACE,
SRM_DUPLICATION_ERROR,
SRM_NON_EMPTY_DIRECTORY,
SRM_TOO_MANY_RESULTS,
SRM_INTERNAL_ERROR,
SRM_FATAL_INTERNAL_ERROR,
SRM_NOT_SUPPORTED,
SRM_REQUEST_QUEUED,
SRM_REQUEST_INPROGRESS,
SRM_REQUEST_SUSPENDED,
SRM_ABORTED,
SRM_RELEASED,
SRM_FILE_PINNED,
SRM_FILE_IN_CACHE,
SRM_SPACE_AVAILABLE,
SRM_LOWER_SPACE_GRANTED,
SRM_DONE,
SRM_PARTIAL_SUCCESS,
SRM_REQUEST_TIMED_OUT,
SRM_LAST_COPY,
SRM_FILE_BUSY,
SRM_FILE_LOST,
SRM_FILE_UNAVAILABLE,
SRM_CUSTOM_STATUS
}
o SRM_NOT_SUPPORTED is used, in general
· If a server does not support a method
· If a server does not support particular optional input parameters
typedef struct { TRetentionPolicy retentionPolicy,
TAccessLatency accessLatency
} TRetentionPolicyInfo
o TRetentionPolicyInfo is a combined structure to indicate how the file needs to be stored.
o When both retention policy and access latency are provided, their combination needs to match what SRM supports. Otherwise request will be rejected.
o The Request Token assigned by SRM is unique and immutable (non-reusable). For example, if the date:time is part of the request token it will be immutable.
o Request tokens are case-sensitive.
o Request token is valid until the request is completed. However, SRM server may choose to keep the request tokens for a short period of time after the request is completed, and the time period depends on the SRM servers.
typedef struct { string userID,
TPermissionMode mode
} TUserPermission
o userID may represent the associated client’s Distinguished Name (DN) instead of unix style login name. VOMS role may be included.
typedef struct { string groupID,
TPermissionMode mode
o groupID may represent the associated client’s Distinguished Name (DN) instead of unix style login name. VOMS role may be included.
1999-05-31T13:20:00 is
ok (for 1999
May 31st, 13:20PM, UTC) but 1999-05-31T13:20:00-5:00 is not.
1.19. Time in Seconds (Lifetime and RequestTime)
o The type definition SURL is represented as anyURI and used for both site URL and the “Storage File Name” (stFN). This was done in order to simplify the notation. Recall that stFN is the file path/name of the intended storage location when a file is put (or copied) into an SRM controlled space. Thus, a stFN can be thought of a special case of an SURL, where the protocol is assumed to be “srm” and the machine:port is assumed to be local to the SRM. For example, when the request srmCopy is made as a pulling case, the source file is specified by a site URL, and the target location can be optionally specified as a stFN. By considering the stFN a special case of an SURL, a srmCopy takes SURLs as both the source and target parameters.
typedef struct {TStatusCode statusCode,
string explanation
} TReturnStatus
typedef struct {anyURI surl,
TReturnStatus status
} TSURLReturnStatus
typedef struct {string path, // absolute dir and file path
unsigned long size, // 0 if directory
dateTime createdAtTime,
dateTime lastModificationTime,
TFileStorageType fileStorageType,
TRetentionPolicyInfo retentionPolicyInfo,
TFileLocality fileLocality,
string[] arrayOfSpaceTokens,
TFileType type, // Directory or File
int lifetimeAssigned,
int lifetimeLeft, // on the SURL
TUserPermission ownerPermission,
TGroupPermission groupPermission,
TPermissionMode otherPermission,
string checkSumType,
string checkSumValue,
TMetaDataPathDetail[] arrayOfSubPaths
// optional recursive
} TMetaDataPathDetail
o The TMetaDataPathDetail describes the properties of a file. It is used as an output parameter in srmLs.
o