Page 1
Acronis Storage 2.0
Object Storage Orchestration API
Reference
October 19, 2016
Page 2
Copyright Statement
Acronis International GmbH, 2002-2016. All rights reserved.
”Acronis” and ”Acronis Secure Zone” are registered trademarks of Acronis International GmbH.
”Acronis Compute with Confidence”, ”Acronis Startup Recovery Manager”, ”Acronis Active Restore”,
”Acronis Instant Restore” and the Acronis logo are trademarks of Acronis International GmbH.
Linux is a registered trademark of Linus Torvalds.
VMware and VMware Ready are trademarks and/or registered trademarks of VMware, Inc. in the United States and/or other jurisdictions.
Windows and MS-DOS are registered trademarks of Microsoft Corporation.
All other trademarks and copyrights referred to are the property of their respective owners.
Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.
Distribution of this work or derivative work in any standard (paper) book form for commercial purposes is prohibited unless prior permission is obtained
from the copyright holder.
DOCUMENTATION IS PROVIDED ”AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED
WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT
SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
Third party code may be provided with the Software and/or Service. The license terms for such third parties are detailed in the license.txt file located
in the root installation directory. You can always find the latest up-to-date list of the third party code and the associated license terms used with the
Software and/or Service at http://kb.acronis.com/content/7696
Acronis patented technologies
Technologies, used in this product, are covered and protected by one or more U.S. Patent Numbers: 7,047,380; 7,275,139; 7,281,104; 7,318,135;
7,353,355; 7,366,859; 7,475,282; 7,603,533; 7,636,824; 7,650,473; 7,721,138; 7,779,221; 7,831,789; 7,886,120; 7,895,403; 7,934,064; 7,937,612; 7,949,635;
7,953,948; 7,979,690; 8,005,797; 8,051,044; 8,069,320; 8,073,815; 8,074,035; 8,145,607; 8,180,984; 8,225,133; 8,261,035; 8,296,264; 8,312,259; 8,347,137;
8,484,427; 8,645,748; 8,732,121 and patent pending applications.
Page 3
Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 About the Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2. User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1 GET Service ostor-users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1.2 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.2.3 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.3 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.3.1 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.3.2 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.3.3 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.4.1 Sample Request #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.4.2 Sample Response #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.4.3 Sample Request #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1.4.4 Sample Response #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2 PUT Service ostor-users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.2 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.2.3 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
i
Page 4
2.2.3 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.3.1 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.3.2 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.4.1 Sample Request #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.4.2 Sample Response #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2.4.3 Sample Request #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.4.4 Sample Response #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3 DELETE Service ostor-users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3.2 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3.2.3 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3.3 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.3.1 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.3.2 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.3.3 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.4.1 Sample Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.4.2 Sample Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.4 GET Service ostor-limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4.2 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4.2.3 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4.3 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4.3.1 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4.3.2 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4.3.3 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.4.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.4.4.1 Sample Request #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.4.4.2 Sample Response #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.4.4.3 Sample Request #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
ii
Page 5
2.4.4.4 Sample Response #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.5 PUT Service ostor-limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.5.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.5.2 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.5.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.5.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.5.2.3 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.5.3 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.5.3.1 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.5.3.2 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.5.3.3 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.5.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.5.4.1 Sample Request #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.5.4.2 Sample Response #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.5.4.3 Sample Request #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.5.4.4 Sample Response #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.5.4.5 Sample Request #3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.5.4.6 Sample Response #3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.5.4.7 Sample Request #4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.5.4.8 Sample Response #4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.6 DELETE Service ostor-limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.6.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.6.2 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.6.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.6.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.6.2.3 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.6.3 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.6.3.1 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.6.3.2 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.6.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.6.4.1 Sample Request #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.6.4.2 Sample Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.6.4.3 Sample Request #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.6.4.4 Sample Response #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3. Usage Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
iii
Page 6
3.1 GET Service ostor-usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.1.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.1.2 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.1.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.1.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.1.2.3 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.1.3 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.1.3.1 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.1.3.2 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.1.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.1.4.1 Sample Request #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.1.4.2 Sample Response #1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.1.4.3 Sample Request #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.1.4.4 Sample Response #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.2 DELETE Service ostor-usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2.2 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2.2.3 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2.3 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2.3.1 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2.3.2 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.2.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.2.4.1 Sample Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.2.4.2 Sample Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
iv
Page 7
CHAPTER 1
Introduction
1.1 About the Guide
The guide explains how to use the REST API to manage S3 clusters based on Acronis Storage. The system API
enables storage administrators to manage users, limits, and billing statistics. The system REST API enables
remote execution of operations similar to ostor-s3-admin functionality.
1.2 Authentication
Management request must be authenticated with the AWS Access Key ID corresponding to the S3 system user.
You can create system users with the ostor-s3-admin create-user -S command.
1
Page 8
CHAPTER 2
User Management
2.1 GET Service ostor-users
2.1.1 Description
Lists information about all users or the user specified by either email or ID.
2.1.2 Requests
2.1.2.1 Syntax
GET /?ostor-users HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
GET /?ostor-users&emailAddress=<value> HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
GET /?ostor-users&id=<value> HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
2
Page 9
2.1. GET Service ostor-users
Authorization: <authorization_string>
2.1.2.2 Parameters
Parameter Description Required
emailAddress User email address.
Type: string.
Default value: none.
id User ID.
Type: string.
Default value: none.
* Only one of the required parameters can be set in a single request.
If neither emailAddress nor id are set, the response is information about all users, otherwise the response is
information about the user with the specified email or ID.
No*
No*
2.1.2.3 Headers
This implementation uses only common request headers.
2.1.3 Responses
2.1.3.1 Headers
This implementation uses only common response headers.
2.1.3.2 Body
A JSON dictionary with user information in the following format:
{
”UserEmail” : ”<email>”
”UserId” : ”<id>”,
3
Page 10
”AWSAccessKeys : [
{
”AWSAccessKeyId” : ”<access_key>”,
”AWSSecretAccessKey” : ”<secret_key>”
}]
}
2.1.3.3 Errors
Returns Error Code 400, if more than one parameter is set.
2.1.4 Examples
Chapter 2. User Management
2.1.4.1 Sample Request #1
Returns information about all users
GET /?ostor-users HTTP/1.1
Host: s3.amazonaws.com
Date: Wed, 30 Apr 2016 22:32:00 GMT
Authorization: <authorization_string>
2.1.4.2 Sample Response #1
HTTP/1.1 200 OK
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection : keep-alive
x-amz-request-id : 80000000000000030003c6b538eedd95
Date: Wed, 30 Apr 2016 22:32:00 GMT
Connection:keep-alive
Content-type : application/json
[
4
Page 11
2.1. GET Service ostor-users
{
”UserEmail”: ”user@email.com”,
”UserId”: ”c5bf3c29f0a86585”,
”AWSAccessKeys”: [
{
”AWSAccessKeyId”: ”c5bf3c29f0a865851KPQ”,
”AWSSecretAccessKey”: ”yqt3or2xMFn6mtvPH5Fdrr9nbp2foDCKOCLYjCTb”
}]
},
{
”UserEmail”: ”root2@email.com”,
”UserId”: ”da2ccd035ce34bc3”,
”AWSAccessKeys”: [
{
”AWSAccessKeyId”: ”da2ccd035ce34bc3XD5P”,
”AWSSecretAccessKey”: ”wHfEBQFO7HN7fhoHx45lHHyBInAOOCZTHtvveYlB”
}]
},
{
”UserEmail”: ”root0@email.com”,
”UserId”: ”f82c23f7823589eb”,
”AWSAccessKeys”: [
{
”AWSAccessKeyId”: ”f82c23f7823589ebN4KD”,
”AWSSecretAccessKey”: ”MbKetIRMW8rrZh16yfb2dMj16ejHuBHfOa37bp5V”
}]
},
{
”UserEmail”: ”root1@email.com”,
”UserId”: ”fc06056891f36588”,
”AWSAccessKeys”: [
{
”AWSAccessKeyId”: ”fc06056891f36588RMOE”,
”AWSSecretAccessKey”: ”HHD59Sf9KB4fGOxrjqhzyLBeHsODXD40QZeomKfy”
}]
5
Page 12
}]
2.1.4.3 Sample Request #2
Returns information about the user with the ID fc06056891f36588.
GET /?ostor-users&id=fc06056891f36588 HTTP/1.1
Host: s3.amazonaws.com
Date: Wed, 30 Apr 2016 22:32:00 GMT
Authorization: <authorization_string>
2.1.4.4 Sample Response #2
HTTP/1.1 200 OK
Transfer-encoding : chunked
Chapter 2. User Management
Server : nginx/1.8.1
Connection : keep-alive
x-amz-request-id : 80000000000000030003c6b538eedd95
Date: Wed, 30 Apr 2016 22:32:00 GMT
Connection:keep-alive
Content-type : application/json
{
”UserEmail”: ”root1@email.com”,
”UserId”: ”fc06056891f36588”,
”AWSAccessKeys”: [
{
”AWSAccessKeyId”: ”fc06056891f36588RMOE”,
”AWSSecretAccessKey”: ”HHD59Sf9KB4fGOxrjqhzyLBeHsODXD40QZeomKfy”
}]
}
6
Page 13
2.2. PUT Service ostor-users
2.2 PUT Service ostor-users
2.2.1 Description
Creates a new user or generates/revokes access key pairs of existing users.
2.2.2 Requests
2.2.2.1 Syntax
PUT /?ostor-users&emailAddress=<value> HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
PUT /?ostor-users&emailAddress=<value>&genKey HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
PUT /?ostor-users&emailAddress=<value>&revokeKey=<value> HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
2.2.2.2 Parameters
Parameter Description Required
emailAddress User email address.
Type: string.
Yes
Default value: none.
7
Page 14
Chapter 2. User Management
Parameter Description Required
genKey Generates a new access key pair for the user. A user can only have two
key pairs.
Type: flag.
Default value: none.
revokeKey Removes the access key pair that corresponds to the specified access
key.
Type: string.
Default value: none.
If neither genKey nor revokeKey are set, a new user with the specified email will be created.
2.2.2.3 Headers
This implementation uses only common request headers.
No
No
2.2.3 Responses
2.2.3.1 Headers
This implementation uses only common response headers.
2.2.3.2 Body
If a new user is created or a key is generated, the body is a JSON dictionary with user information.
{
”UserEmail” : ”<email>”,
”UserId” : ”<id>”,
”AWSAccessKeys : [
{
”AWSAccessKeyId” : ”<access_key>”,
”AWSSecretAccessKey” : ”<secret_key>”
}]
8
Page 15
2.2. PUT Service ostor-users
}
If a key is revoked, the body is empty.
2.2.4 Examples
2.2.4.1 Sample Request #1
Creates a user with the email test@test.test.
PUT /?ostor-users&emailAddress=test@test.test HTTP/1.1
Host: s3.amazonaws.com
Date: Thu, 07 Apr 2016 16:01:03 GMT +3:00
Authorization: <authorization_string>
2.2.4.2 Sample Response #1
HTTP/1.1 200 OK
x-amz-req-time-micros : 186132
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection : keep-alive
X-amz-request-id : 80000000000000030003746059efad68
Date : Thu, 07 Apr 2016 13:01:08 GMT
Content-type : application/json
{
”UserEmail”: ”test@test.test”,
”UserId”: ”a721fc1a64f13a05”,
”AWSAccessKeys”: [
{
”AWSAccessKeyId”: ”a721fc1a64f13a05OQF4”,
”AWSSecretAccessKey”: ”VtzYY4ZHWYzbWLUrRMSzVhB07UvD6Z5nGsAPtESV”
}]
}
9
Page 16
2.2.4.3 Sample Request #2
Generates a new key pair for the user with the email user1@email.com.
PUT /?ostor-users&emailAddress=user1@email.com&genKey HTTP/1.1
Host: s3.amazonaws.com
Date: Thu, 07 Apr 2016 15:51:13 GMT +3:00
Authorization: <authorization_string>
2.2.4.4 Sample Response #2
HTTP/1.1 200 OK
x-amz-req-time-micros : 384103
Transfer-encoding : chunked
Server : nginx/1.8.1
Chapter 2. User Management
Connection : closed
x-amz-request-id : 8000000000000003000374603639905b
Date : Thu, 07 Apr 2016 12:51:09 GMT
Content-type : application/json
{
”UserEmail”: ”user1@email.com”,
”UserId”: ”8eaa6ab4749a29b4”,
”AWSAccessKeys”: [
{
”AWSAccessKeyId”: ”8eaa6ab4749a29b4034G”,
”AWSSecretAccessKey”: ”7spuMfShCIl2tX6dFtSl7TEP7ZQbIGl1GgE0Emdy”
},
{
”AWSAccessKeyId”: ”8eaa6ab4749a29b4EJUY”,
”AWSSecretAccessKey”: ”ELzQ8CTMFcYQCGSP5lnGvmJxFC9xXrEJ4CjBAA2k”
}]
10
}
Page 17
2.3. DELETE Service ostor-users
2.3 DELETE Service ostor-users
2.3.1 Description
Deletes the user specified by email or ID.
2.3.2 Requests
2.3.2.1 Syntax
DELETE /?ostor-users&emailAddress=<value> HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
2.3.2.2 Parameters
Parameter Description Required
emailAddress User email address.
Type: string.
Default value: none.
id User ID.
Type: string.
Default value: none.
* Only one of the required parameters can be set in a single request.
Yes*
Yes*
2.3.2.3 Headers
This implementation uses only common request headers.
11
Page 18
2.3.3 Responses
2.3.3.1 Headers
This implementation uses only common response headers.
2.3.3.2 Body
Empty.
2.3.3.3 Errors
Returns Error Code 400, if more than one required parameter is set.
Chapter 2. User Management
Note: If a user is successfully deleted, Status204NoContent is returned.
2.3.4 Examples
2.3.4.1 Sample Request
Deletes the user with the email test@test.test.
DELETE /?ostor-users&emailAddress=test@test.test HTTP/1.1
Host: s3.amazonaws.com
Date: Wed, 30 Apr 2016 22:32:00 GMT
Authorization: <authorization_string>
2.3.4.2 Sample Response
HTTP/1.1 203 No Content
x-amz-req-time-micros : 172807
Server : nginx/1.8.1
Connection : closed
12
Page 19
2.4. GET Service ostor-limits
x-amz-request-id : 80000000000000030005c8ca5862476a
Date : Wed, 30 Apr 2016 22:32:03 GMT
Content-type : application/xml
2.4 GET Service ostor-limits
2.4.1 Description
Lists information about limits on operations and bandwidth for the specified user or bucket.
2.4.2 Requests
2.4.2.1 Syntax
GET /?ostor-limits&emailAddress=<value> HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
GET /?ostor-limits&bucket=<value> HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
2.4.2.2 Parameters
Parameter Description Required
emailAddress User email address.
Yes*
Type: string.
Default value: none.
13
Page 20
Chapter 2. User Management
Parameter Description Required
id User ID.
Type: string.
Default value: none.
bucket Bucket name.
Type: string.
Default value: none.
* Only one of the required parameters can be set in a single request.
2.4.2.3 Headers
This implementation uses only common request headers.
2.4.3 Responses
Yes*
Yes*
2.4.3.1 Headers
This implementation uses only common response headers.
2.4.3.2 Body
A JSON dictionary with information about limits for a user or bucket in the following format:
{
”ops:default” : ”<default_limit_value_in_ops/sec>”,
”ops:get” : ”<get_ops_limit_value_in_ops/sec>”,
”ops:put” : ”<put_ops_limit_value_in_ops/sec>”,
”ops:list” : ”<list_ops_limit_value_in_ops/sec>”,
”ops:delete” : ”<delete_ops_limit_value_in_ops/sec>”,
”bandwidth:out” : ”<bandwidth_limit_value_in_kb/sec>”,
}
14
Page 21
2.4. GET Service ostor-limits
Note: 0 means “unlimited”.
2.4.3.3 Errors
Returns Error Code 400, if multiple parameters are set at once.
Note: The limits are disabled by default. If limits for a user/bucket requested are disabled, an error will
be returned. Use PUT ostor-limits to enable limits.
2.4.4 Examples
2.4.4.1 Sample Request #1
Returns information about limits for the user with the email user1@email.com.
GET /?ostor-users&emailAddress=user1@email.com HTTP/1.1
Host: s3.amazonaws.com
Date: Thu, 07 Apr 2016 14:08:55 GMT
Authorization: <authorization_string>
2.4.4.2 Sample Response #1
HTTP/1.1 200 OK
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection: closed
x-amz-request-id : 80000000000000030005c8caec96d65b
Date : Thu, 07 Apr 2016 14:08:56 GMT
Content-type : application/json
{
”ops:default” : ”0.50”,
15
Page 22
”ops:get” : ”0.50”,
”ops:put” : ”0.50”,
”ops:list” : ”0.50”,
”ops:delete” : ”0.50”,
”bandwidth:out” : ”0”
}
2.4.4.3 Sample Request #2
Returns information about limits for the bucket bucket-1.
GET /?ostor-limits&bucket=bucket-1 HTTP/1.1
Host: s3.amazonaws.com
Date: Wed, 30 Apr 2016 22:32:00 GMT
Authorization: <authorization_string>
Chapter 2. User Management
2.4.4.4 Sample Response #2
HTTP/1.1 200 OK
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection : closed
x-amz-request-id : 80000000000000030003c6b538eedd95
Date: Wed, 30 Apr 2016 22:32:00 GMT
Content-type : application/json
{
”ops:default” : ”0”,
”ops:get” : ”0”,
”ops:put” : ”0”,
”ops:list” : ”0”,
”ops:delete” : ”0”,
”bandwidth:out” : ”3.33”
}
16
Page 23
2.5. PUT Service ostor-limits
2.5 PUT Service ostor-limits
2.5.1 Description
Sets limit values for the specified user or bucket. Either operations count or bandwidth limits can be specified
in a single request.
2.5.2 Requests
2.5.2.1 Syntax
PUT /?ostor-limits&emailAddress=<value> HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
GET /?ostor-limits&bucket=<value> HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
2.5.2.2 Parameters
Parameter Description Required
emailAddress User email address.
Type: string.
Default value: none.
id User ID.
Type: string.
Yes*
Yes*
Default value: none.
bucket Bucket name.
Type: string.
Default value: none.
Yes
17
Page 24
Chapter 2. User Management
Parameter Description Required
bandwidth Enables bandwidth limits.
Bandwidth limits types: { out | kb/s }
Type: flag.
ops Enables operations limits. If set, all unspecified bandwidth limits are
set to 0.
Operations limits types: { default | ops/min, put | ops/min , get |
ops/min, list | ops/min, delete | ops/min }
Type: flag.
default Sets the default value for operations limits. If set, all unspecified oper-
ations limits are set to default, otherwise they are set to 0.
Requires the ops subresource to be set.
Type: integer.
Default: 0.
put Sets the PUT operations limit value.
Requires the ops subresource to be set.
Type: integer.
Default: default.
Yes**
Yes**
No
No
get Sets the GET operations limit value.
Requires the ops subresource to be set.
Type: integer.
Default: default.
delete Sets the DELETE operations limit value.
Requires the ops subresource to be set.
Type: integer.
Default: default.
list Sets the LIST operations limit value.
Requires the ops subresource to be set.
Type: integer.
Default: default.
out Sets an outgoing bandwidth limit.
Requires the ops subresource to be set.
Type: integer.
Default: 0.
No
No
No
No
18
Page 25
2.5. PUT Service ostor-limits
* Only one of the required parameters can be set in a single request.
** Either ops or bandwidth can be set in a single request.
Note: Zero limit value means “unlimited”.
2.5.2.3 Headers
This implementation uses only common request headers.
2.5.3 Responses
2.5.3.1 Headers
This implementation uses only common response headers.
2.5.3.2 Body
Empty.
2.5.3.3 Errors
Returns Error Code 400, if a wrong set of parameters is specified.
2.5.4 Examples
2.5.4.1 Sample Request #1
Sets all operations limits for the user with the email user1@email.com to zero.
PUT /?ostor-limits&emailAddress=user1@email.com&ops&default=0 HTTP/1.1
Host: s3.amazonaws.com
Date: Thu, 07 Apr 2016 14:08:55 GMT
Authorization: <authorization_string>
19
Page 26
Chapter 2. User Management
2.5.4.2 Sample Response #1
HTTP/1.1 200 OK
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection: closed
x-amz-request-id : 80000000000000030005c8caec96d65b
Date : Thu, 07 Apr 2016 14:08:56 GMT
Content-type : application/json
2.5.4.3 Sample Request #2
Sets all operations limits for the user with the email user1@email.com to 1 ops/sec.
PUT /?ostor-limits&emailAddress=user1@email.com&ops&default=60 HTTP/1.1
Host: s3.amazonaws.com
Date: Thu, 07 Apr 2016 14:08:55 GMT
Authorization: <authorization_string>
2.5.4.4 Sample Response #2
HTTP/1.1 200 OK
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection: closed
x-amz-request-id : 80000000000000030005c8caec96d65b
Date : Thu, 07 Apr 2016 14:08:56 GMT
Content-type : application/json
2.5.4.5 Sample Request #3
Sets all badwidth.out limit for the bucket testbucket to 50 kb/s.
PUT /?ostor-limits&bucket=testbucket&bandwidth&out=50 HTTP/1.1
Host: s3.amazonaws.com
20
Page 27
2.5. PUT Service ostor-limits
Date: Thu, 07 Apr 2016 14:08:55 GMT
Authorization: <authorization_string>
2.5.4.6 Sample Response #3
HTTP/1.1 200 OK
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection: closed
x-amz-request-id : 80000000000000030005c8caec96d65b
Date : Thu, 07 Apr 2016 14:08:56 GMT
Content-type : application/json
2.5.4.7 Sample Request #4
Sets operations limits for the bucket testbucket. The new PUT operations limit is 60 ops/s, LIST limit is 0.5 ops/s,
GET and DELETE limits are 1 ops/s.
PUT /?ostor-limits&bucket=testbucket&ops&default=60&put=3600&list=30 HTTP/1.1
Host: s3.amazonaws.com
Date: Thu, 07 Apr 2016 14:08:55 GMT
Authorization: <authorization_string>
2.5.4.8 Sample Response #4
HTTP/1.1 200 OK
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection: closed
x-amz-request-id : 80000000000000030005c8caec96d65b
Date : Thu, 07 Apr 2016 14:08:56 GMT
Content-type : application/json
21
Page 28
Chapter 2. User Management
2.6 DELETE Service ostor-limits
2.6.1 Description
Sets a limit of the selected type to 0.0 (unlimited) for the specified user or bucket.
2.6.2 Requests
2.6.2.1 Syntax
DELETE /?ostor-limits&emailAddress=<value>&ops HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
DELETE /?ostor-limits&id=<value>&ops HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
DELETE /?ostor-limits&bucket=<value>&bandwidth HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
2.6.2.2 Parameters
Parameter Description Required
emailAddress User email address.
Type: string.
Yes*
22
Default value: none.
Page 29
2.6. DELETE Service ostor-limits
Parameter Description Required
id User ID.
Type: string.
Default value: none.
bucket Bucket name.
Type: string.
Default value: none.
ops Removes operations limits. No
bandwidth Removes bandwidth limits. No
* Only one of the required parameters can be set in a single request.
2.6.2.3 Headers
This implementation uses only common request headers.
2.6.3 Responses
Yes*
Yes*
2.6.3.1 Headers
This implementation uses only common response headers.
2.6.3.2 Body
Empty.
Note: If limits are successfully removed, Status204NoContent will be returned.
2.6.4 Examples
2.6.4.1 Sample Request #1
The following request deletes all operations limits for a user with the email user1@email.com.
23
Page 30
PUT /?ostor-limits&emailAddress=user1@email.com&ops HTTP/1.1
Host: s3.amazonaws.com
Date: Thu, 07 Apr 2016 14:08:55 GMT
Authorization: <authorization_string>
2.6.4.2 Sample Response
HTTP/1.1 204 No Content
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection: closed
x-amz-request-id : 80000000000000030005c8caec96d65b
Date : Thu, 07 Apr 2016 14:08:56 GMT
Content-type : application/json
Chapter 2. User Management
2.6.4.3 Sample Request #2
The following request removes bandwidth limits for the bucket testbucket.
PUT /?ostor-limits&bucket=testbucket&bandwidth HTTP/1.1
Host: s3.amazonaws.com
Date: Thu, 07 Apr 2016 14:08:55 GMT
Authorization: <authorization_string>
2.6.4.4 Sample Response #2
HTTP/1.1 204 No Content
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection: closed
x-amz-request-id : 80000000000000030005c8caec96d65b
Date : Thu, 07 Apr 2016 14:08:56 GMT
Content-type : application/json
24
Page 31
CHAPTER 3
Usage Statistics
The S3 gateway can collect usage statistics for S3 users and S3 buckets. The collected data are saved as regular
Object Storage objects. One such object contains statistics for the set usage period.
To enable statistics collection, set S3_GW_USAGE_BUCKET to True in the gateway configuration file
(/var/lib/ostor/local/gw.conf by default).
Other options you may need to set are: S3_GW_USAGE_PERIOD (usage period in a single statistics object, in seconds)
and S3_GW_USAGE_CACHE_TIMEOUT (the frequency of dumping statistics from memory to storage, in seconds).
3.1 GET Service ostor-usage
3.1.1 Description
Lists existing statistics objects or queries information contained in a specified object.
3.1.2 Requests
3.1.2.1 Syntax
GET /?ostor-users HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
25
Page 32
Chapter 3. Usage Statistics
GET /?ostor-users&obj=object name
HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Authorization: <authorization_string>
3.1.2.2 Parameters
The parameter is specified by the obj subresource. If the obj subresource is undefined, the response contains
information about all existing statistics objects. Otherwise information from the specified object obj is returned.
Parameter Description Required
obj Statistics object name.
Type: string.
Default value: none.
3.1.2.3 Headers
This implementation uses only common request headers.
3.1.3 Responses
3.1.3.1 Headers
This implementation uses only common response headers.
3.1.3.2 Body
No
If obj is unspecified:
{ ”nr_items”: number of statistics objects,
”truncated”: true if a list is truncated,
”items”: [ //list of statistics objects
”first object’s name”,
26
Page 33
3.1. GET Service ostor-usage
”s3-usage-obj1”,
”s3-usage-obj2”,
”s3-usage-obj3”,
...
]
}
If obj is specified:
{ ”fmt_version”: version of response format,
”service_id”: idof a service that collected statistics,
”start_ts”: timestamp of statistics upload,
”period”: statistics upload period in seconds,
”nr_items”: number of counters,
”items”: [//list of usage counters
{
”key”: { ”bucket”: ”bucket-name”, ”epoch”:bucket’s epoch, ”user_id”: ”user id”, ”tag”: ”statistics object tag” },
”counters”: {
”ops”: { ”put”:count of put ops, ”get”: count of get ops, ”list”: count of list ops, ”other”: count of other ops },
”net_io”: { ”uploaded”:number of uploaded bytes during the period,
”downloaded”: number of downloaded bytes during the period }
}
},
...
]
}
3.1.4 Examples
3.1.4.1 Sample Request #1
The following request returns information about all statistics objects.
GET /?ostor-usage /HTTP1.1
Date : Mon, 11 Apr 2016 16:43:16 GMT+3:00
Host : ostor-test-1
27
Page 34
Authorization : <authorization_string>
3.1.4.2 Sample Response #1
HTTP/1.1 200 OK
x-amz-req-time-micros : 404
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection : keep-alive
x-amz-request-id : 80000000000000030006b6be3b0ae378
Date : Mon, 11 Apr 2016 13:43:16 GMT
Content-type : application/json
{ ”nr_items”: 9,
Chapter 3. Usage Statistics
”truncated”: false,
”items”: [
”s3-usage-8000000000000003-2016-04-11T13:10:29.000Z-1800”,
”s3-usage-8000000000000003-2016-04-11T13:12:53.000Z-30”,
”s3-usage-8000000000000003-2016-04-11T13:13:23.000Z-30”,
”s3-usage-8000000000000003-2016-04-11T13:15:53.000Z-30”,
”s3-usage-8000000000000003-2016-04-11T13:16:23.000Z-30”,
”s3-usage-8000000000000003-2016-04-11T13:31:54.000Z-30”,
”s3-usage-8000000000000003-2016-04-11T13:33:25.000Z-30”,
”s3-usage-8000000000000003-2016-04-11T13:33:55.000Z-30”,
”s3-usage-8000000000000003-2016-04-11T13:34:25.000Z-30”
]
}
3.1.4.3 Sample Request #2
The following request returns information from the object s3-usage-8000000000000003-2016-04-11T13:33:55.000Z-30.
GET /?ostor-usage&obj=s3-usage-8000000000000003-2016-04-11T13:12:53.000Z-30 /HTTP1.1
Date: Mon, 11 Apr 2016 17:48:21 GMT+3:00
Host: ostor-test-1
28
Page 35
3.1. GET Service ostor-usage
Authorization: <authorization_string>
3.1.4.4 Sample Response #2
HTTP/1.1 200 OK
X-amz-req-time-micros : 576
Transfer-encoding : chunked
Server : nginx/1.8.1
Connection : keep-alive
X-amz-request-id : 80000000000000030006b6bf23c77f09
Date : Mon, 11 Apr 2016 14:48:21 GMT
Content-type : application/json
{ ”fmt_version”: 1, ”service_id”:8000000000000003,
”start_ts”:1460380373, ”period”: 30, ”nr_items”:2,
”items”: [
{
”key”: { ”bucket”: ”bucket”, ”epoch”:16394, ”user_id”: ”f82c23f7823589eb”, ”tag”: ”” },
”counters”: {
”ops”: { ”put”:15, ”get”:0, ”list”:1, ”other”:0 },
”net_io”: { ”uploaded”:99785, ”downloaded”:0 }
}
},
{
”key”: { ”bucket”: ””, ”epoch”:0, ”user_id”: ”f82c23f7823589eb”, ”tag”: ”” },
”counters”: {
”ops”: { ”put”:0, ”get”:2, ”list”:0, ”other”:0 },
”net_io”: { ”uploaded”:0, ”downloaded”:0 }
}
}
]
}
29
Page 36
3.2 DELETE Service ostor-usage
3.2.1 Description
Deletes the statistics object specified by name.
3.2.2 Requests
3.2.2.1 Syntax
DELETE /?ostor-users&obj=<object_name> HTTP/1.1
Host: s3.amazonaws.com
Date: <date>
Chapter 3. Usage Statistics
Authorization: <authorization_string>
3.2.2.2 Parameters
Parameter Description Required
obj Statistics object name.
Type: string.
Default value: none.
No
3.2.2.3 Headers
This implementation uses only common request headers.
3.2.3 Responses
3.2.3.1 Headers
This implementation uses only common response headers.
30
Page 37
3.2. DELETE Service ostor-usage
3.2.3.2 Body
Empty.
Note: If the request is successful, Status204NoContent is returned.
3.2.4 Examples
3.2.4.1 Sample Request
The following request deletes statistics object with name s3-usage-8000000000000003-2016-04-11T13:33:55.000Z-30.
DELETE /?ostor-usage&obj=s3-usage-8000000000000003-2016-04-11T13:12:53.000Z-30 /HTTP1.1
Date : Mon, 11 Apr 2016 17:52:05 GMT+3:00
Host : ostor-test-1
Authorization : authorization string
3.2.4.2 Sample Response
HTTP/1.1 204 No Content
Date : Mon, 11 Apr 2016 14:52:05 GMT
x-amz-req-time-micros : 4717
Connection : keep-alive
x-amz-request-id : 80000000000000030006b6bf31262d2c
Server : nginx/1.8.1
31
Loading...