Contributors to this document are: EDG-WP2 Peter Kunszt, Heinz Stockinger, Kurt Stockinger, Erwin Laure EDG-WP5 Jean-Philippe Baud, Stefano Occhetti, Jens Jensen, Emil Knezo, Owen Synge, Olof Barring JLAB Bryan Hess, Andy Kowalski, Chip Watson FNAL Don Petravick, Timur Perelmutov, Rich Wellner LBNL Junmin Gu , Arie Shoshani, Alex Sim The version 2.1 was prepared by Timur Perelmutov, Fermilab. The version 2.1.1 was modified by Alex Sim, LBNL. on basis of the Storage Resource Manager Interface Specification version 2.1.1 published at http://sdm.lbl.gov/srm-wg The requestToken assigned by SRM is unique and immutable (non-reusable). For example, if the date:time is part of the requestToken it will be immutable. The type definition SURL above is 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, 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, an srmCopy takes SURLs as both the source and target parameters. TMetaDataSpace can refer to a single space of each type (i.e. volatile, durable, permanent). It does not include the extra space needed to hold the directory structures. storageSystemInfo is a string that contains the login and password required by the storage system. For example, it might have the form of login:passwd@hostname, where ":" is a reserved separator between login and passwd. If hostname is not provided, it is defaulted to what's in the accompanying site URL or the host of SRM. TstorageSystemInfo can contain but is not limited to the following: storage device, storage login ID, storage login authorization. the default value of "lifetime" for Volatile or Durable files will be the lifetime left in the space of the corresponding file type. The default value of "fileType" is Volatile. the default value of "lifetime" for Volatile or Durable files will be the lifetime left in the space of the corresponding file type. The default value of "fileType" is Volatile. the default value of "lifetime" for Volatile or Durable files will be the lifetime left in the space of the corresponding file type. The default value of "fileType" is Volatile. Status codes represent errors, warnings and status. Status code Explanation SRM_SUCCESS: SRM request was successful Errors: SRM_FAILURE : Requested operation failed for unspecified reason, and additional info is in the explanation string. SRM_AUTHENTICATION_FAILURE: Requester has an invalid authentication information. SRM_UNAUTHORIZED_ACCESS: Requester has no permissions for the operation (although the user could have a valid authentication information). SRM_INVALID_REQUEST: The request is invalid, and additional information may be provided in the explanation string. For example, The request token is invalid The requested life time of a file is longer than the lifetime of the space. SRM_INVALID_PATH: The requested file/directory path is invalid. SRM_FILE_LIFETIME_EXPIRED: The life time on the pinned file has expired SRM_SPACE_LIFETIME_EXPIRED: The life time on the reserved space has expired SRM_EXCEED_ALLOCATION: Requester exceeded allocation (number of requests, files or spaces), and the request cannot be placed. SRM_NO_USER_SPACE: The requester does not have enough space to put the file into that space. SRM_NO_FREE_SPACE: SRM has not more space. SRM_DUPLICATION_ERROR : Requester tried to create a new file or directory that already exists. SRM_NON_EMPTY_DIRECTORY: Requester tried to remove a non-empty directory without the recursive option set. SRM_TOO_MANY_RESULTS: The request produced too many results; for example, as a result of srmLs. The term "too many" is determined by each SRM , and the detailed information, such as the supported max number of results can be returned in the explanation string. SRM_INTERNAL_ERROR: SRM has an internal error temporarily. Client may try again. SRM_FATAL_INTERNAL_ERROR: SRM has a severe internal error that cannot be recovered. SRM_NOT_SUPPORTED: SRM implementation does not support this functionality that client requested. Status: SRM_REQUEST_QUEUED SRM_REQUEST_INPROGRESS SRM_REQUEST_SUSPENDEND SRM _ABORTED SRM _RELEASED SRM_FILE_PINNED The requested file is pinned SRM_FILE_IN_CACHE The file is in cache, but not pinned SRM_SPACE_AVAILABLE The requested space is reserved and ready to be used SRM_LOWER_SPACE_GRANTED The requested space is not ready, but lower sized space is granted. SRM _DONE SRM_CUSTOM_STATUS: SRM has a site specific status information. The details are described in the explanation string. all the following complex types are introduced for the purpose of specifying the optional operation parameters lifetimeOfSpaceToReserve is not needed if requesting permanent space. SRM can provide default size and lifetime if not supplied. storageSystemInfo is optional in case storage system requires additional security check. If sizeOfTotalSpaceDesired is not specified, the SRM will return its default quota. forceFileRelease=false is default. This means that the space will not be released if it has files that are still pinned in the space. To release the space regardless of the files it contains and their status forceFileRelease=true must be specified. To be safe, a request to release a reserved space that has an on-going file transfer will return false, even forceFileRelease= true. When space is releasable and forceFileRelease=true, all the files in the space are released, even in durable or permanent space. When space is released, the files in that space are treated according to their types: If permanent, keep it. If durable, perform action at the end of lifetime. If Volatile, release it at the end of lifetime. Includes size and time If neither size nor lifetime are supplied in the input, then return will be null. newSize is the new actual size of the space, so has to be positive. newLifetimeFromCallingTime is the new lifetime requested regardless of the previous lifetime, and has to be positive. It might even be shorter than the remaining lifetime at the time of the call. This function is called to reclaim the space for all released files and update space size in Durable and Permanent spaces. Files not released are not going to be removed (even if lifetime expired.) doDynamicCompactFromNowOn=false by default, which implies that only a one time compactSpace will take place. If doDynamicCompactFromNowOn=true, then the space of released files will be automatically compacted until the value of doDynamicCompactFromNowOn is set to false. When space is compacted, the files in that space do not have to be removed by the SRM. For example, the SRM can choose to move them to volatile space. The client will only perceive that the compacted space is now available to them. To physically force a removal of a file, the client should use srmRm. Applies to both dir and dile Either path must be supplied. If a path is pointing to a directory, then the effect is recursive for all the files in this directory. Space allocation and de-allocation maybe involved. If userSpaceTokenDescription is null, returns all space tokens this user owns If the user assigned the same name to multiple space reservations, he may get back multiple space tokens. Applies to both dir and file Support for srmSetPermission is optional. In this version, TPermissionMode is identical to Unix permission modes. User permissions are provided in order to support dynamic user-level permission assignment similar to Access Control Lists (ACLs). Permissions can be assigned to set of users and sets of groups, but only a single owner. In this version, SRMs do not provide any group operations (setup, modify, remove, etc.) Groups are assumed to be setup before srmSetPermission is used. If TPermissionType is ADD or CHANGE, and TPermissionMode is null, then it is assumed that TPermissionMode is READ only. If TPermissionType is REMOVE, then the TPermissionMode is ignored. After lifeTimeOfThisAssignment time period, or when assignedUser obtained a copy of files through srmCopy(), the files involved are released and space is compacted automatically, which ever is first. This function implies actual lifetime of file/space involved is extended up to the lifeTimeOfThisAssignment. The caller must be the owner of the files to be reassigned. permission is omitted because it has to be READ permission. lifeTimeOfThisAssignment is relative to the calling time. So it must be positive. If the path here is a directory, then all the files under it are included recursively. If there are any files involved that are released before this function call, then these files will not be involved in reassignment, even if they are still in the space. If a compact() is called before this function is complete, then this function has priority over compact(). Compact will be done automatically as soon as files are copies to the assignedUser. Whether to dynamically compact or not is an implementation choice. When checkInLocalCacheOnly=true, then SRM will only check files in its local cache. Otherwise, if a file is not in its local cache, then SRM will go to the siteURL to check the user permission. If checkInLocalCacheOnly = false, SRM can choose to always check the siteURL for user permission of each file. It is also ok if SRM choose to check its local cache first, if a file exists and the user has permission, return that permission. Otherwise, check the siteURL and return permission. Consistent with unix, recursive creation of directories is not supported. newDiretoryPath can include paths, as long as all sub directories exist. applies to dir doRecursiveRemove is false by default. To distinguish from srmRm(), this function is for directories only. Applies to files To distinguish from srmRmDir(), this function applies to files only. Applies to both dir and file fullDetailedList=false by default. For directories, only path is required to be returned. For files, path and size are required to be returned. If fullDetailedList=true, the full details are returned. For directories, path and userPermission are required to be returned. For files, path, size, userPermission, lastModificationTime, typeOfThisFile, and lifetimeLeft are required to be returned, similar to unix command ls -l. If allLevelRecursive=true then file lists of all level below current will be provided as well. If allLevelRecursive is "true" it dominates, i.e. ignore numOfLevels. If allLevelRecursive is "false" or missing, then do numOfLevels. If numOfLevels is "0" (zero) or missing, assume a single level. If both allLevelRecursive and numOfLevels are missing, assume a single level. When listing for a particular type specified by "fileStorageType", only the files with that type will be in the output. Empty directories will be returned. We recommend width first in the listing. We recommend that list of directories come before list of files in the return array (details). Applies to both dir and file Authorization checks need to be performed on both fromPath and toPath. The userRequestDescription is a user designated name for the request. It can be used in the getRequestID method to get back the system assigned request ID. Only pull mode is supported. SRM assigns the requestToken at this time. Normally this call will be followed by srmRelease(). "retryTime" means: if all the file transfer for this request are complete, then try previously failed transfers for a total time period of "retryTime". In case that the retries fail, the return should include an explanation of why the retries failed. This call is an asynchronous (non-blocking) call. To get subsequent status and results, separate calls should be made. When the file is ready for the user, the file is implicitly pinned in the cache and lifetime will be enforced. The invocation of srmReleaseFile() is expected for finished files later on. Only push mode is supported for srmPrepareToPut. StFN ("toSURLInfo" in the TPutFileRequest) has to be local. If stFN is not specified, SRM will name it automatically and put it in the specified user space. This will be returned as part of the "transfer URL". srmPutDone() is expected after each file is "put" into the allocated space. The lifetime of the file starts as soon as SRM get the srmPutDone(). If srmPutDone() is not provided then the files in that space are subject to removal when the space lifetime expires. "retryTime" is meaningful here only when the file destination is not a local disk, such as tape or MSS. In case that the retries fail, the return should include an explanation of why the retires failed. Pull mode: copy from remote location to SRM. (e.g. from remote to MSS.) Push mode: copy from SRM to remote location. Always release files from source after copy is done. When removeSourceFiles=true, then SRM will remove the source files on behalf of the caller after copy is done. In pull mode, send srmRelease() to remote location when transfer is done. If in push mode, then after transfer is done, notify the caller. User can then release the file. If user releases a file being copied to another location before it is done, then refuse to release. Note there is no protocol negotiation with the client for this request. "retryTime" means: if all the file transfer for this request are complete, then try previously failed transfers for a total time period of "retryTime". In case that the retries fail, the return should include an explanation of why the retires failed. When both fromSURL and toSURL are local, perform local copy Empty directories are copied as well. If requestToken is not provided, then the SRM will do nothing. It has the effect of a release before the file is removed. If file is not in cache, do nothing dir is ok. Will release recursively for dirs. If requestToken is not provided, then the SRM will release all the files specified by the siteURLs owned by this user, regardless of the requestToken. If requestToken is not provided, then authorizationID is needed. It may be inferred or provide in the call. Releasing files will be followed by compacting space, if doDynamicCompactFromNowOn was set to true in a previous srmCompactSpace call. Called by user after srmPut() Abort all files in this request regardless of the state. Expired files are released. Abort all files in this call regardless of the state Suspend all files in this request until srmResumeRequest is issued Resume suspended files in this request If arrayOfFromSURLs is not provided, returns status for all the file requests in this request. If arrayOfToSURLs is not provided, returns status for all the file requests in this request. If arrayOfFromSURLs and/or arrayOfToSURLs are not provided, return status for all the file requests in this request. newLifeTime is relative to the calling time. Lifetime will be set from the calling time for the specified period. The number of lifetime extensions maybe limited by SRM according to its policies. IsExtended = false if SRM refuse to do it. (set newTimeExtended = 0 in this case.) If original lifetime is longer than the requested one, then the requested one will be assigned. If newLifeTime is not specified, the SRM can use its default to assign the newLifeTime. If userRequestDescription is null, returns all requests this user has. If the user assigned the same name to multiple requests, he may get back multiple request IDs each with the time the request was made. the following location of the service is specific to the particular deployment and is not part of the specification