Cloudian HyperStore

AWS APIs Support Reference

Support for the S3 API

and the IAM, STS, and SQS APIs

Version 8.1
This page left intentionally blank.
Confidentiality Notice

The information contained in this document is confidential to, and is the intellectual property of, Cloudian,
Inc. Neither this document nor any information contained herein may be (1) used in any manner other than
to support the use of Cloudian software in accordance with a valid license obtained from Cloudian, Inc, or (2)
reproduced, disclosed or otherwise provided to others under any circumstances, without the prior written per-
mission of Cloudian, Inc. Without limiting the foregoing, use of any information contained in this document in
connection with the development of a product or service that may be competitive with Cloudian software is
strictly prohibited. Any permitted reproduction of this document or any portion hereof must be accompanied
by this legend.
This page left intentionally blank.
Contents
Chapter 1. S3 API 13
1.1. Introduction 13

1.1.1. HyperStore Support for the AWS S3 API 13

1.1.2. S3 Client Application Options 14

1.1.3. Authenticating Requests (AWS Signature Version 4) 15

1.1.4. Access Control List (ACL) Support 16

1.1.5. S3 Common Request and Response Headers 17

1.1.6. S3 Error Responses 18

1.1.7. HyperStore Extensions to the S3 API 20

1.2. Supported S3 Operations 21

1.2.1. AbortMultipartUpload 21

1.2.2. CompleteMultipartUpload 21

1.2.3. CopyObject 22

1.2.4. CreateBucket 23

1.2.5. CreateMultipartUpload 25

1.2.6. DeleteBucket 26

1.2.7. DeleteBucketCors 26

1.2.8. DeleteBucketEncryption 27

1.2.9. DeleteBucketInventoryConfiguration 27

1.2.10. DeleteBucketLifecycle 27

1.2.11. DeleteBucketOwnershipControls 27

1.2.12. DeleteBucketPolicy 27

1.2.13. DeleteBucketReplication 27

1.2.14. DeleteBucketTagging 28

1.2.15. DeleteBucketWebsite 28

1.2.16. DeleteObject 28

1.2.17. DeleteObjects 29

1.2.18. DeleteObjectTagging 30

1.2.19. DeletePublicAccessBlock 30
1.2.20. GetBucketAcl 30

1.2.21. GetBucketCors 31

1.2.22. GetBucketEncryption 31

1.2.23. GetBucketInventoryConfiguration 32

1.2.24. GetBucketLifecycle 33

1.2.25. GetBucketLifecycleConfiguration 33

1.2.26. GetBucketLocation 34

1.2.27. GetBucketLogging 35

1.2.28. GetBucketNotificationConfiguration 35

1.2.29. GetBucketOwnershipControls 36

1.2.30. GetBucketPolicy 36

1.2.31. GetBucketPolicyStatus 36

1.2.32. GetBucketReplication 37

1.2.33. GetBucketTagging 37

1.2.34. GetBucketVersioning 37

1.2.35. GetBucketWebsite 38

1.2.36. GetObject 38

1.2.37. GetObjectAcl 40

1.2.38. GetObjectLegalHold 40

1.2.39. GetObjectLockConfiguration 41

1.2.40. GetObjectRetention 41

1.2.41. GetObjectTagging 41

1.2.42. GetObjectTorrent 42

1.2.43. GetPublicAccessBlock 42

1.2.44. HeadBucket 43

1.2.45. HeadObject 43

1.2.46. ListBucketInventoryConfigurations 45

1.2.47. ListBuckets 46

1.2.48. ListMultipartUploads 47

1.2.49. ListObjects 48
 1.2.50. ListObjectsV2 49

1.2.51. ListObjectVersions 51

1.2.52. ListParts 52

1.2.53. OPTIONS Object 54

1.2.54. POST Object 54

1.2.55. PutBucketAcl 56

1.2.56. PutBucketCors 56

1.2.57. PutBucketEncryption 57

1.2.58. PutBucketInventoryConfiguration 58

1.2.59. PutBucketLifecycle 59

1.2.60. PutBucketLifecycleConfiguration 59

1.2.61. PutBucketLogging 65

1.2.62. PutBucketNotificationConfiguration 65

1.2.63. PutBucketOwnershipControls 66

1.2.64. PutBucketPolicy 67

1.2.65. PutBucketReplication 72

1.2.66. PutBucketTagging 73

1.2.67. PutBucketVersioning 74

1.2.68. PutBucketWebsite 74

1.2.69. PutObject 75

1.2.70. PutObjectAcl 76

1.2.71. PutObjectLegalHold 77

1.2.72. PutObjectLockConfiguration 77

1.2.73. PutObjectRetention 78

1.2.74. PutObjectTagging 78

1.2.75. PutPublicAccessBlock 79

1.2.76. RestoreObject 80

1.2.77. UploadPart 80

1.2.78. UploadPartCopy 81

Chapter 2. IAM API 83

2.1. Introduction 83

2.1.1. HyperStore Support for the AWS IAM API 83

2.1.2. IAM Client Application Options 85

2.1.3. IAM Common Request Parameters 87

2.1.4. IAM Common Errors 87

2.2. Supported IAM Actions 88

2.2.1. AddUserToGroup 88

2.2.2. AttachGroupPolicy 88

2.2.3. AttachRolePolicy 89

2.2.4. AttachUserPolicy 89

2.2.5. CreateAccessKey 90

2.2.6. CreateGroup 90

2.2.7. CreatePolicy 91

2.2.8. CreatePolicyVersion 92

2.2.9. CreateRole 92

2.2.10. CreateSAMLProvider 94

2.2.11. CreateUser 94

2.2.12. CreateVirtualMFADevice 95

2.2.13. DeactivateMFADevice 97

2.2.14. DeleteAccessKey 97

2.2.15. DeleteGroup 97

2.2.16. DeleteGroupPolicy 98

2.2.17. DeletePolicy 98

2.2.18. DeletePolicyVersion 99

2.2.19. DeleteRole 99

2.2.20. DeleteRolePolicy 100

2.2.21. DeleteSAMLProvider 100

2.2.22. DeleteUser 100

2.2.23. DeleteUserPolicy 101

2.2.24. DeleteVirtualMFADevice 101

2.2.25. DetachGroupPolicy 101

2.2.26. DetachRolePolicy 102

2.2.27. DetachUserPolicy 102

2.2.28. EnableMFADevice 103

2.2.29. GetGroup 103

2.2.30. GetGroupPolicy 104

2.2.31. GetPolicy 105

2.2.32. GetPolicyVersion 105

2.2.33. GetRole 106

2.2.34. GetRolePolicy 106

2.2.35. GetSAMLProvider 107

2.2.36. GetUser 107

2.2.37. GetUserPolicy 108

2.2.38. ListAccessKeys 108

2.2.39. ListAttachedGroupPolicies 109

2.2.40. ListAttachedRolePolicies 109

2.2.41. ListAttachedUserPolicies 110

2.2.42. ListEntitiesForPolicy 110

2.2.43. ListGroupPolicies 111

2.2.44. ListGroups 111

2.2.45. ListGroupsForUser 112

2.2.46. ListInstanceProfilesForRole 112

2.2.47. ListMFADevices 113

2.2.48. ListPolicies 113

2.2.49. ListPolicyVersions 114

2.2.50. ListRolePolicies 114

2.2.51. ListRoles 115

2.2.52. ListSAMLProviders 115

2.2.53. ListUserPolicies 115

2.2.54. ListUsers 116

 2.2.55. ListVirtualMFADevices 116

2.2.56. PutGroupPolicy 117

2.2.57. PutRolePolicy 118

2.2.58. PutUserPolicy 118

2.2.59. RemoveUserFromGroup 119

2.2.60. ResyncMFADevice 119

2.2.61. SetDefaultPolicyVersion 120

2.2.62. SimulatePrincipalPolicy 120

2.2.63. UpdateAccessKey 121

2.2.64. UpdateAssumeRolePolicy 122

2.2.65. UpdateGroup 122

2.2.66. UpdateRole 123

2.2.67. UpdateRoleDescription 123

2.2.68. UpdateSAMLProvider 123

2.2.69. UpdateUser 124

2.3. Supported IAM Policy Elements 124

2.4. SAML Support 125

2.4.1. Downloading the HyperStore SAML Metadata Document for IdP Setup 125

2.4.2. Using the IAM Service to Create SAML Provider Resources 126

2.4.3. Using the IAM Service to Create Roles 127

2.4.4. Using the STS Service to Assume a Role 127

Chapter 3. STS API 131

3.1. Introduction 131

3.1.1. HyperStore Support for the AWS STS API 131

3.1.2. STS Common Request Parameters 132

3.1.3. STS Common Errors 132

3.2. Supported STS Actions 132

3.2.1. AssumeRole 132

3.2.2. AssumeRoleWithSAML 133

3.2.3. GetCallerIdentity 134

Chapter 4. SQS API 135
4.1. Introduction 135

4.1.1. HyperStore Support for the AWS SQS API 135

4.2. SQS Supported Actions 136

4.2.1. ChangeMessageVisibility 137

4.2.2. CreateQueue 137

4.2.3. DeleteMessage 138

4.2.4. DeleteQueue 138

4.2.5. GetQueueAttributes 138

4.2.6. GetQueueUrl 139

4.2.7. ListQueues 139

4.2.8. PurgeQueue 140

4.2.9. ReceiveMessage 140

4.2.10. SendMessage 141

4.2.11. SetQueueAttributes 141

This page left intentionally blank.
Chapter 1. S3 API

1.1. Introduction

1.1.1. HyperStore Support for the AWS S3 API

Subjects covered in this section:

l Introduction (immediately below)

l "S3 API Notes for HyperStore Administrators" (page 13)

The Cloudian® HyperStore® system supports the great majority of the Amazon Web Services S3 REST API,
including advanced features.

This documentation provides the details of the HyperStore system’s compliance with the S3 REST API. The
organization of this documentation parallels that of the AWS S3 API Reference. Links are provided to specific
parts of the AWS S3 API Reference so you can easily view additional information about individual API oper-
ations.

This documentation takes the approach of specifying in detail the things that the HyperStore system does sup-
port from the AWS S3 REST API — from operations down to the level of particular request parameters, request
headers, request elements, response headers, and response elements. If it’s not listed in this HyperStore S3
API Support documentation, the HyperStore system does not currently support it.

This documentation also describes ways in which the HyperStore system extends the AWS S3 API, to support
additional functionality. Most of these extensions are in the form of additional request headers that add
enhanced functionality to standard AWS S3 operations on buckets. These extensions are described within the
sections that document HyperStore compliance with standard AWS S3 operations. The extensions are always
identified by a sub-heading that says HyperStore Extension to the S3 API. (For a summary of the extensions
see "HyperStore Extensions to the S3 API" (page 20).)

To access the S3 Service, HyperStore users need S3 access credentials. When users are created in Hyper-
Store, S3 access credentials are automatically created for the users.

If users are using a third party S3 client to access the HyperStore IAM Service, the users can obtain their S3
access credentials by logging in to the CMC and going to the Security Credentials page (via the drop-down
menu under the user login name). They can then supply those credentials to the third party S3 client applic-
ation.

If users are using the CMC's built-in S3 client, the CMC automatically uses the user's S3 credentials to access
the S3 service. Through the CMC's Bucket & Objects section, HyperStore users can create buckets, upload
and download objects, and so on.

1.1.1.1. S3 API Notes for HyperStore Administrators

l "S3 Service Configuration" (page 14)
l "S3 Service Endpoints" (page 14)
l "Using TLS/SSL" (page 14)
l "DNS" (page 14)

13
Chapter 1. S3 API

l "S3 Request Logging" (page 14)

l "Caution About Mass Deletes " (page 14)

S3 Service Configuration

The S3 Service is enabled by default system configuration. To view the current values of all S3 related con-
figuration settings in your system, on the Config Controller node run the command hsctl config get s3. For
descriptions of these settings, see the "HyperStore Configuration Settings" section of the Cloudian HyperStore
Administrator's Guide.

S3 Service Endpoints

To find the S3 service endpoint(s) for your system go to the CMC's Cluster Information page (Cluster ->
Cluster Config -> Cluster Information).

Using TLS/SSL

For information about setting up HTTPS for the S3 Service see the "HTTPS Feature Overview" section of the
Cloudian HyperStore Administrator's Guide. If HTTPS is enabled for your S3 Service it will listen for HTTPS
connections on port 443, as well as listening for regular HTTP connections on port 80.

DNS

Be sure to configure the S3 endpoint domains in your DNS environment. For more information see the "DNS
Set-Up" section of the Cloudian HyperStore Administrator's Guide.

S3 Request Logging

Information about requests processed by the S3 Service are logged to cloudian-request-info.log, which exists
on each node.For more information see the "Logging" section of the Cloudian HyperStore Administrator's
Guide.

Caution About Mass Deletes

S3 users should not attempt to delete more than 100,000 objects from a single bucket in less than an hour
using the S3 API, if the bucket was created in a HyperStore version older than 7.4. Doing so will result in Tomb-
stoneOverwhelmingException errors in the Cassandra logs and an inability to successfully execute an S3
ListObjectsVersion 1 or ListObjectsVersion 2 operation on the bucket. If the system is in this error condition,
you can trigger a tombstone purge as described in "Dealing with Excessive Tombstone Build-Up" in the "Sys-
tem cron jobs" section of the Cloudian HyperStore Administrator's Guide.

Buckets created in HyperStore 7.4 and later use a different metadata structure than older buckets. Starting in
HyperStore 7.4.2, all buckets created in HyperStore 7.4 and later use an improved tombstone monitoring and
cleanup mechanism that leverages the new metadata structure. Such buckets are able to support mass dele-
tions without negative service impact (they are not subject to the 100,000 deletes per hour limit that older buck-
ets are). If you have buckets that were created prior to HyperStore 7.4 and that need to be able to support mass
deletes, contact Cloudian Support for assistance in upgrading those buckets to the newer metadata structure
(known as "rules based partitioning").

1.1.2. S3 Client Application Options

Broadly you have three options for using HyperStore's implementation of the AWS S3 API to create storage
buckets in HyperStore, upload objects, retrieve objects, and so on:

14
 1.1. Introduction

l "Using the CMC as Your S3 Client" (page 15)

l "Using Third Party S3 Applications" (page 15)
l "Developing Custom S3 Applications for HyperStore" (page 15)

1.1.2.1. Using the CMC as Your S3 Client

The Cloudian Management Console's Buckets & Objects section serves as a graphical S3 client for inter-
acting with the HyperStore object store. With the CMC, users can create and configure buckets, and upload
and download objects.

1.1.2.2. Using Third Party S3 Applications

Because of HyperStore’s comprehensive compliance with the AWS S3 API, you can use most off-the-shelf third
party S3 client applications with HyperStore. For feedback on particular S3 applications that you are con-
sidering using with HyperStore, consult with Cloudian Sales Engineering or Cloudian Support.

To check to see what is your HyperStore S3 Service endpoint -- the URI to which you will submit S3 requests
with your third party application -- go to the CMC's Security Credentials page.

1.1.2.3. Developing Custom S3 Applications for HyperStore

In nearly every way, developing a client application for the Cloudian HyperStore storage service is the same as
developing a client application for AWS S3. Consequently, when building S3 applications for the HyperStore
service you can leverage the wealth of resources available to AWS S3 developers.

Good online resources for S3 application developers include:

l Amazon Simple Storage Service Developer Guide

l Amazon S3 resources

What’s Distinct About Developing for the HyperStore S3 Service

In practice, the main differences between developing for the HyperStore S3 service and developing for
Amazon S3 are:

l HyperStore S3 client applications must use the HyperStore S3 service endpoint rather than the Amazon
S3 service endpoint. To check to see what is your HyperStore S3 Service endpoint -- the URI to which
you will submit S3 requests with your custom application -- go to the CMC's Security Credentials page.
l As detailed in the "Supported S3 Operations" section of this documentation, the HyperStore S3 service
supports the great majority of but not the entire Amazon S3 API.
l Also as detailed in the "Supported S3 Operations" section of this documentation, the HyperStore S3 ser-
vice supports a small number of extensions to the Amazon S3 API. (For an overview of the extensions
see "HyperStore Extensions to the S3 API" (page 20)).

1.1.3. Authenticating Requests (AWS Signature Version 4)

HyperStore supports AWS Signature Version 4 for authenticating inbound API requests. The HyperStore imple-
mentation of this feature is compliant with Amazon’s specification of the feature. For example, you can express
authentication information in the HTTP Authorization header or in query string parameters; and you can com-
pute a checksum of the entire payload prior to transmission, or for large uploads, you can use chunked upload.

15
Chapter 1. S3 API

For more information on this Amazon S3 feature, refer to the "Authenticating Requests (AWS Signature Ver-
sion 4)" section of the Amazon S3 REST API.

HyperStore continues to support AWS Signature Version 2 as well.

Note The region name validation aspect of AWS Signature Version 4 is disabled by default in Hyper-
Store.

1.1.3.1. Trailing Headers

For AWS Signature Version 4's "trailing headers" functionality (for use with chunked uploads), HyperStore sup-
ports only:

l x-amz-content-sha256: STREAMING-UNSIGNED-PAYLOAD-TRAILER
l x-amz-trailer: x-amz-checksum-crc32c

1.1.4. Access Control List (ACL) Support

For the AWS S3 "Access Control List (ACL)" functionality, the HyperStore system supports the items listed
below. If a grantee group, permission type, or canned ACL type from the AWS S3 documentation is not listed
below, the HyperStore system does not support it.

For ACL usage information and for descriptions of ACL items, see Access Control List (ACL) Overview in the
AWS S3 documentation.

1.1.4.1. AWS S3 Predefined Groups

l Authenticated users group
l All users group
l Log delivery group

1.1.4.2. Permission Types

l READ
l WRITE
l READ_ACP
l WRITE_ACP
l FULL_CONTROL

1.1.4.3. Canned ACL

l private
l public-read
l public-read-write
l authenticated-read
l bucket-owner-read

16
 1.1. Introduction

l bucket-owner-full-control
l log-delivery-write

HyperStore Extension to the S3 API

The HyperStore system supports these additional canned ACLs:

Canned ACL Applies to Permissions added to ACL

group-read Bucket and object Owner gets FULL_CONTROL. All other members of the
owner’s HyperStore service user group get READ access.

group-read-write Bucket and object Owner gets FULL_CONTROL. All other members of the
owner’s HyperStore service user group get READ and WRITE
access.

Note To grant access to groups other than the requester’s own group, you cannot use canned ACLs.
Instead, when using standard Amazon S3 methods for assigning privileges to a grantee (via request
headers or request body), specify "<groupID>|" as the grantee. The "<groupID>|" format (with vertical
bar) indicates that the grantee is a group — for example, "Group5|".

Note When access privileges have through separate requests been granted to a group and to a spe-
cific member of the group, the user gets the broader of the privilege grants. For example, if Group5 is
granted read-write privileges and a specific user within Group5 is separately granted read privileges,
the user gets read-write privileges.

1.1.5. S3 Common Request and Response Headers

1.1.5.1. Common Request Headers

From the "Common Request Headers" section of the AWS S3 REST API specification, HyperStore supports
the headers listed below. If a header from that specification section is not listed below, HyperStore does not
support it.

l Authorization
l Content-Length
l Content-Type
l Content-MD5
l Date
l Expect
l Host

Note For path-style requests, the Host value is your system's S3 endpoint (excluding the pro-
tocol and port) -- for example s3-region1.enterprise.com. For virtual-hosted-style requests, the
Host value is BucketName.<S3 endpoint> -- for example bucket1.s3-region1.enterprise.com.

17
Chapter 1. S3 API

l x-amz-content-sha256
l x-amz-date

l x-amz-expected-bucket-owner

Note
* Unlike the AWS documentation which lists x-amz-expected-bucket-owner as a supported
request header for nearly every individual S3 API call but omits the header from the Common
header list, this HyperStore documentation instead lists the x-amz-expected-bucket-owner
header here among the Common headers. For the HyperStore S3 Service, the x-amz-expected-
bucket-owner request header is supported for all S3 API calls except CreateBucket and
ListBuckets.
* If you use the optional x-amz-expected-bucket-owner request header in making S3 calls to the
HyperStore S3 Service, identify the expected bucket owner by the bucket owner's canonical
user ID. A user's canonical user ID can be obtained by retrieving the user's profile in the CMC or
via the Admin API call GET /user.
* As with AWS, if the destination bucket in an API request is owned by an account other than the
expected bucket owner account, the request will fail with an HTTP 403 (Access Denied) error.

1.1.5.2. Common Response Headers

From the "Common Response Headers" section of the AWS S3 REST API specification, HyperStore sup-
ports the headers listed below. If a header from that specification section is not listed below, HyperStore does
not support it.

l Content-Length
l Content-Type
l Connection
l Date
l ETag
l Server
l x-amz-delete-marker
l x-amz-request-id
l x-amz-version-id

1.1.6. S3 Error Responses

From the "Error Responses" section of the AWS S3 API specification, HyperStore supports the error codes lis-
ted below, in the same format as indicated in the specification. If an error code from that specification section is
not listed below, HyperStore does not support it.

l AccessDenied
l AccountProblem
l AmbiguousGrantByEmailAddress
l BadDigest
l BucketAlreadyExists

18
 1.1. Introduction

l BucketAlreadyOwnedByYou
l BucketNotEmpty
l CrossLocationLoggingProhibited
l EntityTooLarge
l EntityTooSmall
l IllegalVersioningConfigurationException
l IncorrectNumberOfFilesInPostRequest
l InternalError
l InvalidAccessKeyId
l InvalidArgument
l InvalidBucketName
l InvalidBucketState
l InvalidDigest
l InvalidEncryptionAlgorithmError
l InvalidLocationConstraint
l InvalidObjectState
l InvalidPart
l InvalidPartOrder
l InvalidPolicyDocument
l InvalidRange
l InvalidRequest
l InvalidSecurity
l InvalidTargetBucketForLogging
l InvalidURI
l KeyTooLong
l MalformedACLError
l MalformedPOSTRequest
l MalformedXML
l MaxMessageLengthExceeded
l MaxPostPreDataLengthExceededError
l MetadataTooLarge
l MethodNotAllowed
l MissingContentLength
l MissingSecurityHeader
l NoSuchBucket
l NoSuchBucketPolicy
l NoSuchKey
l NoSuchLifecycleConfiguration
l NoSuchReplicationConfiguration

19
Chapter 1. S3 API

l NoSuchUpload
l NoSuchVersion
l NotImplemented
l PermanentRedirect
l PreconditionFailed
l Redirect
l RestoreAlreadyInProgress
l RequestIsNotMultiPartContent
l RequestTimeout
l RequestTimeTooSkewed
l SignatureDoesNotMatch
l ServiceUnavailable
l SlowDown
l TemporaryRedirect
l TooManyBuckets
l UnexpectedContent
l UnresolvableGrantByEmailAddress
l UserKeyMustBeSpecified

1.1.7. HyperStore Extensions to the S3 API

The HyperStore S3 Service supports the following extensions to the AWS S3 REST API. In each case the exten-
sions take the form of additional supported headers for standard AWS S3 API methods.

Extension Purpose Detail

x-gmt-policyid as optional request header Specify the Hyper-
for "CreateBucket" and response header Store storage
l "CreateBucket" (page 23)
for "ListObjects", "ListObjectsV2", and policy to use for a
"HeadBucket" new bucket
x-gmt-tieringinfo and x-gmt-compare and
x-gmt-post-tier-copy as optional request Set up auto-tier- l "PutBucketLifecycleConfiguration"
headers for "PutBucketLifecycle" and ing for a bucket (page 59)
response headers for "GetBucketLifecycle"
x-gmt-error-code and x-gmt-message as Provide additional
l "GetObject" (page 38)
supported response headers for "GetOb- information about
l "HeadObject" (page 43)
ject" and "HeadObject" HTTP 4xx errors
x-gmt-crr-endpoint and x-gmt-crr-cre-
dentials as optional request headers for Use for cross-sys- l "PutBucketReplication" (page 72)
"PutBucketReplication" and response tem replication l Cross-System Replication
headers for "GetBucketReplication".

20
 1.2. Supported S3 Operations

1.2. Supported S3 Operations

1.2.1. AbortMultipartUpload
This operation aborts a multipart upload.

Along with the common headers, HyperStore supports the operation-specific parameters listed below.

For operation details and examples see the AWS documentation: AbortMultipartUpload

Former operation name: Abort Multipart Upload

1.2.1.1. Query Parameters

l uploadId

1.2.2. CompleteMultipartUpload
Completes a multipart upload by assembling previously uploaded parts.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: CompleteMultipartUpload

Former operation name: Complete Multipart Upload

1.2.2.1. Request Headers

l x-amz-checksum-crc32
l x-amz-checksum-crc32c
l x-amz-checksum-sha1
l x-amz-checksum-sha256

1.2.2.2. Request Elements

l CompleteMultipartUpload
o Part
n ETag
n PartNumber

1.2.2.3. Response Headers

l x-amz-expiration
l x-amz-server-side-encryption
l x-amz-version-id

21
Chapter 1. S3 API

1.2.2.4. Response Elements

l Bucket
l CompleteMultipartUploadResult
l ETag
l Key
l Location

1.2.3. CopyObject
Creates a copy of an object that is already stored in HyperStore.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: CopyObject

Former operation name: PUT Object - Copy

1.2.3.1. Request Headers

l x-amz-acl

l x-amz-sdk-checksum-algorithm

l x-amz-copy-source
l x-amz-copy-source-if-match
l x-amz-copy-source-if-modified-since
l x-amz-copy-source-if-none-match
l x-amz-copy-source-if-unmodified-since
l x-amz-copy-source-server-side-encryption-customer-algorithm
l x-amz-copy-source-server-side-encryption-customer-key
l x-amz-copy-source-server-side-encryption-customer-key-MD5
l x-amz-grant-full-control
l x-amz-grant-read
l x-amz-grant-read-acp
l x-amz-grant-write
l x-amz-grant-write-acp
l x-amz-meta-*
l x-amz-metadata-directive
l x-amz-object-lock-legal-hold
l x-amz-object-lock-mode

l x-amz-object-lock-retain-until-date
l x-amz-server-side-encryption

22
 1.2. Supported S3 Operations

l x-amz-server-side-encryption-customer-algorithm
l x-amz-server-side-encryption-customer-key
l x-amz-server-side-encryption-customer-key-MD5
l x-amz-storage-class

Note HyperStore ignores the value of the x-amz-storage-class header and treats all requests as
being for storage class STANDARD.

l x-amz-source-expected-bucket-owner
l x-amz-tagging
l x-amz-tagging-directive
l x-amz-website-redirect-location

1.2.3.2. Response Headers

l x-amz-copy-source-version-id
l x-amz-expiration
l x-amz-server-side-encryption
l x-amz-version-id

1.2.3.3. Response Elements

l CopyObjectResult
o ETag
o LastModified

1.2.4. CreateBucket
Creates a new bucket.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: CreateBucket

Former operation name: PUT Bucket

Note
* By default each user is allowed a maximum of 100 buckets.
* HyperStore enforces the same bucket naming restrictions as does Amazon S3. Also, if you use an
underscore in a bucket name you will not be able to enable auto-tiering for the bucket (for trans-
itioning objects to Amazon or other remote destinations on a configurable schedule). It's best not to use
underscores when naming new buckets, in case you may want to enable auto-tiering on the bucket
immediately or in the future.

23
Chapter 1. S3 API

1.2.4.1. Request Headers

l x-amz-acl
l x-amz-grant-full-control
l x-amz-grant-read
l x-amz-grant-read-acp
l x-amz-grant-write
l x-amz-grant-write-acp
l x-amz-bucket-object-lock-enabled

l x-amz-object-ownership

HyperStore Extension to the S3 API

The HyperStore system supports the following Request Header as an extension to the "PUT Bucket" operation:

Name Description Required

x-gmt-policyid This header specifies the unique ID of the storage policy to assign to the No
newly created bucket. The storage policy determines how data in the
bucket will be distributed and protected through either replication or eras-
ure coding. System administrators can create multiple storage policies
through the CMC and the system automatically assigns each a unique
policy ID that becomes part of the policy definition.

With the "x-gmt-policyid" request header for "PUT Bucket", you specify the
ID of the desired storage policy when you create a new bucket. Note how-
ever that some policies may not be available to all user groups — a policy’s
availability is specified by system administrators at the time of policy cre-
ation, and this information becomes part of the policy definition. When you
specify an "x-gmt-policyid" value with a "PUT Bucket" request, the policy ID
must be for a policy that is available to the group to which the bucket owner
belongs.

Also the policy ID must be for a storage policy from the service region that is
specified in the "PUT Bucket" request’s LocationConstraint element.

If the "PUT Bucket" request does not include the "x-gmt-policyid" request
header, then the system will automatically assign the system default stor-
age policy to the bucket during bucket creation.

Note After a bucket is created, it cannot be assigned a different stor-

age policy. The storage policy assigned to the bucket at bucket cre-
ation time will continue to be bucket’s storage policy for the life of
the bucket.

Note A 403 error response is returned if you specify a policy ID that

does not exist, has been disabled, is not available to the region in
which the bucket is being created, or is not available to the group to
which the bucket owner belongs. A 403 is also returned if you do

24
 1.2. Supported S3 Operations

Name Description Required

not specify an "x-gmt-policyid" header and the system does not yet
have an established default storage policy.

Example header:

x-gmt-policyid: 1bc90238f9f11cb32f5e4e901675d50b

1.2.4.2. Request Elements

l CreateBucketConfiguration
o LocationConstraint

1.2.5. CreateMultipartUpload
This operation initiates a multipart upload and returns an upload ID.

Along with the common headers, HyperStore supports the operation-specific parameters and elements listed
below.

For operation details and examples see the AWS documentation: CreateMultipartUpload

Former operation name: Initiate Multipart Upload

1.2.5.1. Request Headers

l Cache-Control
l Content-Disposition
l Content-Encoding
l Content-Type
l Expires
l x-amz-acl

l x-amz-sdk-checksum-algorithm

Note Along with the information about this header in the AWS documentation for this S3 API
operation, overviews of the AWS S3 "Additional Checksum" feature are available in the AWS
documentation "Checking Object Integrity" and the AWS blog post "Additional Checksum
Algorithms for Amazon S3".

l x-amz-grant-full-control
l x-amz-grant-read
l x-amz-grant-read-acp
l x-amz-grant-write
l x-amz-grant-write-acp
l x-amz-meta-*

25
Chapter 1. S3 API

l x-amz-object-lock-legal-hold
l x-amz-object-lock-mode

l x-amz-object-lock-retain-until-date
l x-amz-server-side-encryption

l x-amz-server-side-encryption-customer-algorithm
l x-amz-server-side-encryption-customer-key
l x-amz-server-side-encryption-customer-key-MD5
l x-amz-storage-class

Note HyperStore ignores the value of the x-amz-storage-class header and treats all requests as
being for storage class STANDARD.

l x-amz-website-redirect-location

1.2.5.2. Response Headers

l x-amz-abort-date
l x-amz-abort​-rule-id
l x-amz-server-side-encryption
l x-amz-server-side-encryption-customer-algorithm
l x-amz-server-side-encryption-customer-key-MD5

1.2.5.3. Response Elements

l InitiateMultipartUploadResult
o Bucket
o Key
o UploadId

1.2.6. DeleteBucket
Deletes the bucket.

For this operation HyperStore supports the S3 common headers.

For operation details and examples see the AWS documentation: DeleteBucket

Former operation name: DELETE Bucket

1.2.7. DeleteBucketCors
Deletes the cors configuration information set for the bucket.

For this operation HyperStore supports the S3 common headers.

For operation details and examples see the AWS documentation: DeleteBucketCors

Former operation name: DELETE Bucket cors

26
 1.2. Supported S3 Operations

1.2.8. DeleteBucketEncryption
This implementation of the DELETE operation removes default encryption from the bucket.

For this operation HyperStore supports the S3 common headers.

For operation details and examples see the AWS documentation: DeleteBucketEncryption

Former operation name: DELETE Bucket encryption

1.2.9. DeleteBucketInventoryConfiguration
Deletes an inventory configuration (identified by the inventory ID) from the bucket.

Along with the common headers, HyperStore supports the operation-specific parameter listed below.

For operation details and examples see the AWS documentation: DeleteBucketInventoryConfiguration

1.2.9.1. Query Parameter

l id

1.2.10. DeleteBucketLifecycle
Deletes the lifecycle configuration from the specified bucket.

For this operation HyperStore supports the S3 common headers.

For operation details and examples see the AWS documentation: DeleteBucketLifecycle

Former operation name: DELETE Bucket lifecycle

1.2.11. DeleteBucketOwnershipControls
Removes OwnershipControls for a bucket.

For this operation HyperStore supports the S3 common headers.

For operation details and examples see the AWS documentation: DeleteBucketOwnershipControls

1.2.12. DeleteBucketPolicy
This implementation of the DELETE operation uses the policy subresource to delete the policy of a specified
bucket.

For this operation HyperStore supports the S3 common headers.

For operation details and examples see the AWS documentation: DeleteBucketPolicy

Former operation name: DELETE Bucket policy

1.2.13. DeleteBucketReplication
Deletes the replication configuration from the bucket.

For this operation HyperStore supports the S3 common headers.

27
Chapter 1. S3 API

For operation details and examples see the AWS documentation: DeleteBucketReplication

Former operation name: DELETE Bucket replication

1.2.14. DeleteBucketTagging
Deletes the tags from the bucket.

For this operation HyperStore supports the S3 common headers.

For operation details and examples see the AWS documentation: DeleteBucketTagging

Former operation name: DELETE Bucket tagging

1.2.15. DeleteBucketWebsite
This operation removes the website configuration for a bucket.

For this operation HyperStore supports the S3 common headers.

For operation details and examples see the AWS documentation: DeleteBucketWebsite

Former operation name: DELETE Bucket website

1.2.16. DeleteObject
Removes the null version (if there is one) of an object and inserts a delete marker, which becomes the latest
version of the object.

Along with the common headers, HyperStore supports the operation-specific headers listed below.

For operation details and examples see the AWS documentation: DeleteObject

Former operation name: DELETE Object

Note Successful completion of a DeleteObject request results in the system marking the object as hav-
ing been deleted. However the actual deletion of object data from disk will not occur until the next auto-
matic running of the object deletion batch processing job. By default this batch processing of object
data deletes runs hourly on each node.

IMPORTANT ! Do not attempt to delete more than 100,000 objects from a single bucket in less than an
hour, if the bucket was created in a HyperStore version older than 7.4.

Buckets created in HyperStore 7.4 and later use a different metadata structure than older buckets. Start-
ing in HyperStore 7.4.2, all buckets created in HyperStore 7.4 and later use an improved tombstone
monitoring and cleanup mechanism that leverages the new metadata structure. Such buckets are able
to support mass deletions without negative service impact (they are not subject to the 100,000 deletes
per hour limit that older buckets are). If you have buckets that were created prior to HyperStore 7.4 and
that need to be able to support mass deletes, contact Cloudian Support for assistance in upgrading
those buckets to the newer metadata structure (known as "rules based partitioning").

28
 1.2. Supported S3 Operations

1.2.16.1. Request Headers

l x-amz-bypass-governance-retention

1.2.16.2. Response Headers

l x-amz-delete-marker
l x-amz-version-id

1.2.17. DeleteObjects
This operation enables you to delete multiple objects from a bucket using a single HTTP request.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: DeleteObjects

Former operation name: Delete Multiple Objects

Note The HyperStore S3 Service allows a maximum of 1000 object deletes per DeleteObjects request.

Note Successful completion of a DeleteObjects request results in the system marking the objects as
having been deleted. However the actual deletion of object data from disk will not occur until the next
automatic running of the object deletion batch processing job. By default this batch processing of object
data deletes runs hourly on each node.

IMPORTANT ! Do not attempt to delete more than 100,000 objects from a single bucket in less than an
hour, if the bucket was created in a HyperStore version older than 7.4.

Buckets created in HyperStore 7.4 and later use a different metadata structure than older buckets. Start-
ing in HyperStore 7.4.2, all buckets created in HyperStore 7.4 and later use an improved tombstone
monitoring and cleanup mechanism that leverages the new metadata structure. Such buckets are able
to support mass deletions without negative service impact (they are not subject to the 100,000 deletes
per hour limit that older buckets are). If you have buckets that were created prior to HyperStore 7.4 and
that need to be able to support mass deletes, contact Cloudian Support for assistance in upgrading
those buckets to the newer metadata structure (known as "rules based partitioning").

1.2.17.1. Request Headers

l x-amz-bypass-governance-retention

29
Chapter 1. S3 API

1.2.17.2. Request Elements

l Delete
o Object
n Key
n VersionId
o Quiet

1.2.17.3. Response Elements

l DeleteResult
o Deleted
n DeleteMarker
n DeleteMarkerVersionId
n Key
n VersionId
o Error
n Code
n Key
n Message
n VersionId

1.2.18. DeleteObjectTagging
Removes the entire tag set from the specified object.

For this operation HyperStore supports the S3 common headers.

For operation details and examples see the AWS documentation: DeleteObjectTagging

Former operation name: DELETE Object tagging

1.2.19. DeletePublicAccessBlock
Removes the PublicAccessBlock configuration for a bucket.

For this operation HyperStore supports the S3 common headers.

For operation details and examples see the AWS documentation: DeletePublicAccessBlock

1.2.20. GetBucketAcl
This implementation of the GET operation uses the acl subresource to return the access control list (ACL) of a
bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketAcl

Former operation name: GET Bucket acl

30
 1.2. Supported S3 Operations

1.2.20.1. Response Elements

l AccessControlPolicy
o Owner
n DisplayName
n ID
o AccessControlList
n Grant
o Grantee
n DisplayName
n ID
n Permission

1.2.21. GetBucketCors
Returns the cors configuration information set for the bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketCors

Former operation name: GET Bucket cors

1.2.21.1. Response Elements

l CORSConfiguration
o CORSRule
n AllowedHeader
n AllowedMethod
n AllowedOrigin
n ExposeHeader
n ID
n MaxAgeSeconds

1.2.22. GetBucketEncryption
Returns the default encryption configuration for the bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketEncryption

Former operation name: GET Bucket encryption

31
Chapter 1. S3 API

1.2.22.1. Response Elements

l ServerSideEncryptionConfiguration
o Rule
n ApplyServerSideEncryptionByDefault
o SSEAlgorithm

1.2.23. GetBucketInventoryConfiguration
Returns an inventory configuration (identified by the inventory configuration ID) from the bucket.

Along with the common headers, HyperStore supports the operation-specific parameter and elements listed
below.

For operation details and examples see the AWS documentation: GetBucketInventoryConfiguration

1.2.23.1. Query Parameter

l id

1.2.23.2. Response Elements

l InventoryConfiguration
o Destination
n S3BucketDestination
o AccountId
o Bucket
o Encryption
n SSE-KMS
o KeyId
n SSE-S3
o Format
o Prefix
o Filter
n Prefix
o Id
o IncludedObjectVersions
o IsEnabled
o OptionalFields
n Field
o Schedule
n Frequency

32
 1.2. Supported S3 Operations

1.2.24. GetBucketLifecycle
Returns the lifecycle configuration information set on the bucket.

For operation details and examples see the AWS documentation: GetBucketLifecycle

Note Though HyperStore supports this API operation for backward compatibility, AWS has deprecated
this operation in favor of a newer version called GetBucketLifecycleConfiguration which HyperStore
also supports. If you used PutBucketLifecycleConfiguration to create a lifecycle use GetBuck-
etLifecycleConfiguration to retrieve the configuration.

1.2.25. GetBucketLifecycleConfiguration
Returns the lifecycle configuration information set on the bucket.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: GetBucketLifecycleConfiguration

Former operation name: GET Bucket lifecycle

1.2.25.1. Response Headers

HyperStore Extension to the S3 API

The HyperStore system supports the following Response Headers as extensions to the "GetBuck-
etLifecycleConfiguration" operation:

Name Description Required

x-gmt-tieringinfo

x-gmt-compare See "PutBucketLifecycleConfiguration" (page 59). No

x-gmt-post-tier-copy

1.2.25.2. Response Elements

l LifecycleConfiguration
o Rule
n AbortIncompleteMultipartUpload
l DaysAfterInitiation
n Expiration
l Date
l Days
l ExpiredObjectDeleteMarker

33
Chapter 1. S3 API

n Filter
l And
o ObjectSizeGreaterThan
o ObjectSizeLessThan
o Prefix
o Tag
n Key
n Value
l Prefix
l Tag
o Key
o Value
n ID
n NoncurrentVersionExpiration
l NoncurrentDays
n NoncurrentVersionTransition
l NoncurrentDays
l StorageClass
n Prefix
n Status
n Transition
l Date
l Days
l StorageClass

1.2.26. GetBucketLocation
Returns the Region the bucket resides in.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketLocation

Former operation name: GET Bucket location

1.2.26.1. Response Elements

l LocationConstraint

1.2.26.2. GetBucketLocation Response for Buckets in the Default Service Region

The GetBucketLocation operation behaves as follows:

l If the bucket specified in the GetBucketLocation request resides in a non-default service region, the
response indicates the name of the service region.

34
 1.2. Supported S3 Operations

l If the bucket specified in the GetBucketLocation request resides in the default service region, the
response returns a null/empty value.

HyperStore's behavior of returning a null/empty value if the bucket is in the default region is the same as
Amazon Web Services' implementation of the GetBucketLocation operation. Some S3 client applications --
such as Veeam -- are unable to handle the return of a null/empty region value, and may display an error if the
actual default region name is set within the client application. The work-around is to not set the region in the cli-
ent application, or else set it to the AWS default region name: us-east-1.

1.2.27. GetBucketLogging
Returns the logging status of a bucket and the permissions users have to view and modify that status.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketLogging

Former operation name: GET Bucket logging

1.2.27.1. Response Elements

l BucketLoggingStatus
o LoggingEnabled
n TargetBucket
n TargetGrants
o Grant
n Grantee
n Permission
n TargetPrefix

1.2.28. GetBucketNotificationConfiguration
Returns the notification configuration of a bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketNotificationConfiguration

1.2.28.1. Response Elements

l NotificationConfiguration
o QueueConfiguration
o Event
o Filter
n S3Key
o FilterRule
n Name
n Value

35
Chapter 1. S3 API

o Id
o Queue

For Event types, HyperStore supports only the following:

l s3:ObjectCreated:*
l s3:ObjectCreated:Put
l s3:ObjectCreated:Post
l s3:ObjectCreated:Copy
l s3:ObjectCreated:CompleteMultipartUpload
l s3:ObjectRemoved:*
l s3:ObjectRemoved:Delete
l s3:ObjectRemoved:DeleteMarkerCreated

1.2.29. GetBucketOwnershipControls
Retrieves OwnershipControls for a bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketOwnershipControls

1.2.29.1. Response Elements

l OwnershipControls
o Rule
n ObjectOwnership

1.2.30. GetBucketPolicy
Returns the policy of a specified bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketPolicy

Former operation name: GET Bucket policy

1.2.30.1. Response Elements

The response contains the (JSON) policy of the specified bucket.

1.2.31. GetBucketPolicyStatus
Retrieves the policy status for a bucket, indicating whether the bucket is public.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketPolicyStatus

36
 1.2. Supported S3 Operations

1.2.31.1. Response Elements

l PolicyStatus
o IsPublic

Note HyperStore considers a bucket policy to be "public" if any statement in the policy is public. A state-
ment is considered public if the Effect is Allow and the Principal has a wildcard -- unless there is an
IpAddress:{aws:SourceIp condition associated with the statement that restricts the requesting source IP
to one or more specified IP addresses.

1.2.32. GetBucketReplication
Returns the replication configuration of a bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketReplication

Former operation name: GET Bucket replication

1.2.32.1. Response Elements

l ReplicationConfiguration
o Role
o Rule

1.2.33. GetBucketTagging
Returns the tag set associated with the bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketTagging

Former operation name: GET Bucket tagging

1.2.33.1. Response Elements

l Tagging
o TagSet
n Tag
o Key
o Value

1.2.34. GetBucketVersioning
Returns the versioning state of a bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketVersioning

37
Chapter 1. S3 API

Former operation name: GET Bucket versioning

1.2.34.1. Response Elements

l VersioningConfiguration
o Status

1.2.35. GetBucketWebsite
Returns the website configuration for a bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetBucketWebsite

Former operation name: GET Bucket website

1.2.35.1. Response Elements

l WebsiteConfiguration
l o ErrorDocument
n Key
o IndexDocument
n Suffix
o RedirectAllRequestsTo
n HostName
n Protocol

1.2.36. GetObject
Retrieves objects from the S3 storage system.

Along with the common headers, HyperStore supports the operation-specific parameters, headers, and ele-
ments listed below.

For operation details and examples see the AWS documentation: GetObject

Former operation name: GET Object

1.2.36.1. Query Parameters

l partNumber

Note Using the partNumber parameter may not work as expected if the object has been auto-
tiered, or if the object has been auto-tiered and restored. This is because an object's number of
parts when uploaded to HyperStore may be different than its number of parts when it is auto-
tiered to a remote destination system.

38
 1.2. Supported S3 Operations

l response-cache-control
l response-content-disposition
l response-content-encoding
l response-content-language
l response-content-type
l response-expires
l versionId

1.2.36.2. Request Headers

l If-Match
l If-Modified-Since
l If-None-Match
l If-Unmodified-Since
l Range
l x-amz-checksum-mode
l x-amz-server-side-encryption-customer-algorithm

l x-amz-server-side-encryption-customer-key
l x-amz-server-side-encryption-customer-key-MD5

1.2.36.3. Response Headers

l Last-Modified
l x-amz-delete-marker
l x-amz-expiration
l x-amz-meta-*
l x-amz-object-lock-legal-hold
l x-amz-object-lock-mode
l x-amz-object-lock-retain-until-date
l x-amz-replication-status
l x-amz-restore
l x-amz-server-side-encryption

Note For objects encrypted with the KMIP type of server-side encryption a "-KMIP" suffix will be
appended to the x-amz-server-side-encryption response header value.

l x-amz-server-side-encryption-customer-algorithm
l x-amz-server-side-encryption-customer-key-MD5
l x-amz-tagging-count
l x-amz-version-id
l x-amz-website-redirect-location

39
Chapter 1. S3 API

HyperStore Extension to the S3 API

The HyperStore system supports the following Response Headers as extensions to the "GET Object" oper-
ation. These headers are returned only in the event of an HTTP 4xx response. They are not returned with
HTTP 2xx, 3xx, or 5xx responses.

Name Description
x-gmt-error-code In the event of an HTTP 4xx response, these two response headers provide
additional information about the nature of the error. The x-gmt-error-code
x-gmt-message header values will be from among the list in "S3 Error Responses" (page
18).

1.2.37. GetObjectAcl
Returns the access control list (ACL) of an object.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: GetObjectAcl

Former operation name: GET Object acl

1.2.37.1. Response Elements

l AccessControlPolicy
o Owner
n DisplayName
n ID
o AccessControlList
n Grant
o Grantee
n DisplayName
n ID
o Permission

1.2.38. GetObjectLegalHold
Gets an object's current Legal Hold status.

Along with the common headers, HyperStore supports the operation-specific parameters and elements listed
below.

For operation details and examples see the AWS documentation: GetObjectLegalHold

Former operation name: GET Object legal hold

1.2.38.1. Query Parameters

l versionId

40
 1.2. Supported S3 Operations

1.2.38.2. Response Elements

l LegalHold
o Status

1.2.39. GetObjectLockConfiguration
Gets the Object Lock configuration for a bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetObjectLockConfiguration

Former operation name: GET Bucket object lock configuration

1.2.39.1. Response Elements

l ObjectLockConfiguration
o ObjectLockEnabled
o Rule
n DefaultRetention
o Days
o Mode
o Years

1.2.40. GetObjectRetention
Retrieves an object's retention settings.

Along with the common headers, HyperStore supports the operation-specific parameters and elements listed
below.

For operation details and examples see the AWS documentation: GetObjectRetention

Former operation name: GET Object retention

1.2.40.1. Query Parameters

l versionId

1.2.40.2. Response Elements

l Retention
o Mode
o RetainUntilDate

1.2.41. GetObjectTagging
Returns the tag-set of an object.

41
Chapter 1. S3 API

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetObjectTagging

Former operation name: GET Object tagging

1.2.41.1. Response Elements

l Tagging
o TagSet
n Tag
o Key
o Value

1.2.42. GetObjectTorrent
Return torrent files from a bucket.

For operation details and examples see the AWS documentation: GetObjectTorrent

Former operation name: GET Object torrent

1.2.42.1. Implementation Notes

l This operation is not supported by HyperStore by default, and can only be enabled with assistance from
Cloudian Support.
l HyperStore implements BitTorrent HTTP seeding for in accordance with the BEP19 specification
(http://www.bittorrent.org/beps/bep_0019.html). Therefore torrent files returned by HyperStore in
response to GetObjectTorrent requests will include a "url-list" key and the value of that key will be the
URL of the object in HyperStore.
l HyperStore objects that have been auto-tiered to a destination S3 system cannot be retrieved via BitTor-
rent, unless the objects are first restored to local HyperStore storage (via the S3 "RestoreObject"
(page 80) method). Restored objects can be retrieved from HyperStore via BitTorrent.
l Like with Amazon S3, with HyperStore only publicly readable objects are eligible for BitTorrent retrieval.
And like with Amazon S3, the following types of objects are not retrievable via BitTorrent:
o Objects larger than 5GB
o Non-current versions of versioned objects
o Objects encrypted via SSE-C (SSE with Customer-managed key; by contrast, BitTorrent retrieval
is supported for objects encrypted with regular SSE)

1.2.43. GetPublicAccessBlock
Retrieves the PublicAccessBlock configuration for a bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: GetPublicAccessBlock

42
 1.2. Supported S3 Operations

1.2.43.1. Response Elements

l PublicAccessBlockConfiguration
o BlockPublicAcls
o IgnorePublicAcls
o BlockPublicPolicy
o RestrictPublicBuckets

1.2.44. HeadBucket
This operation is useful to determine if a bucket exists and you have permission to access it.

Along with the common headers, HyperStore supports the operation-specific headers listed below.

For operation details and examples see the AWS documentation: HeadBucket

Former operation name: HEAD Bucket

1.2.44.1. Response Headers

l x-amz-bucket-region

HyperStore Extension to the S3 API

The HyperStore system supports the following Response Header as an extension to the "HeadBucket" oper-
ation:

Parameter Description
This header specifies the unique ID of the storage policy assigned to the
x-gmt-policyid
bucket. For more information see "CreateBucket" (page 23).

1.2.45. HeadObject
The HEAD operation retrieves metadata from an object without returning the object itself.

Along with the common headers, HyperStore supports the operation-specific parameters and headers listed
below.

For operation details and examples see the AWS documentation: HeadObject

Former operation name: HEAD Object

1.2.45.1. Query Parameters

l partNumber

Note Using the partNumber parameter may not work as expected if the object has been auto-
tiered, or if the object has been auto-tiered and restored. This is because an object's number of

43
Chapter 1. S3 API

parts when uploaded to HyperStore may be different than its number of parts when it is auto-
tiered to a remote destination system.

l versionId

1.2.45.2. Request Headers

l If-Match
l If-Modified-Since
l If-None-Match
l If-Unmodified-Since
l Range
l x-amz-checksum-mode
l x-amz-server-side-encryption-customer-algorithm
l x-amz-server-side-encryption-customer-key
l x-amz-server-side-encryption-customer-key-MD5

1.2.45.3. Response Headers

l Last-Modified
l x-amz-expiration
l x-amz-meta-*
l x-amz-object-lock-legal-hold
l x-amz-object-lock-mode
l x-amz-object-lock-retain-until-date
l x-amz-replication-status
l x-amz-restore
l x-amz-server-side-encryption

Note For objects encrypted with the KMIP type of server-side encryption a "-KMIP" suffix will be
appended to the x-amz-server-side-encryption response header value.

l x-amz-server-side-encryption-customer-algorithm
l x-amz-server-side-encryption-customer-key-MD5
l x-amz-tagging-count
l x-amz-version-id

HyperStore Extension to the S3 API

The HyperStore system supports the following Response Headers as extensions to the "HeadObject" oper-
ation. These headers are returned only in the event of an HTTP 4xx response. They are not returned with
HTTP 2xx, 3xx, or 5xx responses.

44
 1.2. Supported S3 Operations

Name Description
x-gmt-error-code In the event of an HTTP 4xx response, these two response headers provide
additional information about the nature of the error. The x-gmt-error-code
x-gmt-message header values will be from among the list in "S3 Error Responses" (page
18).

1.2.46. ListBucketInventoryConfigurations
Returns a list of inventory configurations for the bucket.

Along with the common headers, HyperStore supports the operation-specific parameter and elements listed
below.

For operation details and examples see the AWS documentation: ListBucketInventoryConfigurations

1.2.46.1. Query Parameter

l continuation-token

1.2.46.2. Response Elements

l ListInventoryConfigurationsResult
l ContinuationToken
l InventoryConfiguration
o Destination
n S3BucketDestination
o AccountId
o Bucket
o Encryption
n SSE-KMS
o KeyId
n SSE-S3
o Format
o Prefix
o Filter
n Prefix
o Id
o IncludedObjectVersions
o IsEnabled
o OptionalFields
n Field
o Schedule
n Frequency

45
Chapter 1. S3 API

l IsTruncated
l NextContinuationToken

1.2.47. ListBuckets
Returns a list of all buckets owned by the authenticated sender of the request.

Along with the common headers, HyperStore supports the operation-specific parameter listed below.

For operation details and examples see the AWS documentation: ListBuckets

Former operation name: GET Service

HyperStore Extension to the S3 API

The HyperStore system supports the following Query Parameter as an extension to the "ListBuckets" operation:

Note This extension is supported only if it has been enabled by system administrators (using the con-
figuration setting s3.enable.sharedBucket).

Name Description Required

shared If the shared parameter is included in the request, the ListBuckets operation No
returns a list of buckets that other users have shared with the requesting
user. This will be buckets that have been shared specifically with the
requesting user, plus buckets that have been shared with the group to
which the requesting user belongs, plus buckets that have been shared
with everyone.

Example:

GET /?shared HTTP/1.1.

Host: s3-region1.enterprise4.mobi-cloud.com.
Accept-Encoding: identity.
Date: Fri, 05 Apr 2019 15:34:01 GMT.
Content-Length: 0.
Authorization: AWS akey2:jTcwd1Ta+5sZftVHGtEEyweojdk=.
User-Agent: Boto/2.42.0 Python/2.7.5 Linux/3.10.0-693.el7.x86_64.

HTTP/1.1 200 OK.

Date: Fri, 05 Apr 2019 15:34:01 GMT.
x-amz-request-id: 1721b414-267b-1341-93e6-d4ae52ce5402.
Content-Type: application/xml;charset=UTF-8.
Content-Length: 432.
Server: CloudianS3.

<?xml version="1.0" encoding="UTF-8"?><ListAllMyBucketsResult

xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Owner><ID>8ce1c49e532edc91b0a43e0c7e7d5975</ID>
<DisplayName>robot1</DisplayName></Owner>
<Buckets><Bucket><Name>sharedbucket1</Name>
<CreationDate>2019-04-05T15:30:03.897Z</CreationDate></Bucket>
<Bucket><Name>sharedbucket2</Name>
<CreationDate>2019-04-05T15:27:26.300Z</CreationDate>

46
 1.2. Supported S3 Operations

Name Description Required

</Bucket></Buckets></ListAllMyBucketsResult>

Note When the 'shared' parameter is used, the ListBuckets call

returns only buckets that have been shared with the requesting user
-- not buckets owned by the requesting user. So to retrieve all
buckets that a user has access to, an S3 client application must sub-
mit two ListBuckets calls -- one without the 'shared' parameter (to
retrieve the user's own buckets) and one with the 'shared' para-
meter (to retrieve buckets that have been shared with the user).

Note When the 'shared' parameter is used, in the ListBuckets

response body the "Owner" is the requesting user, not the actual
owner(s) of the shared bucket(s).

1.2.48. ListMultipartUploads
This operation lists in-progress multipart uploads.

Along with the common headers, HyperStore supports the operation-specific parameters and elements listed
below.

For operation details and examples see the AWS documentation: ListMultipartUploads

Former operation name: List Multipart Uploads

1.2.48.1. Query Parameters

l delimiter
l encoding-type
l key-marker
l max-uploads
l prefix
l upload-id-marker

1.2.48.2. Response Elements

l ListMultipartUploadsResult
o Bucket
o KeyMarker
o UploadIdMarker
o NextKeyMarker
o Prefix
o Delimiter
o NextUploadIdMarker

47
Chapter 1. S3 API

o MaxUploads
o IsTruncated
o Upload
n ChecksumAlgorithm
n Initiated
n Initiator
o DisplayName
o ID
n Key
n Owner
o DisplayName
o ID
n StorageClass
n UploadId
o CommonPrefixes
n Prefix
o EncodingType

1.2.49. ListObjects
Returns some or all of the objects in a bucket.

Along with the common headers, HyperStore supports the operation-specific parameters, headers, and ele-
ments listed below.

For operation details and examples see the AWS documentation: ListObjects

Former operation name: GET Bucket (List Objects) Version 1

Note HyperStore also supports the newer version of this API operation, ListObjectsV2.

Note When using ListObjects, use the marker request parameter to improve performance in listing the
content of buckets that contain many objects. For detail see the AWS documentation for this API oper-
ation.

1.2.49.1. Query Parameters

l delimiter

Note The HyperStore system does not support %c2%85(U+0085) as a delimiter value

l encoding-type
l marker

48
 1.2. Supported S3 Operations

l max-keys
l prefix

Note The HyperStore S3 extension request parameter meta=true is no longer supported.

1.2.49.2. Response Headers

HyperStore Extension to the S3 API

The HyperStore system supports the following Response Header as an extension to the "ListObjects" oper-
ation:

Name Description Required

This header specifies the unique ID of the storage policy assigned to
x-gmt-policyid No
the bucket. For more information see "CreateBucket" (page 23).

1.2.49.3. Response Elements

l ListBucketResult
o IsTruncated
o Marker
o NextMarker
o Contents
n ChecksumAlgorithm
n ETag
n Key
n LastModified
n Owner
o DisplayName
o ID
n Size
n StorageClass (values STANDARD and GLACIER only)
o Name
o Prefix
o Delimiter
o MaxKeys
o CommonPrefixes
n Prefix
o Encoding-Type

1.2.50. ListObjectsV2
Returns some or all of the objects in a bucket.

49
Chapter 1. S3 API

Along with the common headers, HyperStore supports the operation-specific parameters, headers, and ele-
ments listed below.

For operation details and examples see the AWS documentation: ListObjectsV2

Former operation name: GET Bucket (List Objects) Version 2

Note For backward-compatibility HyperStore continues to also support the older version of this API
operation, ListObjects.

Note When using ListObjectsV2, use the continuation-token request parameter to improve per-
formance in listing the content of buckets that contain many objects. For detail see the Amazon doc-
umentation for ListObjectsV2.

1.2.50.1. Query Parameters

l continuation-token
l delimiter

Note The HyperStore system does not support %c2%85(U+0085) as a delimiter value

l encoding-type
l fetch-owner
l list-type
l max-keys
l prefix
l start-after

Note The HyperStore S3 extension request parameter meta=true is no longer supported.

1.2.50.2. Response Headers

HyperStore Extension to the S3 API

The HyperStore system supports the following Response Header as an extension to the "ListObjectsV2" oper-
ation:

Name Description Required

This header specifies the unique ID of the storage policy assigned to
x-gmt-policyid No
the bucket. For more information see "CreateBucket" (page 23).

50
 1.2. Supported S3 Operations

1.2.50.3. Response Elements

l ListBucketResult
o IsTruncated
o Contents
n ChecksumAlgorithm
n ETag
n Key
n LastModified
n Owner
o DisplayName
o ID
n Size
n StorageClass (values STANDARD and GLACIER only)
o Name
o Prefix
o Delimiter
o MaxKeys
o CommonPrefixes
n Prefix
o Encoding-Type
o KeyCount
o ContinuationToken
o NextContinuationToken
o StartAfter

1.2.51. ListObjectVersions
Returns metadata about all of the versions of objects in a bucket.

Along with the common headers, HyperStore supports the operation-specific parameters and elements listed
below.

For operation details and examples see the AWS documentation: ListObjectVersions

Former operation name: GET Bucket Object versions

1.2.51.1. Query Parameters

l delimiter
l encoding-type
l key-marker
l max-keys

51
Chapter 1. S3 API

l prefix
l version-id-marker

1.2.51.2. Response Elements

l ListVersionsResult
o IsTruncated
o KeyMarker
o VersionIdMarker
o NextKeyMarker
o NextVersionIdMarker
o Version
n ChecksumAlgorithm
n ETag
n IsLatest
n Key
n LastModified
n Owner
o DisplayName
o ID
n Size
n StorageClass
n VersionId
o DeleteMarker
n IsLatest
n Key
n LastModified
n Owner
o DisplayName
o ID
n VersionId
o Name
o Prefix
o Delimiter
o MaxKeys
o Encoding-Type

1.2.52. ListParts
Lists the parts that have been uploaded for a specific multipart upload.

52
 1.2. Supported S3 Operations

Along with the common headers, HyperStore supports the operation-specific parameters and elements listed
below.

For operation details and examples see the AWS documentation: ListParts

Former operation name: List Parts

1.2.52.1. Query Parameters

l key
l max-parts
l part-number-marker
l uploadId

1.2.52.2. Response Headers

l x-amz-abort-date
l x-amz-abort-rule-id

1.2.52.3. Response Elements

l ListPartsResult
o Bucket
o Key
o UploadId
o PartNumberMarker
o NextPartNumberMarker
o MaxParts
o IsTruncated
o Part
n ChecksumCRC32
n ChecksumCRC32C
n ChecksumSHA1
n ChecksumSHA256
n ETag
n LastModified
n PartNumber
n Size
o Initiator
n DisplayName
n ID

53
Chapter 1. S3 API

o Owner
n DisplayName
n ID
o StorageClass
o ChecksumAlgorithm

1.2.53. OPTIONS Object

A browser can send this preflight request to HyperStore to determine if it can send an actual request with the
specific origin, HTTP method, and headers.

Along with the common headers, HyperStore supports the operation-specific parameters and elements listed
below.

For operation details and examples see the AWS documentation: OPTIONS Object

Former operation name: OPTIONS Object (no change)

1.2.53.1. Request Headers

l Access-Control-Request-Headers
l Access-Control-Request-Method
l Origin

1.2.53.2. Response Headers

l Access-Control-Allow-Headers
l Access-Control-Allow-Methods
l Access-Control-Allow-Origin
l Access-Control-Expose-Headers
l Access-Control-Max-Age

1.2.54. POST Object

The POST operation adds an object to a specified bucket using HTML forms.

Along with the common headers, HyperStore supports the operation-specific form fields listed below.

For operation details and examples see the AWS documentation: POST Object

Former operation name: POST Object (no change)

1.2.54.1. Form Fields

l AWSAccessKeyId
l acl
l Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires
l file
l key

54
 1.2. Supported S3 Operations

l policy
l success_action_redirect, redirect
l success_action_status
l tagging

l x-amz-sdk-checksum-algorithm

Note Along with the information about this header (and the x-amz-checksum-<algrorithm> head-
ers below) in the AWS documentation for this S3 API operation, overviews of the AWS S3 "Addi-
tional Checksum" feature are available in the AWS documentation "Checking Object Integrity"
and the AWS blog post "Additional Checksum Algorithms for Amazon S3". Note that if the
algorithm specified by x-amz-sdk-checksum-algorithm: <algorithm> is different than the
algorithm specified in the x-amz-checksum-<algorithm>: <checksum-value> header (one of the
four headers listed below), HyperStore rejects the request with an HTTP 400 error.

l x-amz-checksum-crc32
l x-amz-checksum-crc32c
l x-amz-checksum-sha1
l x-amz-checksum-sha256

l x-amz-storage-class

Note HyperStore ignores the value of the x-amz-storage-class field and treats all requests as
being for storage class STANDARD.

l x-amz-meta-*

l x-amz-website-redirect-location
l x-amz-object-lock-mode

l x-amz-object-lock-retain-until-date
l x-amz-object-lock-legal-hold
l x-amz-server-side-encryption

l x-amz-server-side-encryption-customer-algorithm
l x-amz-server-side-encryption-customer-key
l x-amz-server-side-encryption-customer-key-MD5

1.2.54.2. Response Headers

l success_action_redirect, redirect
l x-amz-expiration
l x-amz-server-side-encryption
l x-amz-server-side-encryption-customer-algorithm
l x-amz-server-side-encryption-customer-key-MD5
l x-amz-version-id

55
Chapter 1. S3 API

1.2.54.3. Response Elements

l Bucket
l ETag
l Key
l Location

1.2.55. PutBucketAcl
Sets the permissions on an existing bucket using access control lists (ACL).

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: PutBucketAcl

Former operation name: PUT Bucket acl

1.2.55.1. Request Headers

l x-amz-acl
l x-amz-grant-full-control
l x-amz-grant-read
l x-amz-grant-read-acp
l x-amz-grant-write
l x-amz-grant-write-acp

1.2.55.2. Request Elements

l AccessControlPolicy
o AccessControlList
n Grant
l Grantee
o DisplayName
o ID
n Permission
o Owner
l DisplayName
l ID

1.2.56. PutBucketCors
Sets the cors configuration for your bucket.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

56
 1.2. Supported S3 Operations

For operation details and examples see the AWS documentation: PutBucketCors

Former operation name: PUT Bucket cors

1.2.56.1. Request Headers

l Content-MD5

1.2.56.2. Request Elements

l CORSConfiguration
o CORSRule
n AllowedHeader
n AllowedMethod
n AllowedOrigin
n ExposeHeader
n ID
n MaxAgeSeconds

1.2.57. PutBucketEncryption
This implementation of the PUT operation uses the encryption subresource to set the default encryption state of
an existing bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: PutBucketEncryption

Former operation name: PUT Bucket encryption

Note In the current HyperStore release, only the bucket owner is allowed to perform operations
relating to bucket encryption. HyperStore does not currently support the use of bucket policies to
extend bucket encryption permissions to users other than the bucket owner. Specifically, with regard to
"PutBucketPolicy" (page 67), HyperStore does not currently support the "s3:PutEn-
cryptionConfiguration" or "s3:GetEncryptionConfiguration" actions.

1.2.57.1. Request Elements

l ServerSideEncryptionConfiguration
o Rule
n ApplyServerSideEncryptionByDefault
l KMSMasterKeyID
l SSEAlgorithm

57
Chapter 1. S3 API

1.2.58. PutBucketInventoryConfiguration
This implementation of the PUT action adds an inventory configuration (identified by the inventory ID) to the
bucket.

Along with the common headers, HyperStore supports the operation-specific parameter and elements listed
below.

For operation details and examples see the AWS documentation: PutBucketInventoryConfiguration

Note Unlike AWS, HyperStore does not use a system account to write inventory reports to the des-
tination bucket. Instead, reports are written by source bucket owner's account. In the current version of
HyperStore, the report destination bucket must be a bucket that is owned by the source bucket
owner.

1.2.58.1. Query Parameter

l id

1.2.58.2. Request Elements

l InventoryConfiguration
o Destination
n S3BucketDestination
o AccountId
o Bucket
o Encryption

Note HyperStore currently does not support encryption of bucket invent-

ory reports. If you include the optional "Encryption" element in the request
body HyperStore will ignore it.

o Format

Note HyperStore currently only supports CSV format.

o Prefix
o Filter
n Prefix
o Id
o IncludedObjectVersions
o IsEnabled
o OptionalFields
n Field

58
 1.2. Supported S3 Operations

o Schedule
n Frequency

1.2.59. PutBucketLifecycle
Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration.

For operation details and examples see the AWS documentation: PutBucketLifecycle

Note Though HyperStore supports this API operation for backward compatibility, AWS has deprecated
this operation in favor of a newer version called PutBucketLifecycleConfiguration which HyperStore
also supports. For new lifecycle configurations use the new version.

1.2.60. PutBucketLifecycleConfiguration
Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: PutBucketLifecycleConfiguration

Former operation name: PUT Bucket lifecycle

Note With the HyperStore system, only the bucket owner can create bucket lifecycle rules.

1.2.60.1. Request Headers

HyperStore Extension to the S3 API

The HyperStore system supports the following Request Headers as extensions to the "PutBuck-
etLifecycleConfiguration" operation:

Note Do not set an auto-tiering lifecycle rule and a cross-region replication configuration on the
same source bucket.

Name Description Require-

d
x-gmt- The x-gmt-tieringinfo request header enables you to configure a bucket for schedule- No
tieringinf- based automatic transitioning of objects from local HyperStore storage to a remote stor-
o age system.

The x-gmt-tieringinfo header is formatted as follows:

x-gmt-tieringinfo: PROTOCOL|EndPoint:Endpoint,Action:Action
[,Mode:proxy][,Region:Region][,TieringBucket:TieringBucket]

l PROTOCOL (mandatory) — Specify one of these values, in all caps:

o S3 -- Transition the objects to Amazon S3 storage.

o S3GLACIER -- Transition the objects to Amazon Glacier.

59
Chapter 1. S3 API

Name Description Require-

d
o GCS -- Transition the objects to Google Cloud Storage.
o AZURE -- Transition the objects to Microsoft Azure.
o SPECTRA -- Transition the objects to a Spectra Logic BlackPearl des-
tination.

Note If you are tiering to an S3-compliant system other than

Amazon S3, Glacier, or Google Cloud Storage, use "S3" as the
protocol. This would include, for instance, tiering to a remote
HyperStore region or system.

Note Auto-tiering restrictions based on destination type:

* Tiering to Azure, Google Cloud, or Spectra BlackPearl is not
supported for source buckets that have versioning enabled or
that have had versioning enabled in the past.
* When auto-tiering to Spectra BlackPearl is used for a bucket,
objects in the bucket will not be auto-tiered unless they are lar-
ger than 5MB. Objects 5MB or smaller will remain in HyperStore.

l EndPoint:EndPoint (mandatory) — The service endpoint URL to use as your

auto-tiering destination. For example with Amazon S3, choose the region end-
point that’s most suitable for your location (such as s3-us-west-1.amazon-
aws.com if your organization is in northern California). Or in the case of
Spectra BlackPearl, specify the URL for your Spectra BlackPearl destination.

If your ultimate tiering destination is Glacier, you must specify an Amazon S3

endpoint here, not a Glacier endpoint. The HyperStore system will first trans-
ition the objects to your specified Amazon S3 endpoint and then from there they
will be transitioned to the corresponding Glacier location.

Note You must use nested URL encoding. First URL encode the End-
point value (the endpoint itself), and then URL encode the whole x-gmt-
tieringinfo value.

Note Once you've configured an auto-tiering lifecycle on a source

bucket you cannot subsequently change the tiering endpoint for that
source bucket.

l Action:Action (mandatory) — This parameter specifies how the HyperStore sys-

tem will handle S3 GET Object requests for objects that have been transitioned
to the tiering destination. The choices are:

o stream — If the client submits a GET Object request to HyperStore, the

HyperStore system retrieves the object from the destination and streams
it through to the client. This method is supported only if the Protocol is
S3, GCS, or AZURE.

60
 1.2. Supported S3 Operations

Name Description Require-

d
o nostream — If the client submits a GET Object request to HyperStore,
the HyperStore system rejects the GET request. Instead, clients must
submit a POST Object restore request in order to temporarily restore a
copy of the object to local HyperStore storage.
o cache -- The local system GETs the object from the tiering destination
system and immediately streams it through to the client, and sim-
ultaneous saves a copy of the object to local storage. The local copy is
kept in local storage -- cached -- for a period that depends on how the
auto-tiering policy is configured:
n If the tiering policy uses a "Days After..." configuration, the cach-
ing retention period is the same as the number of days that trig-
gers the tiering of objects in the first place. For example, if the
auto-tiering policy is configured to tier objects 30 days after
object creation, and "Cache (Stream & Restore)" mode is selec-
ted for handling GETs of tiered objects, then when there's a GET
request for a tiered object the object is streamed to the client and
also cached locally for 30 days.
n If the tiering policy uses a "After Date..." configuration, the
cached local copy is retained only until the next running of the
auto-tiering / auto-expiration cron job (which runs once a day).
The same caching behavior applies to GETs of objects that were
tiered by "Bridge Mode" (proxy mode).

During the period while the object is cached locally, subsequent GETs
of the object can be served from local storage. After the cache period
expires, the local copy is automatically deleted by the next run of the
daily auto-tiering / auto-expiration cron job. Following deletion of the
cached copy, the next GET of the object will be served from the tiering
destination site (and a copy of the object will be once again be cached).

If the Protocol is S3, GCS, or AZURE you can use either "stream" or "nostream"
or "cache". If the Protocol is S3GLACIER or SPECTRA you must use "nostream"
(the "stream" and "cache" options are not supported for those destinations).

l Locked:true or false (optional) — You can optionally use this field to indicate
whether the destination bucket has Object Lock enabled. If you omit this field,
the system when executing tiering operations will automatically check whether
the destination bucket has Object Lock enabled or not.
l Mode:proxy (optional) — If you specify this option, then:
o All objects uploaded to the bucket from this time forward (all objects
uploaded after you successfully submit the PUT Bucket lifecycle
request) will be immediately transitioned to the destination system.
o Any objects already in the bucket at the time that you submit the PUT
Bucket lifecycle request will be subject to the transition schedule that
you define in the request body.

Proxy mode is supported only if the Protocol is S3, GCS, or AZURE (proxy
mode is not supported for S3GLACIER or SPECTRA tiering).

61
Chapter 1. S3 API

Name Description Require-

d
l Region: Region (optional) — If you are tiering to an S3 protocol endpoint other
than Amazon (for example a remote HyperStore destination) and you are hav-
ing the system create a destination bucket for you to tier to -- meaning you are
leaving the "TieringBucket" field empty or you are specifying the name of a
bucket that does not yet exist -- use the "Region" field to indicate the des-
tination service region in which you want the bucket created.
l TieringBucket:TieringBucket (optional) — The name of the bucket to transition
objects into, in the tiering destination system. This can be either:
o The name of a bucket that already exists in the destination system,
and for which you are the bucket owner. In this case HyperStore will
use this existing bucket as the tiering destination.

o The name of a bucket that you want HyperStore to create in the des-
tination system, to use as the tiering destination. Be sure to choose a
bucket name that is very likely to be unique in the destination system. If
your supplied bucket name is not unique in the destination system,
HyperStore will be unable to create the bucket and the PUT Bucket life-
cycle request will fail.

If you omit the tiering bucket parameter, then in the destination system Hyper-
Store will create a tiering bucket named as follows:

<origin-bucket-name-truncated-to-34-characters>-<28-character-ran-
dom-string>

Example x-gmt-tieringinfo request headers:

# Example 1 (before URL encoding) Tiering to Amazon S3, into target bucket
# named 'bucket12'. Streaming for local GETs will be supported.

x-gmt-tieringinfo: S3|EndPoint:http://s3.amazonaws.com,Action:stream,
TieringBucket:bucket12

# Example 1 after nested URL encoding (endpoint value first, then whole
# header value)

x-gmt-tieringinfo: S3%7CEndPoint%3Ahttp%253A%252F%252Fs3.amazonaws.com
%2CAction%3Astream%2CTieringBucket%3Abucket12

# Example 2 (before URL encoding) Tiering to Azure. HyperStore will derive

target
# bucket name from source bucket name. Streamed local GETs will not be
supported,
# clients must use Restore.

x-gmt-tieringinfo:
AZURE|EndPoint:https://blob.core.windows.net,Action:nostream

# Example 2 after nested URL encoding (endpoint value first, then whole
# header value)

62
 1.2. Supported S3 Operations

Name Description Require-

d

x-gmt-tieringinfo:
AZURE%7CEndPoint%3Ahttps%253A%252F%252Fblob.core.windows.net
%2CAction%3Anostream

x-gmt- If you include this header in your "PUT Bucket lifecycle" request and set the header No
com- value to "LAT", then in lifecycle rules that you configure with the "Days" comparator the
pare rule will be implemented as number of days since the object’s Last Access Time.

If you do not use this extension header, or if you include the header but assign it no
value or any value other than "LAT", then "Days" based lifecycle rules will be imple-
mented as number of days since the object’s Creation Time (the default Amazon S3
behavior).

You can use this header to create:

l Last Access Time based auto-tiering rules (use this header and also the x-gmt-
tierinfo header).
l Last Access Time based expiration rules (use this header but not the x-gmt-tier-
info header).

Note Last Access Time is subject to updating only for objects in buckets for
which a lifecycle is configured. For such objects, Last Access Time is updated
if the object is accessed either for retrieval (GET or HEAD) or modification
(PUT/POST/Copy). If an object is created and then never accessed, its Last
Access Time will be its Creation Time.

Note If you use the x-gmt-compare header and set it to "LAT", it does not apply
to any in NoncurrentVersionTransition or NoncurrentVersionExpiration rules
within the lifecycle policy (for non-current versions of versioned objects).
These types of rules are always based on the time elapsed since an object ver-
sion became non-current (was replaced by a new version of the object).

x-gmt- If you use the x-gmt-tieringinfo request header to configure auto-tiering for a bucket, No
post- you can optionally also use the x-gmt-post-tier-copy request header to specify a num-
tier- ber of days for which a local copy of auto-tiered objects should be retained. For
copy example if you set x-gmt-post-tier-copy: 7 then after each object is auto-tiered to the
tiering destination, a copy of the object will be kept in the HyperStore source bucket for
7 days. After that the local copy will be deleted and only object metadata will be
retained locally.

There is no upper limit on this value. So if you want the local copy retention period to
be practically limitless, you could for example set this header to 36500 to indicate a
local copy retention period of 100 years.

If you omit the x-gmt-post-tier-copy request header, then by default local objects are
deleted after they are successfully auto-tiered to the tiering destination system, and
only object metadata is retained locally.

63
Chapter 1. S3 API

1.2.60.2. Request Elements

l LifecycleConfiguration
o Rule
n AbortIncompleteMultipartUpload
l DaysAfterInitiation
n Expiration
l Date
l Days
l ExpiredObjectDeleteMarker
n Filter
l And
o ObjectSizeGreaterThan
o ObjectSizeLessThan
o Prefix
o Tag
n Key
n Value
l Prefix
l Tag
o Key
o Value
n ID
n NoncurrentVersionExpiration
l NoncurrentDays
n NoncurrentVersionTransition
l NoncurrentDays
l StorageClass
n Prefix
n Status
n Transition
l Date
l Days
l StorageClass

Note If you are using "Bridge Mode" transition (whereby objects are auto-tiered immediately after
being uploaded to HyperStore), leave the "Prefix" attribute empty. Bridge Mode does not support fil-
tering by prefix. Also, Bridge Mode does not support filtering by tag(s).

64
 1.2. Supported S3 Operations

1.2.61. PutBucketLogging
Set the logging parameters for a bucket and to specify permissions for who can view and modify the logging
parameters.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: PutBucketLogging

Former operation name: PUT Bucket logging

Note For a bucket that has bucket logging enabled, bucket logs (server access logs) are generated
every 10 minutes by a HyperStore system cron job, if there was activity for that bucket during that inter-
val.

Note If you are using bucket logging in your service, and if you use a load balancer in front of your S3
Service nodes, you should configure your S3 Service to support the HTTP X-Forwarded-For header.
This will enable bucket logs to record the true originating IP address of S3 requests, rather than the
load balancer IP address. By default the S3 Service does not support the X-Forwarded-For header.
You can enable support for this header using the system configuration file s3.xml.erb.

1.2.61.1. Request Elements

l BucketLoggingStatus
o LoggingEnabled
n TargetBucket
n TargetGrants
l Grant
o Grantee
n DisplayName
n EmailAddress
n ID
o Permission
n TargetPrefix

Note Using a comma in the TargetPrefix is prohibited.

1.2.62. PutBucketNotificationConfiguration
Enables notifications of specified events for a bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: PutBucketNotificationConfiguration

65
Chapter 1. S3 API

Note In the current HyperStore release, only the bucket owner is allowed to submit this request and
the bucket owner must also be the owner of the destination Queue.

Note HyperStore's bucket notification feature and its SQS Service (for notification message queueing
and delivery) are disabled by default. Before you can use this feature it must be enabled by a system
administrator.

1.2.62.1. Request Elements

l NotificationConfiguration
o QueueConfiguration
n Event
n Filter
l S3Key
o FilterRule
n Name
n Value
n Id
n Queue

For Event types, HyperStore supports only the following:

l s3:ObjectCreated:*
l s3:ObjectCreated:Put
l s3:ObjectCreated:Post
l s3:ObjectCreated:Copy
l s3:ObjectCreated:CompleteMultipartUpload
l s3:ObjectRemoved:*
l s3:ObjectRemoved:Delete
l s3:ObjectRemoved:DeleteMarkerCreated

1.2.63. PutBucketOwnershipControls
Creates or modifies OwnershipControls for a bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: PutBucketOwnershipControls

1.2.63.1. Request Elements

l OwnershipControls
o Rule
n ObjectOwnership

66
 1.2. Supported S3 Operations

1.2.64. PutBucketPolicy
Applies an S3 bucket policy to an S3 bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: PutBucketPolicy

For examples of the kinds of things you can do with bucket policies, see the AWS documentation: Bucket
Policy Examples

Former operation name: PUT Bucket policy

1.2.64.1. Request Elements

The request body is a JSON-formatted bucket policy containing one or more policy statements.

l Version (must be "2012-10-17")

l Id
l Statement

Within a policy's Statement block(s), HyperStore support for policy statement elements and their values
is as follows:

o Sid -- Same as AWS: Custom string identifying the statement, for example "Statement1" or "Only
allow access from partner source IPs"
o Effect -- Same as AWS: "Allow" or "Deny"
o Principal -- The following formats are supported:
n "*" -- Statement applies to all users (also known as "anonymous access").
n {"CanonicalUser": "<canonicalUserId>"} -- Statement applies to the specified Hyper-
Store account root user and to IAM users under that account.
n {"CanonicalUser": ["<canonicalUserId>", "<canonicalUserId>",...]} -- Statement applies
to the specified HyperStore account root users and to IAM users under those accounts.
n {"AWS":"arn:aws:iam::<canonicalUserId>:root"} -- Statement applies to the specified
HyperStore account root user and to IAM users under that account.
n {"AWS":"arn:aws:iam::<canonicalUserId>:user/<iamUserName>"} -- Statement applies
to the specified IAM user. In this format the <canonicalUserId> is that of the parent
account root user.

Note
* Be careful to correctly spell the principal type (highlighted in bold above).

* A HyperStore user's canonical ID can be obtained by using the Admin API

method GET /user. Details are in the Cloudian HyperStore Admin API Reference.
* In formats of the "AWS":"arn:aws:iam::...." type, AWS uses "Account Id" to identify
the account root user. In HyperStore the canonical user ID is used for this pur-
pose, since in HyperStore there is not a separate account ID that's different than
the canonical user ID.
* To access a resource, an IAM user must also be granted access to the resource

67
Chapter 1. S3 API

by an IAM policy. A bucket policy by itself is not sufficient to grant an IAM user
access to resources within the bucket. This is consistent with AWS behavior.

o NotPrincipal -- Same usage as AWS.

o Action -- See details below.
o NotAction -- Same usage as AWS.
o Resource -- Same as AWS; must be one of:
n "arn:aws:s3:::<bucketName>" -- For bucket actions (such as "s3:ListBucket") and bucket
subresource actions (such as "s3:GetBucketAcl").
n "arn:aws:s3:::<bucketName>/*" or "arn:aws:s3:::<bucketName>/<objectName>" -- For
object actions (such as "s3:PutObject").
o NotResource -- Same usage as AWS.
o Condition -- See details below.

Supported "Action" Values

Within bucket policy statements, HyperStore supports only the following Action values (also known as per-
mission keywords).

Note For information about how to use Action values in a bucket policy, see the AWS documentation
on Specifying Permissions in a Policy.

Object Actions

l s3:AbortMultipartUpload
l s3:BypassGovernanceRetention
l s3:DeleteObject
l s3:DeleteObjectTagging
l s3:DeleteObjectVersion
l s3:DeleteObjectVersionTagging
l s3:GetObject
l s3:GetObjectAcl
l s3:GetObjectLegalHold
l s3:GetObjectRetention
l s3:GetObjectTagging
l x3:GetObjectTorrent
l s3:GetObjectVersion
l s3:GetObjectVersionAcl
l s3:GetObjectVersionTagging
l s3:ListMultipartUploadParts
l s3:PutObject
l s3:PutObjectAcl

68
 1.2. Supported S3 Operations

l s3:PutObjectLegalHold
l s3:PutObjectRetention
l s3:PutObjectTagging
l s3:PutObjectVersionAcl
l s3:PutObjectVersionTagging
l s3:RestoreObject

Bucket Actions

l s3:CreateBucket
l s3:DeleteBucket
l s3:ListBucket
l s3:ListBucketMultipartUploads
l s3:ListBucketVersions

Bucket Subresource Actions

l s3:DeleteBucketPolicy
l s3:DeleteBucketWebsite
l s3:GetBucketAcl
l s3:GetBucketCORS
l s3:GetBucketLocation
l s3:GetBucketLogging
l s3:GetBucketNotification
l s3:GetBucketObjectLockConfiguration
l s3:GetBucketPolicy
l s3:GetBucketRequestPayment
l s3:GetBucketTagging
l s3:GetBucketVersioning
l s3:GetBucketWebsite
l s3:GetInventoryConfiguration
l s3:GetLifecycleConfiguration
l s3:GetReplicationConfiguration
l s3:PutBucketAcl
l s3:PutBucketCORS
l s3:PutBucketLogging
l s3:PutBucketNotification
l s3:PutBucketObjectLockConfiguration
l s3:PutBucketPolicy
l s3:PutBucketRequestPayment
l s3:PutBucketTagging
l s3:PutBucketVersioning

69
Chapter 1. S3 API

l s3:PutBucketWebsite
l s3:PutInventoryConfiguration
l s3:PutLifecycleConfiguration
l s3:PutReplicationConfiguration

Note Like AWS, the HyperStore system supports the use of a wildcard in your Action configuration
("Action":["s3:*"]). When an Action wildcard is used together with an object-level Resource element
("arn:aws:s3:::<bucketName>/*" or "arn:aws:s3:::<bucketName>/<objectName>"), the wildcard denotes
all the Object actions that HyperStore supports. When an Action wildcard is used together with
bucket-level Resource element ("arn:aws:s3:::<bucketName>"), the wildcard denotes all the Bucket
actions and Bucket Subresource actions that HyperStore supports.

Supported "Condition" Values

Within bucket policy statements, HyperStore supports only the following Condition operators and keys.

Note For information about how to use condition operators and keys in a bucket policy, see the AWS
documentation on Specifying Conditions in a Policy.

Condition Operators

l ForAllValues:StringLike
l ForAnyValue:StringLike
l IpAddress

Note If the HyperStore system uses load balancers in front of the HyperStore S3 Service, then IP
address based bucket policies will only work if system administrators have enabled the use of
PROXY Protocol between the load balancers and the S3 Service.

l NotIpAddress
l NumericEquals
l NumericNotEquals
l NumericLessThan
l NumericLessThanEquals
l NumericGreaterThan
l NumericGreaterThanEquals
l StringEquals
l StringNotEquals
l StringEqualsIgnoreCase
l StringNotEqualsIgnoreCase
l StringLike
l StringNotLike

70
 1.2. Supported S3 Operations

Condition Keys

l "aws:CurrentTime"
l "aws:EpochTime"
l "aws:Referer"
l "aws:SecureTransport"
l "aws:SourceIp"

l "aws:TokenIssueTime"
l "aws:UserAgent"
l "s3:delimiter"
l "s3:ExistingObjectTag"
l "s3:max-keys"
l "s3:object-lock-legal-hold"
l "s3:object-lock-mode"
l "s3:object-lock-remaining-retention-days"
l "s3:object-lock-retain-until-date"
l "s3:prefix"
l "s3:RequestObjectTag"
l "s3:RequestObjectTagKeys"
l "s3:VersionId"
l "s3:x-amz-acl"
l s3:x-amz-content-sha256

Note To deny access via pre-signed URLs you can create a Deny policy statement in which the
condition denied is "s3:x-amz-content-sha256": "UNSIGNED-PAYLOAD".

l "s3:x-amz-copy-source"
l "s3:x-amz-grant-full-control"
l "s3:x-amz-grant-read"
l "s3:x-amz-grant-read-acp"
l "s3:x-amz-grant-write"
l "s3:x-amz-grant-write-acp"
l "s3:x-amz-metadata-directive"
l "s3:x-amz-object-ownership"
l "s3:x-amz-server-side-encryption"
l "s3:x-amz-server-side-encryption-aws-kms-key-id"
l "saml:namequalifier"
l "saml:sub"
l "saml:sub_type"

71
Chapter 1. S3 API

1.2.65. PutBucketReplication
Creates a replication configuration or replaces an existing one.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: PutBucketReplication

Former operation name: PUT Bucket replication

Note
* Unlike Amazon S3, HyperStore does not require that you set up an IAM Role (or anything analogous)
in order to use bucket replication. Also, HyperStore does not require that the destination bucket be in a
different region than the source bucket. With HyperStore you can replicate to a destination bucket that’s
in the same region as the source bucket, if you want to.
* Like Amazon S3, HyperStore bucket replication requires that versioning must be enabled (using the
"PutBucketVersioning" (page 74) operation) on both the source bucket and the destination bucket.
* Do not set a cross-region replication configuration and a bucket lifecycle rule for auto-tiering on the
same source bucket.

1.2.65.1. Request Headers

l Content-MD5

HyperStore Extension to the S3 API

The HyperStore system supports the following Request Headers as extensions to the "PUT Bucket replication"
operation. Typically these headers are not needed for bucket replication. These headers are required only in a
scenario where you want data to be replicated to a destination bucket in an external S3-compatible system
(rather than in a service region within the same HyperStore system as the source bucket). Before using these
extensions you should review (or have a system administrator provide to you) the "Cross-System Replication"
section in the Cloudian HyperStore Administrator's Guide, including the limitations and caveats noted in that
section.

Name Description Required

x-gmt-crr-end- Service endpoint of the destination S3 service, in format <pro- See
point tocol>://<endpoint>:<port>. For example https://s3.amazonaws:443. Since description
security credentials will be transmitted in this request (see "x-gmt-crr-cre-
dentials" below), HTTPS is the recommended protocol rather than regular
HTTP. HyperStore does not force HTTPS use here, but for security HTTPS is
advisable.

This header is required only if the destination bucket is not in the same Hyper-
Store system as the source bucket. Do not use this header if the destination
bucket is in the same HyperStore system as the source bucket.

x-gmt-crr-cre- Access key and secret key for the user account that HyperStore should use to See
dentials write to the destination bucket in the destination S3 system, in format <access- description
key>:<secret-key>. For example, 00caf3940d-
c923c59406:Ku0bMR0H5nSA7t8N+ngP6uPPTINSxJ/Q2olCMexx. This user
account must have write permissions on the destination bucket. For example,

72
 1.2. Supported S3 Operations

Name Description Required

if the destination bucket is in the Amazon S3 system, this header is used to
specify the Amazon S3 access key and secret key for an account that has
write permissions on the destination bucket.

This header is required only if the destination bucket is not in the same Hyper-
Store system as the source bucket. Do not use this header if the destination
bucket is in the same HyperStore system as the source bucket.

1.2.65.2. Request Elements

l ReplicationConfiguration
o Role
o Rule
n Destination
l Bucket
l StorageClass
n ID
n Prefix
n Status

Note
* Use the same "Bucket" value formatting as in the Amazon S3 API spec, i.e. arn:aws:s3:::<buck-
etname>.
* As with the Amazon S3 API specification, for HyperStore the "Role" element must be included in the
PUT Bucket replication request. However, HyperStore ignores the "Role" element’s value (so, you can
use any random string as its value). HyperStore does not use an IAM role or anything analogous when
implementing cross-region replication.
* If you include the "StorageClass element" in the request, HyperStore ignores its value.

1.2.66. PutBucketTagging
Sets the tags for a bucket.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: PutBucketTagging

Former operation name: PUT Bucket tagging

Bucket tagging is subject to these restrictions:

l For each bucket, each tag key must be unique, and each tag key can have only one value.
l Maximum number of tags per bucket – 50
l Maximum key length – 128 Unicode characters in UTF-8
l Maximum value length – 256 Unicode characters in UTF-8

73
Chapter 1. S3 API

1.2.66.1. Request Headers

l Content-MD5

1.2.66.2. Request Elements

l Tagging
o TagSet
n Tag
l Key
l Value

1.2.67. PutBucketVersioning
Sets the versioning state of an existing bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: PutBucketVersioning

Former operation name: PUT Bucket versioning

Note Do not enable versioning on a bucket that is configured for auto-tiering to Azure, Google Cloud,
or Spectra BlackPearl. Auto-tiering to these destinations will not work properly for buckets that have ver-
sioning enabled.

1.2.67.1. Request Elements

l VersioningConfiguration
o Status

1.2.68. PutBucketWebsite
Sets the configuration of the website that is specified in the website subresource.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: PutBucketWebsite

Former operation name: PUT Bucket website

1.2.68.1. Request Elements

l WebsiteConfiguration
o ErrorDocument
n Key
o IndexDocument
n Suffix

74
 1.2. Supported S3 Operations

o RedirectAllRequestsTo
n HostName
n Protocol

1.2.69. PutObject
Adds an object to a bucket.

Along with the common headers, HyperStore supports the operation-specific headers listed below.

For operation details and examples see the AWS documentation: PutObject

Former operation name: PUT Object

1.2.69.1. Request Headers

l Cache-Control
l Content-Disposition
l Content-Encoding
l Expires
l x-amz-acl
l x-amz-sdk-checksum-algorithm

Note Along with the information about this header (and the x-amz-checksum-<algrorithm> head-
ers below) in the AWS documentation for this S3 API operation, overviews of the AWS S3 "Addi-
tional Checksum" feature are available in the AWS documentation "Checking Object Integrity"
and the AWS blog post "Additional Checksum Algorithms for Amazon S3". Note that if the
algorithm specified by x-amz-sdk-checksum-algorithm: <algorithm> is different than the
algorithm specified in the x-amz-checksum-<algorithm>: <checksum-value> header (one of the
four headers listed below), HyperStore rejects the request with an HTTP 400 error.

l x-amz-checksum-crc32
l x-amz-checksum-crc32c
l x-amz-checksum-sha1
l x-amz-checksum-sha256
l x-amz-grant-full-control
l x-amz-grant-read
l x-amz-grant-read-acp
l x-amz-grant-write
l x-amz-grant-write-acp
l x-amz-meta-*

l x-amz-object-lock-legal-hold
l x-amz-object-lock-mode

l x-amz-object-lock-retain-until-date
l x-amz-server-side-encryption

75
Chapter 1. S3 API

l x-amz-server-side-encryption-customer-algorithm
l x-amz-server-side-encryption-customer-key
l x-amz-server-side-encryption-customer-key-MD5
l x-amz-storage-class

Note HyperStore ignores the value of the x-amz-storage-class header and treats all requests as
being for storage class STANDARD.

l x-amz-tagging
l x-amz-website-redirect-location

HyperStore Restrictions on Object Names

The following control characters cannot be used anywhere in an object name and will result in a 400 Bad
Request response: 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A ("\n"), 0x0B, 0x0C, 0x0D
("\r"), 0x0E, 0x0F, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E,
0x1F

Also unsupported are:

l 0x09 ("\t") at the beginning of an object name

l 0xBF (inverted question mark) at the end of an object name
l Object names consisting only of "." or only of ".."
l Object names containing a combination of "." and "/", or a combination of ".." and "/"

1.2.69.2. Response Headers

l x-amz-expiration
l x-amz-server-side-encryption
l x-amz-server-side-encryption-customer-algorithm
l x-amz-server-side-encryption-customer-key-MD5
l x-amz-version-id

1.2.70. PutObjectAcl
Uses the acl subresource to set the access control list (ACL) permissions for an object that already exists in a
bucket.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: PutObjectAcl

Former operation name: PUT Object acl

1.2.70.1. Request Headers

l x-amz-acl
l x-amz-grant-full-control

76
 1.2. Supported S3 Operations

l x-amz-grant-read
l x-amz-grant-read-acp
l x-amz-grant-write
l x-amz-grant-write-acp

1.2.70.2. Request Elements

l AccessControlPolicy
o AccessControlList
n Grant
l Grantee
o DisplayName
o ID
l Permission
o Owner
n DisplayName
n ID

1.2.70.3. Response Headers

l x-amz-version-id

1.2.71. PutObjectLegalHold
Applies a Legal Hold configuration to the specified object.

Along with the common headers, HyperStore supports the operation-specific parameters and elements listed
below.

For operation details and examples see the AWS documentation: PutObjectLegalHold

Former operation name: PUT Object legal hold

1.2.71.1. Query Parameters

l versionId

1.2.71.2. Request Elements

l LegalHold
o Status

1.2.72. PutObjectLockConfiguration
Places an Object Lock configuration on the specified bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: PutObjectLockConfiguration

77
Chapter 1. S3 API

Former operation name: PUT Bucket object lock configuration

1.2.72.1. Request Elements

l ObjectLockConfiguration
o ObjectLockEnabled
o Rule
n DefaultRetention
l Days
l Mode
l Years

1.2.73. PutObjectRetention
Places an Object Retention configuration on an object.

Along with the common headers, HyperStore supports the operation-specific parameters, headers, and ele-
ments listed below.

For operation details and examples see the AWS documentation: PutObjectRetention

Former operation name: PUT Object retention

1.2.73.1. Query Parameters

l versionId

1.2.73.2. Request Headers

l x-amz-bypass-governance-retention

1.2.73.3. Request Elements

l Retention
o Mode
o RetainUntilDate

1.2.74. PutObjectTagging
Sets the supplied tag-set to an object that already exists in a bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: PutObjectTagging

Former operation name: PUT Object tagging

Object tagging is subject to these restrictions:

l For each object, each tag key must be unique, and each tag key can have only one value.
l Maximum number of tags per object – 10

78
 1.2. Supported S3 Operations

l Maximum key length – 128 Unicode characters in UTF-8

l Maximum value length – 256 Unicode characters in UTF-8

1.2.74.1. Request Elements

l Tagging
o TagSet
n Tag
l Key
l Value

1.2.75. PutPublicAccessBlock
Creates or modifies the PublicAccessBlock configuration for a bucket.

Along with the common headers, HyperStore supports the operation-specific elements listed below.

For operation details and examples see the AWS documentation: PutPublicAccessBlock

1.2.75.1. Request Elements

l PublicAccessBlockConfiguration
o BlockPublicAcls
o IgnorePublicAcls
o BlockPublicPolicy
o RestrictPublicBuckets

HyperStore Implementation Notes

l If BlockPublicAcls is set to true, then:

o Put object/bucket ACL calls will fail with access denied if any grant in the ACL is public (grantee
is AllUsers or AuthenticatedUsers)
o Put object calls will fail with access denied if any grant in the ACL is public (or if canned ACL is
public)
l If IgnorePublicAcls is set to true, then when performing ACL permission checks during operations on
the bucket or its objects, public grants are ignored (and therefore public accounts will be denied
access).
l If BlockPublicPolicy is set to true, then a PutBucketPolicy call will fail if any statement in the policy is pub-
lic. A statement is considered public if the Effect is Allow and the Principal has a wildcard -- unless there
is an IpAddress:{aws:SourceIp condition associated with the statement that restricts the requesting
source IP to one or more specified IP addresses.
l If RestrictPublicBuckets is set to true, then the bucket's bucket policy will be replaced with a policy that
allows access to the bucket and its objects only to the bucket owner. Note that RestrictPublicBuckets
does not restrict the use of ACLs on the bucket or its objects. To restrict ACLs use the BlockPublicAcls
and/or IgnorePublicAcls settings.

79
Chapter 1. S3 API

1.2.76. RestoreObject
Restores a tiered object back into HyperStore.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: RestoreObject

Former operation name: POST Object restore

Note In the context of the HyperStore system, this standard S3 operation is for temporarily restoring a
copy of an object that has been auto-tiered to a tiering destination, such as Amazon S3 or Amazon Gla-
cier.

1.2.76.1. Request Headers

l x-amz-sdk-checksum-algorithm

l x-amz-checksum-crc32
l x-amz-checksum-crc32c
l x-amz-checksum-sha1
l x-amz-checksum-sha256

1.2.76.2. Request Elements

l RestoreRequest
o Days
o GlacierJobParameters
n Tier

Note For the sake of S3 API compatibility, HyperStore's S3 Service allows the request elements
GlacierJobParameters and Tier to be included in a "RestoreObject" request -- but in the current
HyperStore release these elements will have no effect on how the restore request is imple-
mented. These elements pertain only to objects tiered to Glacier, and specifically the way in
which tiered objects in AWS Glacier will be temporarily retrieved into AWS S3 (for one day) so
that they then can be restored from AWS S3 to your HyperStore system for your specified num-
ber of Days. For this purpose Standard retrieval (the default) from Glacier will always used.

1.2.77. UploadPart
Uploads a part in a multipart upload.

Along with the common headers, HyperStore supports the operation-specific headers listed below.

For operation details and examples see the AWS documentation: UploadPart

Former operation name: Upload Part

80
 1.2. Supported S3 Operations

1.2.77.1. Request Headers

l x-amz-sdk-checksum-algorithm

Note Along with the information about this header (and the x-amz-checksum-<algrorithm> head-
ers below) in the AWS documentation for this S3 API operation, overviews of the AWS S3 "Addi-
tional Checksum" feature are available in the AWS documentation "Checking Object Integrity"
and the AWS blog post "Additional Checksum Algorithms for Amazon S3". Note that if the
algorithm specified by x-amz-sdk-checksum-algorithm: <algorithm> is different than the
algorithm specified in the x-amz-checksum-<algorithm>: <checksum-value> header (one of the
four headers listed below), HyperStore rejects the request with an HTTP 400 error.

l x-amz-checksum-crc32
l x-amz-checksum-crc32c
l x-amz-checksum-sha1
l x-amz-checksum-sha256

l x-amz-server-side-encryption

l x-amz-server-side-encryption-customer-algorithm

l x-amz-server-side-encryption-customer-key
l x-amz-server-side-encryption-customer-key-MD5

1.2.77.2. Response Headers

l x-amz-server-side-encryption
l x-amz-server-side-encryption-customer-algorithm
l x-amz-server-side-encryption-customer-key-MD5

1.2.78. UploadPartCopy
Uploads a part by copying data from an existing object as data source.

Along with the common headers, HyperStore supports the operation-specific headers and elements listed
below.

For operation details and examples see the AWS documentation: UploadPartCopy

Former operation name: Upload Part - Copy

1.2.78.1. Request Headers

l x-amz-copy-source
l x-amz-copy-source-if-match
l x-amz-copy-source-if-modified-since
l x-amz-copy-source-if-none-match
l x-amz-copy-source-if-unmodified-since

81
Chapter 1. S3 API

l x-amz-copy-source-range
l x-amz-source-expected-bucket-owner

1.2.78.2. Response Headers

l x-amz-copy-source-version-id
l x-amz-server-side-encryption

1.2.78.3. Response Elements

l CopyPartResult
o ETag
o LastModified

82
Chapter 2. IAM API

2.1. Introduction

2.1.1. HyperStore Support for the AWS IAM API

Subjects covered in this section:

l Introduction (immediately below)

l "Restrictions and Limitations in HyperStore's IAM Support" (page 83)
l "IAM API Notes for HyperStore Administrators" (page 84)

HyperStore provides limited support for the Amazon Web Services Identity and Access Management (IAM)
API. This support enables each HyperStore user, under his or her HyperStore user account, to create IAM
groups and IAM users and IAM roles. The HyperStore user -- also known as the "account root user" -- can then
grant those IAM groups, users, and roles permissions to perform certain actions (such as reading or writing
objects in a particular bucket or buckets). As with Amazon, the means by which a HyperStore account root user
grants such permissions to IAM groups, users, and roles is by creating and attaching "managed" IAM policies
to IAM groups, users, and roles, and/or by creating and embedding "inline" IAM policies for IAM groups, users,
and roles. By default newly created IAM entities have no permissions; they gain permissions only by their
association with managed or inline IAM policies.

In the HyperStore system all S3 object data in IAM users' buckets belongs to the parent HyperStore user
account. Consequently, if an IAM user is deleted by their HyperStore parent user, the IAM user's data is not
deleted from the system.

To access the IAM Service, HyperStore users need S3 access credentials. When users are created in Hyper-
Store, S3 access credentials are automatically created for the users.

If users are using a third party IAM client to access the HyperStore IAM Service, the users can obtain their S3
access credentials by logging in to the CMC and going to the Security Credentials page (via the drop-down
menu under the user login name). They can then supply those credentials to the third party IAM client applic-
ation.

If users are using the CMC's built-in IAM client, the CMC automatically uses the user's S3 credentials to access
the IAM service. Through the CMC's IAM section, HyperStore users can create IAM groups and users and so
on.

2.1.1.1. Restrictions and Limitations in HyperStore's IAM Support

l HyperStore supports most but not all of the Amazon IAM API "Actions". For the list of supported actions
see the "Supported IAM Actions" section.
l HyperStore supports most but not all of the Amazon IAM API policy elements, actions, resources, and
condition keys. For more information see "Supported IAM Policy Elements" (page 124).
l Only HyperStore account root users can log into the Cloudian Management Console (CMC). The IAM
users that HyperStore account root users create cannot login to the CMC, and cannot use the CMC as
their S3 client application. To access the HyperStore S3 Service, IAM users must use a third party S3 cli-

83
Chapter 2. IAM API

ent application.
l IAM users cannot use the HyperStore SQS Service.

2.1.1.2. IAM API Notes for HyperStore Administrators

l "IAM Service Configuration" (page 84)
l "Default 'admin' User Does Not Have S3 Access Credentials" (page 84)
l "HyperStore IAM Extensions to Support RBAC for Admin Functions" (page 84)
l "Deleting or Suspending HyperStore Users Who Have Created IAM Users" (page 85)
l "The IAM Service in Multi-Region Systems" (page 85)
l "DNS" (page 85)
l "IAM Request Logging" (page 85)

IAM Service Configuration

The IAM Service is enabled by default system configuration. To view the current values of all IAM related con-
figuration settings in your system, on the Config Controller node run the command hsctl config get iam. For
descriptions of these settings, see the "HyperStore Configuration Settings" section of the Cloudian HyperStore
Administrator's Guide.

Default 'admin' User Does Not Have S3 Access Credentials

As noted above, to access the IAM Service a user needs S3 access credentials. The pre-configured default sys-
tem administrative user -- the user named "admin" -- does not have S3 access credentials by default. Con-
sequently, if you are logged into the CMC as the "admin" user and you go to the CMC's IAM section you will
see the following error displayed:

"No valid Access Key detected. Cannot connect to the IAM Service."

If you want to use the functionality in the CMC's IAM section as the "admin" user, you must create S3 cre-
dentials for this user. While logged into the CMC as the "admin" user, go to the Security Credentials page (via
the drop-down menu under the login name). Then in the S3 Access Credentials section of the page, click
Create New Key. This creates S3 access credentials for the "admin" user. Now you can use the CMC's
IAM section without getting an access key error.

Note IAM users created by the "admin" user cannot create buckets or perform other S3 operations.
Such IAM users can only perform RBAC based administrative operations (see the section below), if
granted permissions by the "admin" user.

HyperStore IAM Extensions to Support RBAC for Admin Functions

The HyperStore implementation of the IAM API includes extensions that:

l Allow HyperStore system admins, group admins, or regular users to execute certain read-only Hyper-
Store administrative functions by submitting a request to the IAM Service.
l Allow HyperStore system admins, group admins, or regular users to grant their IAM users permission to
execute those same read-only HyperStore administrative functions.

84
 2.1. Introduction

For more information, including information about the client tool that HyperStore provides to help you use this
feature, see "Role-Based Access to Admin API Operations" in the Cloudian HyperStore Admin
API Reference.

Deleting or Suspending HyperStore Users Who Have Created IAM Users

If a HyperStore user creates IAM groups, users, and/or roles, and then subsequently you delete that Hyper-
Store user from the system, all IAM resources associated with that HyperStore user will also be deleted from
the system. That includes IAM groups, users, roles, and policies that the HyperStore user created, the security
credentials of those IAM users, and any object data that those IAM users have stored in the system.

If rather than deleting the HyperStore user you suspend the HyperStore user (make the user inactive), then
any IAM groups, users, and/or roles that the HyperStore user created will be unable to access any HyperStore
services (just like the suspended HyperStore user will be unable to access HyperStore services). If you sub-
sequently make the HyperStore user active again, then IAM groups, users, and roles under that HyperStore
user will again be able to access HyperStore services.

The IAM Service in Multi-Region Systems

In a multi-region HyperStore system, the IAM Service runs only on nodes in the default service region.

DNS

Be sure to configure the IAM endpoint domain in your DNS environment. For more information see the "DNS
Set-Up" section of the Cloudian HyperStore Administrator's Guide.

IAM Request Logging

Information about requests processed by the IAM Service are logged to cloudian-iam-request-info.log, which
exists on each node in the default service region.For more information see the "Logging" section of the Cloud-
ian HyperStore Administrator's Guide.

2.1.2. IAM Client Application Options

Subjects covered in this section:

l Introduction (immediately below)

l "CMC Support for IAM Functions" (page 85)
l "Accessing the IAM Service with a Third Party Client Application" (page 86)
l "Creating S3 Access Credentials for the Default System Admin User" (page 86)

Users can access and use the HyperStore IAM Service either through the Cloudian Management Console
(CMC) or a third party client application that supports IAM calls. Whether using the CMC or a third party client
application, application users must have S3 access credentials (access key ID and secret key) in order to use
the HyperStore IAM Service.

2.1.2.1. CMC Support for IAM Functions

Through the CMC, HyperStore account root users can:

l Add and manage IAM users and groups

l Add and manage IAM roles

85
Chapter 2. IAM API

l Add and manage IAM policies

l Add and manage SAML identity providers

2.1.2.2. Accessing the IAM Service with a Third Party Client Application
Third party or custom client applications can access the HyperStore IAM Service at these service endpoints:

http://iam.<organization-domain>:16080

https://iam.<organization-domain>:16443

HyperStore supports the standard IAM request line formatting, for example:

http://iam.enterprise.com:16080/?Action=<action-name>&<Parameter-name>=<value>

Note that:

l These are the default service endpoints for the HyperStore IAM Service. System administrators can cus-
tomize the endpoints.
l The HyperStore IAM Service by default uses a self-signed certificate for its HTTPS listener, so if you are
using HTTPS to access the service your client application must be configured to allow self-signed cer-
tificates.System administrators can replace the default self-signed certificate with a CA-signed cer-
tificate.
l You must configure your DNS environment to resolve the IAM Service endpoint as described in DNS
Set-Up.
l System administrators must configure the DNS environment to resolve the IAM Service endpoint as
described in "DNS Set-Up" in the Cloudian HyperStore Installation Guide.

2.1.2.3. Creating S3 Access Credentials for the Default System Admin User

Note This applies to system administrators only.

If you want the default HyperStore system admin user -- the user whose user ID is "admin" in the CMC -- to be
able to use the IAM Service, do the following:

1. Log into the CMC as the "admin" user. (You will see that an IAM tab now displays in the CMC interface,
but clicking that tab will return an authorization error until after you've completed Steps 2 and 3 below.)
2. On the right side of the CMC's top navigation bar, hold your cursor over your login name ("admin") and
then in the drop-down menu select Security Credentials.
3. In the security credentials page's S3 Access Credentials section, click Create New Key.

This creates S3 access credentials (access key ID and secret key) for the "admin" user. S3 access credentials
are required in order to access HyperStore's IAM Service. The CMC will use these credentials automatically
when the "admin" user uses the CMC to access IAM functions (on the IAM tab). Or if you are using a third party
application to access the HyperStore IAM Service, you will need to provide the credentials to that application.

Note If you created any additional system admin users prior to the HyperStore 7.1 release, and if you
want those system admin users to be able to use the IAM Service, those system admin users will need
to complete the steps described above to create S3 access credentials for themselves.

Regular users and group admins created in the CMC are given S3 credentials automatically as part of

86
 2.1. Introduction

the user creation process, so such users already have the credentials that they need to access the IAM
Service. Also, additional system admins that you create in HyperStore 7.1 or later are automatically
given S3 credentials.

2.1.3. IAM Common Request Parameters

From the "Common Parameters" section of the AWS IAM API specification, HyperStore supports the para-
meters listed below. If a common parameter from that specification section is not listed below, HyperStore does
not support it.

l Action
l Version

Note Unlike Amazon's IAM implementation, in HyperStore's IAM implementation the "Version"
request parameter is not required.

l X-Amz-Algorithm
l X-Amz-Credential
l X-Amz-Date
l X-Amz-Signature
l X-Amz-SignedHeaders

Note Like Amazon's IAM implementation, in HyperStore's IAM implementation you can either use
query parameters or the HTTP header Authorization to submit the authentication data required by the
Signature Version 2 or Signature Version 4 protocol. For more information on this topic see the
Amazon documentation topic Task 4: Add the Signature to the HTTP Request.

2.1.4. IAM Common Errors

From the "Common Errors" section of the AWS IAM API specification, HyperStore supports the errors listed
below. If a common error from that specification section is not listed below, HyperStore does not support it.

l AccessDenied
l IncompleteSignature
l InternalFailure
l InvalidAction
l InvalidClientTokenId
l InvalidParameterCombination
l InvalidParameterValue
l InvalidQueryParameter
l MalformedQueryString
l MissingAction
l MissingAuthenticationToken

87
Chapter 2. IAM API

l MissingParameter
l OptInRequired
l RequestExpired
l ServiceUnavailable
l ThrottlingException
l ValidationError

2.2. Supported IAM Actions

The HyperStore implementation of the AWS IAM API supports the Actions listed in this section. If an IAM Action
is not listed in this section, HyperStore does not support it. For each Action, the documentation here lists the
request parameters and request or response elements that HyperStore supports. If a parameter or element is
not listed in this documentation, HyperStore does not support it.

For detailed descriptions of each Action and its associated parameters and elements, see the AWS doc-
umentation links.

Note For all "List" actions (such as "ListAccessKeys", "ListGroups" and so on): The HyperStore
IAM Service does not support truncation. If the client request includes the "MaxItems" and "Marker"
request parameters, the HyperStore IAM Service ignores those parameters. Accordingly, in the
response bodies the "IsTruncated" response element will always be "false".

2.2.1. AddUserToGroup
Adds the specified user to the specified group.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: AddUserToGroup

2.2.1.1. Request Parameters

l GroupName
l UserName

2.2.1.2. Errors
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.2. AttachGroupPolicy
Attaches the specified managed policy to the specified IAM group.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: AttachGroupPolicy

88
 2.2. Supported IAM Actions

2.2.2.1. Request Parameters

l GroupName
l PolicyArn

2.2.2.2. Errors
l InvalidInput
l LimitExceeded
l NoSuchEntity
l PolicyNotAttachable
l ServiceFailure

2.2.3. AttachRolePolicy
Attaches the specified managed policy to the specified IAM role.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: AttachRolePolicy

2.2.3.1. Request Parameters

l PolicyArn
l RoleName

2.2.3.2. Errors
l InvalidInput
l LimitExceeded
l NoSuchEntity
l PolicyNotAttachable
l ServiceFailure
l UnmodifiableEntity

2.2.4. AttachUserPolicy
Attaches the specified managed policy to the specified user.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: AttachUserPolicy

2.2.4.1. Request Parameters

l PolicyArn
l UserName

89
Chapter 2. IAM API

2.2.4.2. Errors
l InvalidInput
l LimitExceeded
l NoSuchEntity
l PolicyNotAttachable
l ServiceFailure

2.2.5. CreateAccessKey
Creates a new secret access key and corresponding access key ID for the specified user.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: CreateAccessKey

2.2.5.1. Request Parameters

l UserName

2.2.5.2. Response Elements

l AccessKey

2.2.5.3. Errors
l LimitExceeded
l NoSuchEntity
l ServiceFailure

Note By default the HyperStore system allows only two key pairs per IAM user. Note that an IAM user's
inactive credentials (if any) count toward this limit, as well as active credentials.

2.2.6. CreateGroup
Creates a new group.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: CreateGroup

2.2.6.1. Request Parameters

l GroupName
l Path

90
 2.2. Supported IAM Actions

2.2.6.2. Response Elements

l Group

Note For HyperStore, within the "Group" object the system-generated "GroupId" attribute value
will be in this format: <Canonical-UID-of-HyperStore-User>|<IAM-groupname>

For example: e97eb4557aea18781f53eb2b8f7e282e|iamgroup2

The canonical user ID is that of the HyperStore user account under which the IAM group is cre-
ated. The IAM group name will be preceded by the path if any is specified when the group is cre-
ated.

Similarly, the "Arn" attribute value will be in this format:

arn:aws:iam::<Canonical-UID-of-HyperStore-User>:group/<IAM-groupname>

2.2.6.3. Errors
l EntityAlreadyExists
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.7. CreatePolicy
Creates a new managed policy under your HyperStore account.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: CreatePolicy

2.2.7.1. Request Parameters

l Description
l Path
l PolicyDocument

Note For information about HyperStore's IAM policy document support see "Supported IAM
Policy Elements" (page 124).

l PolicyName

2.2.7.2. Response Elements

l Policy

91
Chapter 2. IAM API

2.2.7.3. Errors
l EntityAlreadyExists
l InvalidInput
l LimitExceeded
l MalformedPolicyDocument
l ServiceFailure

2.2.8. CreatePolicyVersion
Creates a new version of the specified managed policy.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: CreatePolicyVersion

2.2.8.1. Request Parameters

l PolicyArn
l PolicyDocument

Note For information about HyperStore's IAM policy document support see "Supported IAM
Policy Elements" (page 124).

l SetAsDefault

2.2.8.2. Response Elements

l PolicyVersion
o CreateDate
o Document
o IsDefaultVersion
o VersionId

2.2.8.3. Errors
l InvalidInput
l LimitExceeded
l MalformedPolicyDocument
l NoSuchEntity
l ServiceFailure

2.2.9. CreateRole
Creates a new role under your account.

92
 2.2. Supported IAM Actions

HyperStore supports the parameters, parameters, and errors listed below.

For action details and examples see the AWS documentation: CreateRole

See also the AWS documentation: IAM Roles

2.2.9.1. Request Parameters

l AssumeRolePolicyDocument (also known as the "trust policy")
l Description
l MaxSessionDuration
l Path
l PermissionsBoundary
l RoleName

Example AssumeRolePolicyDocument (trust policy) for a federated/SAML principal:

{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRoleWithSAML",
"Principal": {"Federated": "arn:aws:iam::123456789012:saml-provider/adfs"},
"Condition": {"StringEquals": {"saml:aud":
"https://cmc.mycloudianhyperstore.com:8443/saml/sso"}}
}
}

The example policy above says to trust SAML assertions from the "adfs" SAML Provider to use STS:As-
sumeRoleWithSAML for this role but only if the SAML assertion contains the recipient string matching https://cm-
c.mycloudianhyperstore.com:8443/saml/sso.

IMPORTANT ! The "saml:aud" value must exactly match what is submitted by the identity provider sys-
tem (IdP). This value will come from this element in the HyperStore SAML Metadata Document for
IdP Setup (emphasis added):

<AssertionConsumerService index=“1” isDefault=“true” Bind-

ing=“urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST” Location =“https://<cmc FQDN or IP>:<-
port>/saml/sso”/>

For Condition in a trust policy, HyperStore supports only the StringEquals condition operator and only the fol-
lowing condition keys:

l aws:TokenIssueTime
l sts:ExternalId
l saml:aud
l saml:doc
l saml:iss
l saml:namequalifier

93
Chapter 2. IAM API

l saml:sub
l saml:sub_type

2.2.9.2. Response Elements

l Role

2.2.9.3. Errors
l ConcurrentModification
l EntityAlreadyExists
l InvalidInput
l LimitExceeded
l MalformedPolicyDocument
l ServiceFailure

2.2.10. CreateSAMLProvider
Creates an IAM resource that describes an identity provider (IdP) that supports SAML 2.0.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: CreateSAMLProvider

2.2.10.1. Request Parameters

l Name
l SAMLMetadataDocument

2.2.10.2. Response Elements

l SAMLProviderArn

2.2.10.3. Errors
l EntityAlreadyExists
l LimitExceeded
l ServiceFailure

2.2.11. CreateUser
Creates a new IAM user under your account.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: CreateUser

94
 2.2. Supported IAM Actions

2.2.11.1. Request Parameters

l Path
l UserName

2.2.11.2. Response Elements

l User

Note For HyperStore, within the "User" object the system-generated "UserId" attribute value will
be in this format: <Canonical-UID-of-HyperStore-User>|<IAM-username>

For example: e97eb4557aea18781f53eb2b8f7e282e|iamuser2

The canonical user ID is that of the HyperStore user account under which the IAM user is cre-
ated. The IAM user name will be preceded by the path if any is specified when the user is cre-
ated.

Similarly, the "Arn" attribute value will be in this format:

arn:aws:iam::<Canonical-UID-of-HyperStore-User>:user/<IAM-username>

2.2.11.3. Errors
l EntityAlreadyExists
l LimitExceeded
l NoSuchEntity
l ServiceFailure

Note IAM users that you create under your HyperStore user account will not be allowed to log into the
CMC or to use the CMC as their S3 client application. IAM users will need to use an S3 client applic-
ation other than the CMC to access the HyperStore S3 Service.

2.2.12. CreateVirtualMFADevice
Creates a new virtual MFA device for the HyperStore account root. After creating the virtual MFA, use
"EnableMFADevice" (page 103) to attach the MFA device to an IAM user.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: CreateVirtualMFADevice

95
Chapter 2. IAM API

2.2.12.1. Request Parameters

l Path
l Tags.member.N
o Tag
n Key
n Value
l VirtualMFADeviceName

2.2.12.2. Response Elements

l VirtualMFADevice
o Base32StringSeed
o EnableDate
o QRCodePNG
o SerialNumber
o Tags.member.N
n Tag
l Key
l Value
o User
n Arn
n CreateDate
n PasswordLastUsed
n Path
n PermissionsBoundary
l PermissionsBoundaryArn
l PermissionsBoundaryType
n Tags.member.N
l Tag
o Key
o Value
n UserId
n UserName

2.2.12.3. Errors
l ConcurrentModification
l EntityAlreadyExists
l InvalidInput

96
 2.2. Supported IAM Actions

l LimitExceeded
l ServiceFailure

2.2.13. DeactivateMFADevice
Deactivates the specified MFA device and removes it from association with the user name for which it was ori-
ginally enabled.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeactivateMFADevice

2.2.13.1. Request Parameters

l SerialNumber
l UserName

2.2.13.2. Errors
l EntityTemporarilyUnmodifiable
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.14. DeleteAccessKey
Deletes the access key pair associated with the specified IAM user.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeleteAccessKey

2.2.14.1. Request Parameters

l AccessKeyId
l UserName

2.2.14.2. Errors
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.15. DeleteGroup
Deletes the specified IAM group.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeleteGroup

97
Chapter 2. IAM API

2.2.15.1. Request Parameters

l GroupName

2.2.15.2. Errors
l DeleteConflict
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.16. DeleteGroupPolicy
Deletes the specified inline policy that is embedded in the specified IAM group.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeleteGroupPolicy

2.2.16.1. Request Parameters

l GroupName
l PolicyName

2.2.16.2. Errors
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.17. DeletePolicy
Deletes the specified managed policy.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeletePolicy

2.2.17.1. Request Parameters

l PolicyArn

2.2.17.2. Errors
l DeleteConflict
l InvalidInput
l LimitExceeded

98
 2.2. Supported IAM Actions

l NoSuchEntity
l ServiceFailure

2.2.18. DeletePolicyVersion
Deletes the specified version from the specified managed policy.

Note You cannot delete the default version of a policy using this operation. To delete the default ver-
sion a policy, use "DeletePolicy" (page 98).

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeletePolicyVersion

2.2.18.1. Request Parameters

l PolicyArn
l VersionId

2.2.18.2. Errors
l DeleteConflict
l InvalidInput
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.19. DeleteRole
Deletes the specified role.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeleteRole

2.2.19.1. Request Parameters

l RoleName

2.2.19.2. Errors
l ConcurrentModification
l DeleteConflict
l LimitExceeded
l NoSuchEntity
l ServiceFailure
l UnmodifiableEntity

99
Chapter 2. IAM API

2.2.20. DeleteRolePolicy
Deletes the specified inline policy that is embedded in the specified IAM role.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeleteRolePolicy

2.2.20.1. Request Parameters

l PolicyName
l RoleName

2.2.20.2. Errors
l LimitExceeded
l NoSuchEntity
l ServiceFailure
l UnmodifiableEntity

2.2.21. DeleteSAMLProvider
Deletes a SAML provider resource in IAM.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeleteSAMLProvider

2.2.21.1. Request Parameters

l SAMLProviderArn

2.2.21.2. Errors
l InvalidInput
l NoSuchEntity
l ServiceFailure

2.2.22. DeleteUser
Deletes the specified IAM user.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeleteUser

2.2.22.1. Request Parameters

l UserName

100
 2.2. Supported IAM Actions

2.2.22.2. Errors
l DeleteConflict
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.23. DeleteUserPolicy
Deletes the specified inline policy that is embedded in the specified IAM user.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeleteUserPolicy

2.2.23.1. Request Parameters

l PolicyName
l UserName

2.2.23.2. Errors
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.24. DeleteVirtualMFADevice
Deletes a virtual MFA device.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeleteVirtualMFADevice

2.2.24.1. Request Parameters

l SerialNumber

2.2.24.2. Errors
l DeleteConflict
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.25. DetachGroupPolicy
Removes the specified managed policy from the specified IAM group.

101
Chapter 2. IAM API

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DetachGroupPolicy

2.2.25.1. Request Parameters

l GroupName
l PolicyArn

2.2.25.2. Errors
l InvalidInput
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.26. DetachRolePolicy
Removes the specified managed policy from the specified role.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DetachRolePolicy

2.2.26.1. Request Parameters

l PolicyArn
l RoleName

2.2.26.2. Errors
l InvalidInput
l LimitExceeded
l NoSuchEntity
l ServiceFailure
l UnmodifiableEntity

2.2.27. DetachUserPolicy
Removes the specified managed policy from the specified user.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DetachUserPolicy

2.2.27.1. Request Parameters

l PolicyArn
l UserName

102
 2.2. Supported IAM Actions

2.2.27.2. Errors
l InvalidInput
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.28. EnableMFADevice
Enables the specified MFA device and associates it with the specified IAM user.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: EnableMFADevice

2.2.28.1. Request Parameters

l AuthenticationCode1
l AuthenticationCode2
l SerialNumber
l UserName

2.2.28.2. Errors
l EntityAlreadyExists
l EntityTemparilyUnmodifiable
l InvalidAuthenticationCode
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.29. GetGroup
Returns a list of IAM users that are in the specified IAM group.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: GetGroup

2.2.29.1. Request Parameters

l GroupName

Note The "Marker" and "MaxItems" request parameters, if submitted, are ignored.

103
Chapter 2. IAM API

2.2.29.2. Response Elements

l Group

Note For HyperStore, within the "Group" object the system-generated "GroupId" attribute value
will be in this format: <Canonical-UID-of-HyperStore-User>|<IAM-groupname>

For example: e97eb4557aea18781f53eb2b8f7e282e|iamgroup2

The canonical user ID is that of the HyperStore user account under which the IAM group was cre-
ated. The IAM group name will be preceded by the path if any was specified when the group
was created.

Similarly, the "Arn" attribute value will be in this format:

arn:aws:iam::<Canonical-UID-of-HyperStore-User>:group/<IAM-groupname>

l IsTruncated

Note "IsTruncated" will always be "false".

l Users.member.N

2.2.29.3. Errors
l NoSuchEntity
l ServiceFailure

2.2.30. GetGroupPolicy
Retrieves the specified inline policy document that is embedded in the specified IAM group.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: GetGroupPolicy

2.2.30.1. Request Parameters

l GroupName
l PolicyName

2.2.30.2. Response Elements

l GroupName
l PolicyDocument
l PolicyName

104
 2.2. Supported IAM Actions

2.2.30.3. Errors
l NoSuchEntity
l ServiceFailure

2.2.31. GetPolicy
Retrieves information about the specified managed policy, including the policy's default version and the total
number of IAM users, groups, and roles to which the policy is attached.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: GetPolicy

2.2.31.1. Request Parameters

l PolicyArn

2.2.31.2. Response Elements

l Policy

2.2.31.3. Errors
l InvalidInput
l NoSuchEntity
l ServiceFailure

2.2.32. GetPolicyVersion
Retrieves information about the specified version of the specified managed policy, including the policy doc-
ument.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: GetPolicyVersion

2.2.32.1. Request Parameters

l PolicyArn
l VersionId

2.2.32.2. Response Elements

l PolicyVersion

105
Chapter 2. IAM API

2.2.32.3. Errors
l InvalidInput
l NoSuchEntity
l ServiceFailure

2.2.33. GetRole
Retrieves information about the specified role, including the role's path, GUID, ARN, and the role's trust policy
that grants permission to assume the role.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: GetRole

2.2.33.1. Request Parameters

l RoleName

2.2.33.2. Response Elements

l Role

2.2.33.3. Errors
l NoSuchEntity
l ServiceFailure

2.2.34. GetRolePolicy
Retrieves the specified inline policy document that is embedded with the specified IAM role.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: GetRolePolicy

2.2.34.1. Request Parameters

l PolicyName
l RoleName

2.2.34.2. Response Elements

l PolicyDocument
l PolicyName
l RoleName

106
 2.2. Supported IAM Actions

2.2.34.3. Errors
l NoSuchEntity
l ServiceFailure

2.2.35. GetSAMLProvider
Returns the SAML provider metadata document that was uploaded when the IAM SAML provider resource
object was created or updated.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: GetSAMLProvider

2.2.35.1. Request Parameters

l SAMLProviderArn

2.2.35.2. Response Elements

l CreateDate
l SAMLMetadataDocument
l ValidUntil

2.2.35.3. Errors
l InvalidInput
l NoSuchEntity
l ServiceFailure

2.2.36. GetUser
Retrieves information about the specified IAM user, including the user's creation date, path, unique ID, and
ARN.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: GetUser

2.2.36.1. Request Parameters

l UserName

2.2.36.2. Response Elements

l User

107
Chapter 2. IAM API

Note For HyperStore, within the "User" object the system-generated "UserId" attribute value will
be in this format: <Canonical-UID-of-HyperStore-User>|<IAM-username>

For example: e97eb4557aea18781f53eb2b8f7e282e|iamuser2

The canonical user ID is that of the HyperStore user account under which the IAM user was cre-
ated.The IAM user name will be preceded by the path if any was specified when the user was
created.

Similarly, the "Arn" attribute value will be in this format:

arn:aws:iam::<Canonical-UID-of-HyperStore-User>:user/<IAM-username>

2.2.36.3. Errors
l NoSuchEntity
l ServiceFailure

2.2.37. GetUserPolicy
Retrieves the specified inline policy document that is embedded in the specified IAM user.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: GetUserPolicy

2.2.37.1. Request Parameters

l PolicyName
l UserName

2.2.37.2. Response Elements

l PolicyDocument
l PolicyName
l UserName

2.2.37.3. Errors
l NoSuchEntity
l ServiceFailure

2.2.38. ListAccessKeys
Returns information about the access key IDs associated with the specified IAM user.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListAccessKeys

108
 2.2. Supported IAM Actions

2.2.38.1. Request Parameters

l UserName

2.2.38.2. Response Elements

l AccessKeyMetadata.member.N
l IsTruncated

2.2.38.3. Errors
l NoSuchEntity
l ServiceFailure

2.2.39. ListAttachedGroupPolicies
Lists all managed policies that are attached to the specified IAM group.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListAttachedGroupPolicies

2.2.39.1. Request Parameters

l GroupName
l PathPrefix

2.2.39.2. Response Elements

l AttachedPolicies.member.N
l IsTruncated

2.2.39.3. Errors
l InvalidInput
l NoSuchEntity
l ServiceFailure

2.2.40. ListAttachedRolePolicies
Lists all managed policies that are attached to the specified IAM role.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListAttachedRolePolicies

109
Chapter 2. IAM API

2.2.40.1. Request Parameters

l PathPrefix
l UserName

2.2.40.2. Response Elements

l AttachedPolicies.member.N
l IsTruncated

2.2.40.3. Errors
l InvalidInput
l NoSuchEntity
l ServiceFailure

2.2.41. ListAttachedUserPolicies
Lists all managed policies that are attached to the specified IAM user.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListAttachedUserPolicies

2.2.41.1. Request Parameters

l PathPrefix
l UserName

2.2.41.2. Response Elements

l AttachedPolicies.member.N
l IsTruncated

2.2.41.3. Errors
l InvalidInput
l NoSuchEntity
l ServiceFailure

2.2.42. ListEntitiesForPolicy
Lists all IAM users, groups, and roles that the specified managed policy is attached to.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListEntitiesForPolicy

110
 2.2. Supported IAM Actions

2.2.42.1. Request Parameters

l EntityFilter
l PathPrefix
l PolicyArn

2.2.42.2. Response Elements

l IsTruncated

l PolicyGroups.member.N
l PolicyUsers.member.N

2.2.42.3. Errors
l InvalidInput
l NoSuchEntity
l ServiceFailure

2.2.43. ListGroupPolicies
Lists the names of the inline policies that are embedded in the specified IAM group.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListGroupPolicies

2.2.43.1. Request Parameters

l GroupName

2.2.43.2. Response Elements

l IsTruncated

l PolicyNames.member.N

2.2.43.3. Errors
l NoSuchEntity
l ServiceFailure

2.2.44. ListGroups
Lists the IAM groups that have the specified path prefix.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListGroups

111
Chapter 2. IAM API

2.2.44.1. Request Parameters

l PathPrefix

2.2.44.2. Response Elements

l Groups.member.N
l IsTruncated

2.2.44.3. Errors
l ServiceFailure

2.2.45. ListGroupsForUser
Lists the IAM groups that the specified IAM user belongs to.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListGroupsForUser

Request Parameters

l UserName

Response Elements

l Groups.member.N
l IsTruncated

Errors

l NoSuchEntity
l ServiceFailure

2.2.46. ListInstanceProfilesForRole
[IAM API Action]

HyperStore does not support the AWS "instance profiles" feature. However, HyperStore does provide limited
support for the ListInstanceProfilesForRole action because some client applications automatically make this
call during certain workflows.

l If the role specified in the request exists, this call will be processed successfully and will return an
empty list (just as if there were no instance profiles for the specified role).
l If the role specified in the request does not exist, this call will return a 404 EntityNotFound error
response.

2.2.46.1. Request Parameters

l RoleName

112
 2.2. Supported IAM Actions

2.2.47. ListMFADevices
Lists the MFA devices for an IAM user.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: ListMFADevices

2.2.47.1. Request Parameters

l UserName

2.2.47.2. Response Elements

l IsTruncated
l Marker
l MFADevices.member.N
o MFADevice
n EnableDate
n SerialNumber
n UserName

2.2.47.3. Errors
l NoSuchEntity
l ServiceFailure

2.2.48. ListPolicies
Lists all the managed policies that are available under your account.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListPolicies

2.2.48.1. Request Parameters

l OnlyAttached
l PathPrefix

Note The "Scope" request parameter, if submitted, is ignored and defaults to All. Note however that
only Local policies are currently supported in HyperStore, so the policies returned by this command will
all be Local policies.

2.2.48.2. Response Elements

l IsTruncated

113
Chapter 2. IAM API

l Policies.member.N

2.2.48.3. Errors
l ServiceFailure

2.2.49. ListPolicyVersions
Lists information about the versions of the specified managed policy, including the version that is currently set
as the policy's default version.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListPolicyVersions

2.2.49.1. Request Parameters

l PolicyArn

2.2.49.2. Response Elements

l IsTruncated

l Versions.member.N

2.2.49.3. Errors
l InvalidInput
l NoSuchEntity
l ServiceFailure

2.2.50. ListRolePolicies
Lists the names of the inline policies that are embedded in the specified IAM role.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListRolePolicies

2.2.50.1. Request Parameters

l RoleName

2.2.50.2. Response Elements

l IsTruncated

l PolicyNames.member.N

114
 2.2. Supported IAM Actions

2.2.50.3. Errors
l NoSuchEntity
l ServiceFailure

2.2.51. ListRoles
Lists the IAM roles that have the specified path prefix.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListRoles

2.2.51.1. Request Parameters

l PathPrefix

2.2.51.2. Response Elements

l IsTruncated

l Roles.member.N

2.2.51.3. Errors
l ServiceFailure

2.2.52. ListSAMLProviders
Lists the SAML provider resource objects defined in IAM in the account.

HyperStore supports the elements and errors listed below.

For action details and examples see the AWS documentation: ListSAMLProviders

2.2.52.1. Response Elements

l SAMLProviderList.member.N

2.2.52.2. Errors
l ServiceFailure

2.2.53. ListUserPolicies
Lists the names of the inline policies embedded in the specified IAM user.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListUserPolicies

115
Chapter 2. IAM API

2.2.53.1. Request Parameters

l UserName

2.2.53.2. Response Elements

l IsTruncated

l PolicyNames.member.N

2.2.53.3. Errors
l NoSuchEntity
l ServiceFailure

2.2.54. ListUsers
Lists the IAM users that have the specified path prefix.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ListUsers

2.2.54.1. Request Parameters

l PathPrefix

2.2.54.2. Response Elements

l IsTruncated

Note "IsTruncated" will always be "false".

l Users.member.N

2.2.54.3. Errors
l ServiceFailure

2.2.55. ListVirtualMFADevices
Lists the virtual MFA devices defined in the HyperStore account root by assignment status.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: ListVirtualMFADevices

2.2.55.1. Request Parameters

l AssignmentStatus

116
 2.2. Supported IAM Actions

2.2.55.2. Response Elements

l IsTruncated
l Marker
l VirtualMFADevices.member.N
o VirtualMFADevice
n Base32StringSeed
n EnableDate
n QRCodePNG
n SerialNumber
n Tags.member.N
l Tag
o Key
o Value
n User
l Arn
l CreateDate
l PasswordLastUsed
l Path
l PermissionsBoundary
o PermissionsBoundaryArn
o PermissionsBoundaryType
l Tags.member.N
o Tag
n Key
n Value
l UserId
l UserName

2.2.55.3. Errors
Only common errors are returned.

2.2.56. PutGroupPolicy
Adds or updates an inline policy document that is embedded in the specified IAM group.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: PutGroupPolicy

117
Chapter 2. IAM API

2.2.56.1. Request Parameters

l GroupName
l PolicyDocument

Note For information about HyperStore's IAM policy document support see "Supported IAM
Policy Elements" (page 124).

l PolicyName

2.2.56.2. Errors
l LimitExceeded
l MalformedPolicyDocument
l NoSuchEntity
l ServiceFailure

2.2.57. PutRolePolicy
Adds or updates an inline policy document that is embedded in the specified IAM role.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: PutRolePolicy

2.2.57.1. Request Parameters

l PolicyDocument
l PolicyName
l RoleName

2.2.57.2. Errors
l LimitExceeded
l MalformedPolicyDocument
l NoSuchEntity
l ServiceFailure
l UnmodifiableEntity

2.2.58. PutUserPolicy
Adds or updates an inline policy document that is embedded in the specified IAM user.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: PutUserPolicy

118
 2.2. Supported IAM Actions

2.2.58.1. Request Parameters

l PolicyDocument

Note For information about HyperStore's IAM policy document support see "Supported IAM
Policy Elements" (page 124).

l PolicyName
l UserName

2.2.58.2. Errors
l LimitExceeded
l MalformedPolicyDocument
l NoSuchEntity
l ServiceFailure

2.2.59. RemoveUserFromGroup
Removes the specified user from the specified group.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: RemoveUserFromGroup

2.2.59.1. Request Parameters

l GroupName
l UserName

2.2.59.2. Errors
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.60. ResyncMFADevice
Synchronizes the specified MFA device with its IAM resource object on the HyperStore servers.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: ResyncMFADevice

2.2.60.1. Request Parameters

l AuthenticationCode1
l AuthenticationCode2

119
Chapter 2. IAM API

l SerialNumber
l UserName

2.2.60.2. Errors
l InvalidAuthenticationCode
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.61. SetDefaultPolicyVersion
Sets the specified version of the specified policy as the policy's default (operative) version.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: SetDefaultPolicyVersion

2.2.61.1. Request Parameters

l PolicyArn
l VersionId

2.2.61.2. Errors
l InvalidInput
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.62. SimulatePrincipalPolicy
Simulate how a set of IAM policies attached to an IAM entity works with a list of API operations and AWS
resources to determine the policies' effective permissions.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: SimulatePrincipalPolicy

2.2.62.1. Request Parameters

l ActionNames.member.N

Note Requests with invalid or unknown actions (such as s3:PetObject) will be rejected with a
400 InvalidInput error. Requests with a wildcard action (such as s3:* ) will also be rejected with
a 400 InvalidInput error.

l MaxItems

120
 2.2. Supported IAM Actions

Note The HyperStore IAM Service does not support pagination of results. Therefore if the
request specifies a "MaxItems" value and the simulation produces more than that many results,
the request will be rejected with a 400 InvalidInput error and the error message will indicate that
the "MaxItems" value must be increased or the number of action names must be decreased.

l PolicySourceArn
l ResourceArns.member.N

2.2.62.2. Response Elements

l EvaluationResults.member.N
o EvalActionName
o EvalDecision
o EvalResourceName
o ResourceSpecificResults.member.N
n EvalResourceDecision
n EvalResourceName
l IsTruncated

Note "IsTruncated" will always be "false".

2.2.62.3. Errors
l InvalidInput
l NoSuchEntity

2.2.63. UpdateAccessKey
Changes the status of the specified access key from Active to Inactive, or vice versa.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: UpdateAccessKey

2.2.63.1. Request Parameters

l AccessKeyId
l Status
l UserName

2.2.63.2. Errors
l LimitExceeded
l NoSuchEntity
l ServiceFailure

121
Chapter 2. IAM API

2.2.64. UpdateAssumeRolePolicy
Updates the policy that grants an IAM entity permission to assume a role.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: UpdateAssumeRolePolicy

2.2.64.1. Request Parameters

l PolicyDocument
l RoleName

Note For Conditions in a trust policy, HyperStore supports only the StringEquals condition operator
and only the following condition keys:
aws:TokenIssueTime
sts:ExternalId
saml:aud
saml:doc
saml:iss
saml:namequalifier
saml:sub
saml:sub_type

2.2.64.2. Errors
l LimitExceeded
l MalformedPolicyDocument
l NoSuchEntity
l ServiceFailure
l UnmodifiableEntity

2.2.65. UpdateGroup
Updates the name and/or the path of the specified IAM group.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: UpdateGroup

2.2.65.1. Request Parameters

l GroupName
l NewGroupName
l NewPath

122
 2.2. Supported IAM Actions

2.2.65.2. Errors
l EntityAlreadyExists
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.2.66. UpdateRole
Updates the description or maximum session duration setting of a role.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: UpdateRole

2.2.66.1. Request Parameters

l Description
l MaxSessionDuration
l RoleName

2.2.66.2. Errors
l NoSuchEntity
l ServiceFailure
l UnmodifiableEntity

2.2.67. UpdateRoleDescription
Although HyperStore supports this Action, it is recommended to use UpdateRole instead.

AWS documentation: UpdateRoleDescription

2.2.68. UpdateSAMLProvider
Updates the metadata document for an existing SAML provider resource object.

HyperStore supports the parameters, response elements, and errors listed below.

For action details and examples see the AWS documentation: UpdateSAMLProvider

2.2.68.1. Request Parameters

l SAMLMetadataDocument
l SAMLProviderArn

2.2.68.2. Response Elements

l SAMLProviderArn

123
Chapter 2. IAM API

2.2.68.3. Errors
l InvalidInput
l NoSuchEntity
l ServiceFailure

2.2.69. UpdateUser
Updates the name and/or the path of the specified IAM user.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: UpdateUser

2.2.69.1. Request Parameters

l NewPath
l NewUserName
l UserName

2.2.69.2. Errors
l EntityAlreadyExists
l EntityTemporarilyUnmodifiable
l LimitExceeded
l NoSuchEntity
l ServiceFailure

2.3. Supported IAM Policy Elements

IAM policies grant permissions to IAM groups and users. You can create IAM policy documents through the
CMC or by using a third party or custom IAM client. If you use the CMC, you have the choice of using a visual
policy editor or using a JSON editor.

HyperStore supports AWS standard IAM policy formatting and most policy elements for granting S3 or IAM ser-
vice permissions.

For guidance on how to construct IAM policies for S3 service permissions or IAM service permissions, see the
AWS documentation on this topic. For example:

l Policies and Permissions

http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html

l IAM JSON Policy Elements Reference

https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html

l Actions, Resources, and Condition Keys for Amazon S3

https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazons3.html

124
 2.4. SAML Support

l Actions, Resources, and Condition Keys for Identity And Access Management

https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsid-
entityandaccessmanagement.html

Below is an example of a simple IAM policy document granting permission to list the contents of a bucket
named "bucket1":

{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::bucket1"
}]
}

Note that:

l For "Version", you must use "2012-10-17"

l HyperStore supports most but not all of the S3 Actions and IAM Actions, and most but not all of the con-
dition keys, cited in the AWS documentation for IAM policy formation. In general, when constructing IAM
policies you can use all the Actions that correspond to operations supported by the HyperStore S3 Ser-
vice and the HyperStore IAM Service. You can check the HyperStore S3 API documentation and Hyper-
Store IAM API documentation if you are unsure whether a particular operation is supported.
Alternatively you can check the CMC interface for creating an IAM policy -- the interface lists all the sup-
ported S3 actions and IAM actions.
l HyperStore does not allow IAM users to use the SQS Service. The SQS Service will reject requests
from IAM users even if those users' IAM policies are configured to allow SQS actions.
l Actions in IAM policies are case sensitive, so be sure to exactly match the desired Action name as it
appears in the AWS documentation.

2.4. SAML Support

The HyperStore object storage system supports Security Assertion Markup Language (SAML 2.0) based
access to S3 storage resources. It does so by supporting the standard AWS IAM Service calls and Security
Token Service calls that are needed to set up and execute SAML based access. With SAML, federated users --
users who have been authenticated by a trusted identity provider system (IdP) external to HyperStore -- can be
granted temporary access to S3 resources, subject to policy-based permission restrictions.

At a high level, the process of setting up and using SAML access for HyperStore works as described below.

l "Downloading the HyperStore SAML Metadata Document for IdP Setup" (page 125)
l "Using the IAM Service to Create SAML Provider Resources" (page 126)
l "Using the IAM Service to Create Roles" (page 127)
l "Using the STS Service to Assume a Role" (page 127)

2.4.1. Downloading the HyperStore SAML Metadata Document for IdP

Setup
For each external identity provider system (IdP) that you expect to be a source of SAML assertions submitted to
HyperStore , you must load the HyperStore SAML Service Provider Metadata document into the IdP. This

125
Chapter 2. IAM API

metadata document is specific to your HyperStore system, and provides the IdP with information about how to
submit SAML assertions to HyperStore. The procedure for applying the SAML Service Provider metadata doc-
ument into the IdP will depend on the IdP that you are working with (refer to your IdP's documentation), but
regardless of those particulars you can download the document from the Cloudian Management Console
(CMC) at this URL:

https://<cmc FQDN or IP>:<cmc port>/static/saml-metadata.xml

For example:

https://cmc.enterprise.com:8443/static/saml-metadata.xml

If load balancers are configured so that external access to the CMC is through a different port number
than the CMC is listening on internally (which is 8443 by default), then before the downloading of the Hyper-
Store SAML Provider Metadata document a system administrator must run the following commands on the Con-
fig Controller node:

hsctl config set cmc.ports.loadBalancer.https=<load balancer port for CMC>

hsctl config apply saml

For example:

hsctl config set cmc.ports.loadBalancer.https=443

hsctl config apply saml

This will result in the correct CMC external access port being specified within the Service Provider Metadata
document.

2.4.2. Using the IAM Service to Create SAML Provider Resources

HyperStore's IAM Service supports all the calls that you need to create and manage SAML provider resources
within the IAM Service. A SAML provider resource describes an IdP that will be a source of SAML assertions
submitted to HyperStore on behalf of federated users who have been authenticated by the IdP.

You can create SAML provider resources either by using the CMC's Manage Identity Providers page, or by
using a third party IAM client to access the HyperStore IAM Service. If you are using a third party IAM client, the
relevant IAM calls are:

l CreateSAMLProvider
l ListSAMLProviders
l GetSAMLProvider
l UpdateSAMLProvider
l DeleteSAMLProvider

You should create a SAML provider resource for each IdP that will be a trusted source of incoming SAML asser-
tions.

Note S3 credentials are needed to access the HyperStore IAM Service (and the CMC's IAM functions),
and the CMC's system administrative user named "admin" does not have these credentials by default.
For information on creating S3 credentials for the "admin" user so that this user can access the
IAM Service, see "Default 'admin' User Does Not Have S3 Access Credentials" (page 84).

126
 2.4. SAML Support

2.4.3. Using the IAM Service to Create Roles

HyperStore's IAM Service supports all the calls that you need to create and manage IAM roles. As part of cre-
ating an IAM role you define a "trust policy" that specifies who will be allowed to assume that role. To facilitate
SAML based access to HyperStore, you specify one or more SAML providers as the principal within an IAM
role's trust policy, as you create the role. Once an IAM role is created, you then specify the S3 permissions gran-
ted to that role, by either attaching a managed permissions policy to the role or creating an inline permission
policy specific to that role.

You can create and manage IAM roles either by using the CMC's Manage Roles page, or by using a third party
IAM client. If you are using a third party IAM client to access the HyperStore IAM Service, the relevant IAM calls
are:

l CreateRole
l ListRoles
l GetRole
l UpdateRole
l UpdateAssumRolePolicy
l DeleteRole
l AttachRolePolicy
l ListAttachedRolePolicies
l DetachRolePolicy
l PutRolePolicy
l ListRolePolicies
l GetRolePolicy
l DeleteRolePolicy

Note S3 credentials are needed to access the HyperStore IAM Service (and the CMC's IAM functions),
and the CMC's system administrative user named "admin" does not have these credentials by default.
For information on creating S3 credentials for the "admin" user so that this user can access the
IAM Service, see "Default 'admin' User Does Not Have S3 Access Credentials" (page 84).

2.4.3.1. Limitations
l Role session policies and role tags are not supported.
l Support for Conditions in trust policies is limited; see the CreateRole API call.

2.4.4. Using the STS Service to Assume a Role

Once an IdP has been configured with HyperStore's SAML metadata XML document, and you have created a
SAML provider IAM resource for that IdP and specified that provider as part of an IAM role's trust policy, SAML
assertions from that provider can be used to allow federated users to assume that role by calling the Hyper-
Store Security Token Service's AssumeRoleWithSAML API call. This API call initiates a role session during
which properly authenticated and authorized users are provided with temporary S3 security credentials.

There are two options for using this API call to assume a role:

127
Chapter 2. IAM API

l A third party STS client application can be used to submit an AssumeRoleWithSAML API call to Hyper-
Store's STS Service. For more information on accessing this service see "HyperStore Support for the
AWS STS API" (page 131).
l The CMC hosts a single-sign-on (SSO) page to which an IdP can submit a SAML assertion on behalf of
a user who has successfully logged into the IdP. The IdP can submit an HTTP POST to the Location
URL identified within the AssertionConsumerService attribute of the HyperStore SAML Metadata doc-
ument. Based on the submitted SAML assertion contents, the CMC will display a list of Roles for which
the user identified in the assertion is eligible. The user can select a Role from that list, and the CMC will
then submit an AssumeRoleWithSAML request for that Role to the HyperStore STS Service. The CMC
then makes the returned temporary security credentials available for the user to copy to their clipboard,
and the user can then paste the temporary credentials into an S3 application and perform the S3 oper-
ations permitted by the Role.

2.4.4.1. Limitations
Users with temporary security credentials obtained from the HyperStore STS Service:

l Cannot log into the CMC

l Cannot access the IAM Service (even with a third party client application)

128
 2.4. SAML Support

What users with temporary security credentials can do is access the HyperStore S3 Service by using a third
party S3 client application. Their S3 permissions will be limited to those permissions ascribed to the role that
they have assumed.

129
This page left intentionally blank
Chapter 3. STS API

3.1. Introduction

3.1.1. HyperStore Support for the AWS STS API

Subjects covered in this section:

l Introduction (immediately below)

l "STS API Notes for HyperStore Administrators" (page 131)

To facilitate Security Assertion Markup Language (SAML) based access to HyperStore S3 services, Hyper-
Store provides limited support for the Amazon Web Services Security Token Service (STS) API:

l Only a few STS Actions are supported -- for details see "Supported STS Actions".
l HyperStore does not allow users with temporary security credentials (obtained through the STS Ser-
vice) to perform IAM operations. The HyperStore IAM Service will reject requests that contain tem-
porary credentials. Users with temporary credentials can only access the S3 Service (within the
permission restrictions of the roles that such users assume).
l Users with temporary security credentials are not allowed to log into the CMC.

The default STS Service endpoint URLs for HTTP and HTTPS are:

l http://iam.<your-organization-domain>:16080
l https://iam.<your-organization-domain>:16443

Note The STS Service uses the same service endpoint and listening ports as the IAM Service.

To access the STS Service, HyperStore users need S3 access credentials. When users are created in Hyper-
Store, S3 access credentials are automatically created for the users.

If users are using a third party STS client to access the HyperStore STS Service, the users can obtain their S3
access credentials by logging in to the CMC and going to the Security Credentials page (via the drop-down
menu under the user login name). They can then supply those credentials to the third party STS client applic-
ation.

3.1.1.1. STS API Notes for HyperStore Administrators

Because the STS Service uses the IAM Service endpoint, the STS Service does not have its own dedicated
configuration settings. Instead, configuration settings for the IAM Service interface (such as port settings and
TLS settings) apply also to the STS Service. This includes that the STS Service is enabled by default, since the
IAM Service is enabled by default.

To view the current values of all IAM related configuration settings in your system, on the Config Controller
node run the command hsctl config get iam. For descriptions of these settings, see the "HyperStore Con-
figuration Settings" section of the Cloudian HyperStore Administrator's Guide.

131
Chapter 3. STS API

3.1.2. STS Common Request Parameters

From the "Common Parameters" section of the AWS STS API specification, HyperStore supports the para-
meters listed below. If a common parameter from that specification section is not listed below, HyperStore does
not support it.

l Action
l Version
l X-Amz-Algorithm
l X-Amz-Credential
l X-Amz-Date
l X-Amz-Security-Token (only supported for GetCallerIdentity requests)
l X-Amz-Signature
l X-Amz-SignedHeaders

3.1.3. STS Common Errors

From the "Common Errors" section of the AWS STS API specification, HyperStore supports the parameters
listed below. If a common parameter from that specification section is not listed below, HyperStore does not
support it.

l AccessDeniedException
l InternalFailure
l InvalidAction
l InvalidClientTokenId
l InvalidParameterCombination
l InvalidParameterValue
l MissingAuthenticationToken
l MissingParameter
l ServiceUnavailable
l ValidationError

3.2. Supported STS Actions

The HyperStore implementation of the AWS STS API supports the Actions listed in this section. If an STS Action
is not listed in this section, HyperStore does not support it. For each Action, the documentation here lists the
request parameters and request or response elements that HyperStore supports. If a parameter or element is
not listed in this documentation, HyperStore does not support it.

For detailed descriptions of each Action and its associated parameters and elements, see the AWS doc-
umentation links.

3.2.1. AssumeRole
Returns a set of temporary security credentials that you can use to access S3 resources that you might not nor-
mally have access to.

132
 3.2. Supported STS Actions

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: AssumeRole

Note HyperStore does not allow users with temporary security credentials to perform IAM operations.

3.2.1.1. Request Parameters

l DurationSeconds
l ExternalId
l RoleArn
l RoleSessionName

3.2.1.2. Response Elements

l AssumedRoleUser
l Credentials

3.2.1.3. Errors
l InvalidParameterValue
l NoSuchEntity

3.2.2. AssumeRoleWithSAML
Returns a set of temporary security credentials for users who have been authenticated via a SAML authen-
tication response.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: AssumeRoleWithSAML

Note For an overview of HyperStore support for SAML see "SAML Support" (page 125). For more
information about using the STS AssumeRoleWithSAML call with HyperStore see "Using the STS Ser-
vice to Assume a Role" (page 127).

3.2.2.1. Request Parameters

l DurationSeconds
l PrincipalArn
l RoleArn
l SAMLAssertion

133
Chapter 3. STS API

3.2.2.2. Response Elements

l AssumedRoleUser
l Audience
l Credentials
l Issuer
l NameQualifier
l Subject
l SubjectType

3.2.2.3. Errors
l ExpiredToken
l InvalidClientTokenId
l InvalidParameterValue

3.2.3. GetCallerIdentity
Returns details about the IAM user or role whose credentials are used to call the operation.

HyperStore supports the elements listed below.

For action details and examples see the AWS documentation: GetCallerIdentity

3.2.3.1. Response Elements

l Account
l Arn
l UserId

3.2.3.2. Errors
l ExpiredToken
l InvalidClientTokenId

134
Chapter 4. SQS API

4.1. Introduction

4.1.1. HyperStore Support for the AWS SQS API

Subjects covered in this section:

l Introduction (immediately below)

l "SQS API Notes for HyperStore Administrators" (page 136)

In support of the bucket notifications feature, HyperStore provides limited support for the Amazon Web Ser-
vices Simple Queue Service (SQS) API. The queueing and processing of messages is implemented within the
HyperStore system. Bucket owners can use the S3 API operation "PutBucketNotificationConfiguration"
(page 65) to configure bucket notifications so that when specified S3 operations occur within the bucket -- such
as objects being uploaded to the bucket or deleted from the bucket -- HyperStore publishes a notification mes-
sage to a specified SQS queue.

In the current HyperStore release, there are these limitations to the bucket notifications feature and the SQS
Service:

l A third party SQS client application must be used to interface with the HyperStore SQS Service to per-
form operations such as creating and configuring queues and receiving and deleting queued mes-
sages. The Cloudian Management Console (CMC) does not support SQS operations.
l A third party S3 client application must be used to execute the "PutBucketNotificationConfiguration"
(page 65) operation. The CMC does not support this S3 operation.
l For bucket notifications to an SQS queue to work, the bucket owner must also be the owner of the
SQS queue.
l IAM users cannot use the SQS Service. Only HyperStore account root users can use the SQS Service.
l The HyperStore SQS Service supports many of the Actions from the Amazon SQS API, but not all of
them. For more detail see "SQS Supported Actions" (page 136).

The SQS Service and the bucket notifications feature are disabled by default (HyperStore administrators see
"Enabling the SQS Service and the Bucket Notification Feature" (page 136)). When the SQS Service and
the bucket notifications feature are enabled then:

l A third party SQS client application can be used to submit requests to the HyperStore SQS Service,
such as for creating and configuring a queue. For HyperStore support of SQS Actions see "SQS Sup-
ported Actions" (page 136). The default SQS Service endpoint URL including the port number is
http://sqs.<your-organization-domain>:18090
l A third party S3 client application can be used to submit a PutBucketNotificationConfiguration request
to the HyperStore S3 Service, to configure notifications for an existing bucket. For HyperStore support of
this S3 API method see "PutBucketNotificationConfiguration" (page 65). As noted previously, the
bucket owner must also be the SQS queue owner.

To access the SQS Service, HyperStore users need S3 access credentials. When users are created in Hyper-
Store, S3 access credentials are automatically created for the users.

135
Chapter 4. SQS API

If users are using a third party SQS client to access the HyperStore SQS Service, the users can obtain their S3
access credentials by logging in to the CMC and going to the Security Credentials page (via the drop-down
menu under the user login name). They can then supply those credentials to the third party SQS client applic-
ation.

4.1.1.1. SQS API Notes for HyperStore Administrators

l "Enabling the SQS Service and the Bucket Notification Feature" (page 136)
l "DNS" (page 136)
l "SQS Request Logging" (page 136)

Enabling the SQS Service and the Bucket Notification Feature

HyperStore's SQS Service and its bucket notifications feature are disabled by default. To enable the SQS Ser-
vice and the bucket notifications feature, run the following hsctl commands on the Config Controller node:

# hsctl config set sqs.enabled true

# hsctl config apply sqs
# hsctl service restart sqs --nodes=ALL

Note To view the current values of all SQS related configuration settings in your system, run the com-
mand hsctl config get sqs. For descriptions of these settings, see the "HyperStore Configuration Set-
tings" section of the Cloudian HyperStore Administrator's Guide.

DNS

Be sure to configure the SQS endpoint domain in your DNS environment so that the endpoint is resolvable for
SQS clients. For more information see the "DNS Set-Up" section of the Cloudian HyperStore Administrator's
Guide.

SQS Request Logging

Information about requests processed by the SQS Service are logged to cloudian-sqs-request.log, which exists
on each node.For more information see the "Logging" section of the Cloudian HyperStore Administrator's
Guide.

4.2. SQS Supported Actions

The HyperStore implementation of the AWS SQS API supports the Actions listed in this section. If an SQS
Action is not listed in this section, HyperStore does not support it. For each Action, the documentation here lists
the request parameters and request or response elements that HyperStore supports. If a parameter or element
is not listed in this documentation, HyperStore does not support it.

For detailed descriptions of each Action and its associated parameters and elements, see the AWS doc-
umentation links.

Note The HyperStore SQS Service is disabled by default. System administrators can enable the ser-
vice.

136
 4.2. SQS Supported Actions

4.2.1. ChangeMessageVisibility
Changes the visibility timeout of a specified message in a queue to a new value.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: ChangeMessageVisibility

4.2.1.1. Request Parameters

l QueueUrl
l ReceiptHandle
l VisibilityTimeout

4.2.1.2. Errors
l AWS.SimpleQueueService.MessageNotInflight
l ReceiptHandleIsInvalid

4.2.2. CreateQueue
Creates a new standard queue.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: CreateQueue

Note HyperStore currently only supports Standard queues. HyperStore does not support FIFO queues.

4.2.2.1. Request Parameters

l Attribute

HyperStore currently only supports these queue attributes:

o DelaySeconds
o MaximumMessageSize
o MessageRetentionPeriod
o ReceiveMessageWaitTimeSeconds
o VisibilityTimeout

Any other attributes included in the CreateQueue request will be ignored.

l QueueName
l Tag

137
Chapter 4. SQS API

4.2.2.2. Response Elements

l QueueUrl

4.2.2.3. Errors
l AWS.SimpleQueueService.QueueDeletedRecently
l QueueAlreadyExists

4.2.3. DeleteMessage
Deletes the specified message from the specified queue.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: DeleteMessage

4.2.3.1. Request Parameters

l QueueUrl
l ReceiptHandle

4.2.3.2. Errors
l InvalidIdFormat
l ReceiptHandleIsInvalid

4.2.4. DeleteQueue
Deletes the queue specified by the QueueUrl, regardless of the queue's contents.

HyperStore supports the parameters listed below.

For action details and examples see the AWS documentation: DeleteQueue

4.2.4.1. Request Parameters

l QueueUrl

4.2.5. GetQueueAttributes
Gets attributes for the specified queue.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: GetQueueAttributes

4.2.5.1. Request Parameters

l AttributeName.N

138
 4.2. SQS Supported Actions

Note For the list of queue attributes that HyperStore supports, see "CreateQueue" (page 137).

l QueueUrl

4.2.5.2. Response Elements

l Attribute

4.2.5.3. Errors
l InvalidAttributeName

4.2.6. GetQueueUrl
Returns the URL of an existing Amazon SQS queue.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: GetQueueUrl

4.2.6.1. Request Parameters

l QueueName
l QueueOwnerAWSAccountId

4.2.6.2. Response Elements

l QueueUrl

4.2.6.3. Errors
l AWS.SimpleQueueService.NonExistentQueue

4.2.7. ListQueues
Returns a list of your queues in the current region.

HyperStore supports the parameters and elements listed below.

For action details and examples see the AWS documentation: ListQueues

4.2.7.1. Request Parameters

l MaxResults
l NextToken
l QueueNamePrefix

139
Chapter 4. SQS API

4.2.7.2. Response Elements

l NextToken
l QueueUrl.N

4.2.8. PurgeQueue
Deletes the messages in a queue specified by the QueueURL parameter.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: PurgeQueue

4.2.8.1. Request Parameters

l QueueUrl

4.2.8.2. Errors
l AWS.SimpleQueueService.NonExistentQueue
l AWS.SimpleQueueService.PurgeQueueInProgress

4.2.9. ReceiveMessage
Retrieves one or more messages (up to 10), from the specified queue.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: ReceiveMessage

4.2.9.1. Request Parameters

l MaxNumberOfMessages
l QueueUrl
l ReceiveRequestAttemptId
l VisibilityTimeout
l WaitTimeSeconds

Note HyperStore does not currently support message attributes.

4.2.9.2. Response Elements

l Message.N

4.2.9.3. Errors
l OverLimit

140
 4.2. SQS Supported Actions

4.2.10. SendMessage
Delivers a message to the specified queue.

HyperStore supports the parameters, elements, and errors listed below.

For action details and examples see the AWS documentation: SendMessage

Note The SendMessage action is not intended to be used by external SQS clients. The HyperStore S3
Service internally uses the SendMessage action to publish notification messages to a queue.

4.2.10.1. Request Parameters

l DelaySeconds
l MessageBody
l QueueUrl

Note HyperStore does not currently support message attributes.

4.2.10.2. Response Elements

l MD5OfMessageBody
l MessageId

4.2.10.3. Errors
l AWS.SimpleQueueService.UnsupportedOperation
l InvalidMessageContents

4.2.11. SetQueueAttributes
Sets the value of one or more queue attributes.

HyperStore supports the parameters and errors listed below.

For action details and examples see the AWS documentation: SetQueueAttributes

4.2.11.1. Request Parameters

l Attribute

Note For the list of queue attributes that HyperStore supports see "CreateQueue" (page 137).

141
Chapter 4. SQS API

l QueueUrl

4.2.11.2. Errors
l InvalidAttributeName

142