Admin Operations

An admin API request will be done on a URI that starts with the configurable ‘admin’resource entry point. Authorization for the admin API duplicates the S3 authorizationmechanism. Some operations require that the user holds special administrative capabilities.The response entity type (XML or JSON) may be specified as the ‘format’ option in therequest and defaults to JSON if not specified.

Get Usage

Request bandwidth usage information.

Note: this feature is disabled by default, can be enabled by setting rgwenable usage log = true in the appropriate section of ceph.conf. For changesin ceph.conf to take effect, radosgw process restart is needed.

• caps
• usage=read

Syntax

GET /{admin}/usage?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

• Description

• The user for which the information is requested. If not specified will apply to all users.

• Type

• String

• Example

• foo_user

• Required

• No

start

• Description

• Date and (optional) time that specifies the start time of the requested data.

• Type

• String

• Example

• 2012-09-25 16:00:00

• Required

• No

end

• Description

• Date and (optional) time that specifies the end time of the requested data (non-inclusive).

• Type

• String

• Example

• 2012-09-25 16:00:00

• Required

• No

show-entries

• Description

• Specifies whether data entries should be returned.

• Type

• Boolean

• Example

• True [True]

• Required

• No

show-summary

• Description

• Specifies whether data summary should be returned.

• Type

• Boolean

• Example

• True [True]

• Required

• No

Response Entities

If successful, the response contains the requested information.

usage

• Description

• A container for the usage information.

• Type

• Container

entries

• Description

• A container for the usage entries information.

• Type

• Container

user

• Description

• A container for the user data information.

• Type

• Container

owner

• Description

• The name of the user that owns the buckets.

• Type

• String

bucket

• Description

• The bucket name.

• Type

• String

time

• Description

• Time lower bound for which data is being specified (rounded to the beginning of the first relevant hour).

• Type

• String

epoch

• Description

• The time specified in seconds since 1/1/1970.

• Type

• String

categories

• Description

• A container for stats categories.

• Type

• Container

entry

• Description

• A container for stats entry.

• Type

• Container

category

• Description

• Name of request category for which the stats are provided.

• Type

• String

bytes_sent

• Description

• Number of bytes sent by the RADOS Gateway.

• Type

• Integer

bytes_received

• Description

• Number of bytes received by the RADOS Gateway.

• Type

• Integer

ops

• Description

• Number of operations.

• Type

• Integer

successful_ops

• Description

• Number of successful operations.

• Type

• Integer

summary

• Description

• A container for stats summary.

• Type

• Container

total

• Description

• A container for stats summary aggregated total.

• Type

• Container

Special Error Responses

TBD.

Trim Usage

Remove usage information. With no dates specified, removes all usageinformation.

Note: this feature is disabled by default, can be enabled by setting rgwenable usage log = true in the appropriate section of ceph.conf. For changesin ceph.conf to take effect, radosgw process restart is needed.

• caps
• usage=write

Syntax

DELETE /{admin}/usage?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

• Description

• The user for which the information is requested. If not specified will apply to all users.

• Type

• String

• Example

• foo_user

• Required

• No

start

• Description

• Date and (optional) time that specifies the start time of the requested data.

• Type

• String

• Example

• 2012-09-25 16:00:00

• Required

• No

end

• Description

• Date and (optional) time that specifies the end time of the requested data (none inclusive).

• Type

• String

• Example

• 2012-09-25 16:00:00

• Required

• No

remove-all

• Description

• Required when uid is not specified, in order to acknowledge multi user data removal.

• Type

• Boolean

• Example

• True [False]

• Required

• No

Special Error Responses

TBD.

Get User Info

Get user information.

• caps
• users=read

Syntax

GET /{admin}/user?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

• Description

• The user for which the information is requested.

• Type

• String

• Example

• foo_user

• Required

• Yes

Response Entities

If successful, the response contains the user information.

user

• Description

• A container for the user data information.

• Type

• Container

user_id

• Description

• The user id.

• Type

• String

• Parent

• user

display_name

• Description

• Display name for the user.

• Type

• String

• Parent

• user

suspended

• Description

• True if the user is suspended.

• Type

• Boolean

• Parent

• user

max_buckets

• Description

• The maximum number of buckets to be owned by the user.

• Type

• Integer

• Parent

• user

subusers

• Description

• Subusers associated with this user account.

• Type

• Container

• Parent

• user

keys

• Description

• S3 keys associated with this user account.

• Type

• Container

• Parent

• user

swift_keys

• Description

• Swift keys associated with this user account.

• Type

• Container

• Parent

• user

caps

• Description

• User capabilities.

• Type

• Container

• Parent

• user

Special Error Responses

None.

Create User

Create a new user. By default, a S3 key pair will be created automaticallyand returned in the response. If only one of access-key or secret-keyis provided, the omitted key will be automatically generated. By default, agenerated key is added to the keyring without replacing an existing key pair.If access-key is specified and refers to an existing key owned by the userthen it will be modified.

New in version Luminous.

A tenant may either be specified as a part of uid or as an additionalrequest param.

• caps
• users=write

Syntax

PUT /{admin}/user?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

• Description

• The user ID to be created.

• Type

• String

• Example

• foo_user

• Required

• Yes

A tenant name may also specified as a part of uid, by following the syntaxtenant$user, refer to Multitenancy for more details.

display-name

• Description

• The display name of the user to be created.

• Type

• String

• Example

• foo user

• Required

• Yes

email

• Description

• The email address associated with the user.

• Type

• String

• Example

• foo@bar.com

• Required

• No

key-type

• Description

• Key type to be generated, options are: swift, s3 (default).

• Type

• String

• Example

• s3 [s3]

• Required

• No

access-key

• Description

• Specify access key.

• Type

• String

• Example

• ABCD0EF12GHIJ2K34LMN

• Required

• No

secret-key

• Description

• Specify secret key.

• Type

• String

• Example

• 0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8

• Required

• No

user-caps

• Description

• User capabilities.

• Type

• String

• Example

• usage=read, write; users=read

• Required

• No

generate-key

• Description

• Generate a new key pair and add to the existing keyring.

• Type

• Boolean

• Example

• True [True]

• Required

• No

max-buckets

• Description

• Specify the maximum number of buckets the user can own.

• Type

• Integer

• Example

• 500 [1000]

• Required

• No

suspended

• Description

• Specify whether the user should be suspended.

• Type

• Boolean

• Example

• False [False]

• Required

• No

New in version Jewel.

tenant

• Description

• the Tenant under which a user is a part of.

• Type

• string

• Example

• tenant1

• Required

• No

Response Entities

If successful, the response contains the user information.

user

• Description

• A container for the user data information.

• Type

• Container

tenant

• Description

• The tenant which user is a part of.

• Type

• String

• Parent

• user

user_id

• Description

• The user id.

• Type

• String

• Parent

• user

display_name

• Description

• Display name for the user.

• Type

• String

• Parent

• user

suspended

• Description

• True if the user is suspended.

• Type

• Boolean

• Parent

• user

max_buckets

• Description

• The maximum number of buckets to be owned by the user.

• Type

• Integer

• Parent

• user

subusers

• Description

• Subusers associated with this user account.

• Type

• Container

• Parent

• user

keys

• Description

• S3 keys associated with this user account.

• Type

• Container

• Parent

• user

swift_keys

• Description

• Swift keys associated with this user account.

• Type

• Container

• Parent

• user

caps

• Description

• User capabilities.

• Type

• Container

• Parent

• user

Special Error Responses

UserExists

• Description

• Attempt to create existing user.

• Code

• 409 Conflict

InvalidAccessKey

• Description

• Invalid access key specified.

• Code

• 400 Bad Request

InvalidKeyType

• Description

• Invalid key type specified.

• Code

• 400 Bad Request

InvalidSecretKey

• Description

• Invalid secret key specified.

• Code

• 400 Bad Request

InvalidKeyType

• Description

• Invalid key type specified.

• Code

• 400 Bad Request

KeyExists

• Description

• Provided access key exists and belongs to another user.

• Code

• 409 Conflict

EmailExists

• Description

• Provided email address exists.

• Code

• 409 Conflict

InvalidCapability

• Description

• Attempt to grant invalid admin capability.

• Code

• 400 Bad Request

Modify User

Modify a user.

• caps
• users=write

Syntax

POST /{admin}/user?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

• Description

• The user ID to be modified.

• Type

• String

• Example

• foo_user

• Required

• Yes

display-name

• Description

• The display name of the user to be modified.

• Type

• String

• Example

• foo user

• Required

• No

email

• Description

• The email address to be associated with the user.

• Type

• String

• Example

• foo@bar.com

• Required

• No

generate-key

• Description

• Generate a new key pair and add to the existing keyring.

• Type

• Boolean

• Example

• True [False]

• Required

• No

access-key

• Description

• Specify access key.

• Type

• String

• Example

• ABCD0EF12GHIJ2K34LMN

• Required

• No

secret-key

• Description

• Specify secret key.

• Type

• String

• Example

• 0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8

• Required

• No

key-type

• Description

• Key type to be generated, options are: swift, s3 (default).

• Type

• String

• Example

• s3

• Required

• No

user-caps

• Description

• User capabilities.

• Type

• String

• Example

• usage=read, write; users=read

• Required

• No

max-buckets

• Description

• Specify the maximum number of buckets the user can own.

• Type

• Integer

• Example

• 500 [1000]

• Required

• No

suspended

• Description

• Specify whether the user should be suspended.

• Type

• Boolean

• Example

• False [False]

• Required

• No

op-mask

• Description

• The op-mask of the user to be modified.

• Type

• String

• Example

• read, write, delete, *

• Required

• No

Response Entities

If successful, the response contains the user information.

user

• Description

• A container for the user data information.

• Type

• Container

user_id

• Description

• The user id.

• Type

• String

• Parent

• user

display_name

• Description

• Display name for the user.

• Type

• String

• Parent

• user

suspended

• Description

• True if the user is suspended.

• Type

• Boolean

• Parent

• user

max_buckets

• Description

• The maximum number of buckets to be owned by the user.

• Type

• Integer

• Parent

• user

subusers

• Description

• Subusers associated with this user account.

• Type

• Container

• Parent

• user

keys

• Description

• S3 keys associated with this user account.

• Type

• Container

• Parent

• user

swift_keys

• Description

• Swift keys associated with this user account.

• Type

• Container

• Parent

• user

caps

• Description

• User capabilities.

• Type

• Container

• Parent

• user

Special Error Responses

InvalidAccessKey

• Description

• Invalid access key specified.

• Code

• 400 Bad Request

InvalidKeyType

• Description

• Invalid key type specified.

• Code

• 400 Bad Request

InvalidSecretKey

• Description

• Invalid secret key specified.

• Code

• 400 Bad Request

KeyExists

• Description

• Provided access key exists and belongs to another user.

• Code

• 409 Conflict

EmailExists

• Description

• Provided email address exists.

• Code

• 409 Conflict

InvalidCapability

• Description

• Attempt to grant invalid admin capability.

• Code

• 400 Bad Request

Remove User

Remove an existing user.

• caps
• users=write

Syntax

DELETE /{admin}/user?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

• Description

• The user ID to be removed.

• Type

• String

• Example

• foo_user

• Required

• Yes.

purge-data

• Description

• When specified the buckets and objects belongingto the user will also be removed.

• Type

• Boolean

• Example

• True

• Required

• No

Response Entities

None

Special Error Responses

None.

Create Subuser

Create a new subuser (primarily useful for clients using the Swift API).Note that in general for a subuser to be useful, it must be grantedpermissions by specifying access. As with user creation ifsubuser is specified without secret, then a secret key willbe automatically generated.

• caps
• users=write

Syntax

PUT /{admin}/user?subuser&format=json HTTP/1.1
Host {fqdn}

Request Parameters

uid

• Description

• The user ID under which a subuser is to be created.

• Type

• String

• Example

• foo_user

• Required

• Yes

subuser

• Description

• Specify the subuser ID to be created.

• Type

• String

• Example

• sub_foo

• Required

• Yes

secret-key

• Description

• Specify secret key.

• Type

• String

• Example

• 0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8

• Required

• No

key-type

• Description

• Key type to be generated, options are: swift (default), s3.

• Type

• String

• Example

• swift [swift]

• Required

• No

access

• Description

• Set access permissions for sub-user, should be oneof read, write, readwrite, full.

• Type

• String

• Example

• read

• Required

• No

generate-secret

• Description

• Generate the secret key.

• Type

• Boolean

• Example

• True [False]

• Required

• No

Response Entities

If successful, the response contains the subuser information.

subusers

• Description

• Subusers associated with the user account.

• Type

• Container

id

• Description

• Subuser id.

• Type

• String

• Parent

• subusers

permissions

• Description

• Subuser access to user account.

• Type

• String

• Parent

• subusers

Special Error Responses

SubuserExists

• Description

• Specified subuser exists.

• Code

• 409 Conflict

InvalidKeyType

• Description

• Invalid key type specified.

• Code

• 400 Bad Request

InvalidSecretKey

• Description

• Invalid secret key specified.

• Code

• 400 Bad Request

InvalidAccess

• Description

• Invalid subuser access specified.

• Code

• 400 Bad Request

Modify Subuser

Modify an existing subuser

• caps
• users=write

Syntax

POST /{admin}/user?subuser&format=json HTTP/1.1
Host {fqdn}

Request Parameters

uid

• Description

• The user ID under which the subuser is to be modified.

• Type

• String

• Example

• foo_user

• Required

• Yes

subuser

• Description

• The subuser ID to be modified.

• Type

• String

• Example

• sub_foo

• Required

• Yes

generate-secret

• Description

• Generate a new secret key for the subuser,replacing the existing key.

• Type

• Boolean

• Example

• True [False]

• Required

• No

secret

• Description

• Specify secret key.

• Type

• String

• Example

• 0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8

• Required

• No

key-type

• Description

• Key type to be generated, options are: swift (default), s3 .

• Type

• String

• Example

• swift [swift]

• Required

• No

access

• Description

• Set access permissions for sub-user, should be oneof read, write, readwrite, full.

• Type

• String

• Example

• read

• Required

• No

Response Entities

If successful, the response contains the subuser information.

subusers

• Description

• Subusers associated with the user account.

• Type

• Container

id

• Description

• Subuser id.

• Type

• String

• Parent

• subusers

permissions

• Description

• Subuser access to user account.

• Type

• String

• Parent

• subusers

Special Error Responses

InvalidKeyType

• Description

• Invalid key type specified.

• Code

• 400 Bad Request

InvalidSecretKey

• Description

• Invalid secret key specified.

• Code

• 400 Bad Request

InvalidAccess

• Description

• Invalid subuser access specified.

• Code

• 400 Bad Request

Remove Subuser

Remove an existing subuser

• caps
• users=write

Syntax

DELETE /{admin}/user?subuser&format=json HTTP/1.1
Host {fqdn}

Request Parameters

uid

• Description

• The user ID under which the subuser is to be removed.

• Type

• String

• Example

• foo_user

• Required

• Yes

subuser

• Description

• The subuser ID to be removed.

• Type

• String

• Example

• sub_foo

• Required

• Yes

purge-keys

• Description

• Remove keys belonging to the subuser.

• Type

• Boolean

• Example

• True [True]

• Required

• No

Response Entities

None.

Special Error Responses

None.

Create Key

Create a new key. If a subuser is specified then by default created keyswill be swift type. If only one of access-key or secret-key is provided thecommitted key will be automatically generated, that is if only secret-key isspecified then access-key will be automatically generated. By default, agenerated key is added to the keyring without replacing an existing key pair.If access-key is specified and refers to an existing key owned by the userthen it will be modified. The response is a container listing all keys of the sametype as the key created. Note that when creating a swift key, specifying the optionaccess-key will have no effect. Additionally, only one swift key may be held byeach user or subuser.

• caps
• users=write

Syntax

PUT /{admin}/user?key&format=json HTTP/1.1
Host {fqdn}

Request Parameters

uid

• Description

• The user ID to receive the new key.

• Type

• String

• Example

• foo_user

• Required

• Yes

subuser

• Description

• The subuser ID to receive the new key.

• Type

• String

• Example

• sub_foo

• Required

• No

key-type

• Description

• Key type to be generated, options are: swift, s3 (default).

• Type

• String

• Example

• s3 [s3]

• Required

• No

access-key

• Description

• Specify the access key.

• Type

• String

• Example

• AB01C2D3EF45G6H7IJ8K

• Required

• No

secret-key

• Description

• Specify the secret key.

• Type

• String

• Example

• 0ab/CdeFGhij1klmnopqRSTUv1WxyZabcDEFgHij

• Required

• No

generate-key

• Description

• Generate a new key pair and add to the existing keyring.

• Type

• Boolean

• Example

• True [True]

• Required

• No

Response Entities

keys

• Description

• Keys of type created associated with this user account.

• Type

• Container

user

• Description

• The user account associated with the key.

• Type

• String

• Parent

• keys

access-key

• Description

• The access key.

• Type

• String

• Parent

• keys

secret-key

• Description

• The secret key

• Type

• String

• Parent

• keys

Special Error Responses

InvalidAccessKey

• Description

• Invalid access key specified.

• Code

• 400 Bad Request

InvalidKeyType

• Description

• Invalid key type specified.

• Code

• 400 Bad Request

InvalidSecretKey

• Description

• Invalid secret key specified.

• Code

• 400 Bad Request

InvalidKeyType

• Description

• Invalid key type specified.

• Code

• 400 Bad Request

KeyExists

• Description

• Provided access key exists and belongs to another user.

• Code

• 409 Conflict

Remove Key

Remove an existing key.

• caps
• users=write

Syntax

DELETE /{admin}/user?key&format=json HTTP/1.1
Host {fqdn}

Request Parameters

access-key

• Description

• The S3 access key belonging to the S3 key pair to remove.

• Type

• String

• Example

• AB01C2D3EF45G6H7IJ8K

• Required

• Yes

uid

• Description

• The user to remove the key from.

• Type

• String

• Example

• foo_user

• Required

• No

subuser

• Description

• The subuser to remove the key from.

• Type

• String

• Example

• sub_foo

• Required

• No

key-type

• Description

• Key type to be removed, options are: swift, s3.NOTE: Required to remove swift key.

• Type

• String

• Example

• swift

• Required

• No

Special Error Responses

None.

Response Entities

None.

Get Bucket Info

Get information about a subset of the existing buckets. If uid is specifiedwithout bucket then all buckets belonging to the user will be returned. Ifbucket alone is specified, information for that particular bucket will beretrieved.

• caps
• buckets=read

Syntax

GET /{admin}/bucket?format=json HTTP/1.1
Host {fqdn}

Request Parameters

bucket

• Description

• The bucket to return info on.

• Type

• String

• Example

• foo_bucket

• Required

• No

uid

• Description

• The user to retrieve bucket information for.

• Type

• String

• Example

• foo_user

• Required

• No

stats

• Description

• Return bucket statistics.

• Type

• Boolean

• Example

• True [False]

• Required

• No

Response Entities

If successful the request returns a buckets container containingthe desired bucket information.

stats

• Description

• Per bucket information.

• Type

• Container

buckets

• Description

• Contains a list of one or more bucket containers.

• Type

• Container

bucket

• Description

• Container for single bucket information.

• Type

• Container

• Parent

• buckets

name

• Description

• The name of the bucket.

• Type

• String

• Parent

• bucket

pool

• Description

• The pool the bucket is stored in.

• Type

• String

• Parent

• bucket

id

• Description

• The unique bucket id.

• Type

• String

• Parent

• bucket

marker

• Description

• Internal bucket tag.

• Type

• String

• Parent

• bucket

owner

• Description

• The user id of the bucket owner.

• Type

• String

• Parent

• bucket

usage

• Description

• Storage usage information.

• Type

• Container

• Parent

• bucket

index

• Description

• Status of bucket index.

• Type

• String

• Parent

• bucket

Special Error Responses

IndexRepairFailed

• Description

• Bucket index repair failed.

• Code

• 409 Conflict

Check Bucket Index

Check the index of an existing bucket. NOTE: to check multipart objectaccounting with check-objects, fix must be set to True.

• caps
• buckets=write

Syntax

GET /{admin}/bucket?index&format=json HTTP/1.1
Host {fqdn}

Request Parameters

bucket

• Description

• The bucket to return info on.

• Type

• String

• Example

• foo_bucket

• Required

• Yes

check-objects

• Description

• Check multipart object accounting.

• Type

• Boolean

• Example

• True [False]

• Required

• No

fix

• Description

• Also fix the bucket index when checking.

• Type

• Boolean

• Example

• False [False]

• Required

• No

Response Entities

index

• Description

• Status of bucket index.

• Type

• String

Special Error Responses

IndexRepairFailed

• Description

• Bucket index repair failed.

• Code

• 409 Conflict

Remove Bucket

Delete an existing bucket.

• caps
• buckets=write

Syntax

DELETE /{admin}/bucket?format=json HTTP/1.1
Host {fqdn}

Request Parameters

bucket

• Description

• The bucket to remove.

• Type

• String

• Example

• foo_bucket

• Required

• Yes

purge-objects

• Description

• Remove a buckets objects before deletion.

• Type

• Boolean

• Example

• True [False]

• Required

• No

Response Entities

None.

Special Error Responses

BucketNotEmpty

• Description

• Attempted to delete non-empty bucket.

• Code

• 409 Conflict

ObjectRemovalFailed

• Description

• Unable to remove objects.

• Code

• 409 Conflict

Unlink Bucket

Unlink a bucket from a specified user. Primarily useful for changingbucket ownership.

• caps
• buckets=write

Syntax

POST /{admin}/bucket?format=json HTTP/1.1
Host {fqdn}

Request Parameters

bucket

• Description

• The bucket to unlink.

• Type

• String

• Example

• foo_bucket

• Required

• Yes

uid

• Description

• The user ID to unlink the bucket from.

• Type

• String

• Example

• foo_user

• Required

• Yes

Response Entities

None.

Special Error Responses

BucketUnlinkFailed

• Description

• Unable to unlink bucket from specified user.

• Code

• 409 Conflict

Link Bucket

Link a bucket to a specified user, unlinking the bucket fromany previous user.

• caps
• buckets=write

Syntax

PUT /{admin}/bucket?format=json HTTP/1.1
Host {fqdn}

Request Parameters

bucket

• Description

• The bucket name to unlink.

• Type

• String

• Example

• foo_bucket

• Required

• Yes

bucket-id

• Description

• The bucket id to unlink.

• Type

• String

• Example

• dev.6607669.420

• Required

• No

uid

• Description

• The user ID to link the bucket to.

• Type

• String

• Example

• foo_user

• Required

• Yes

Response Entities

bucket

• Description

• Container for single bucket information.

• Type

• Container

name

• Description

• The name of the bucket.

• Type

• String

• Parent

• bucket

pool

• Description

• The pool the bucket is stored in.

• Type

• String

• Parent

• bucket

id

• Description

• The unique bucket id.

• Type

• String

• Parent

• bucket

marker

• Description

• Internal bucket tag.

• Type

• String

• Parent

• bucket

owner

• Description

• The user id of the bucket owner.

• Type

• String

• Parent

• bucket

usage

• Description

• Storage usage information.

• Type

• Container

• Parent

• bucket

index

• Description

• Status of bucket index.

• Type

• String

• Parent

• bucket

Special Error Responses

BucketUnlinkFailed

• Description

• Unable to unlink bucket from specified user.

• Code

• 409 Conflict

BucketLinkFailed

• Description

• Unable to link bucket to specified user.

• Code

• 409 Conflict

Remove Object

Remove an existing object. NOTE: Does not require owner to be non-suspended.

• caps
• buckets=write

Syntax

DELETE /{admin}/bucket?object&format=json HTTP/1.1
Host {fqdn}

Request Parameters

bucket

• Description

• The bucket containing the object to be removed.

• Type

• String

• Example

• foo_bucket

• Required

• Yes

object

• Description

• The object to remove.

• Type

• String

• Example

• foo.txt

• Required

• Yes

Response Entities

None.

Special Error Responses

NoSuchObject

• Description

• Specified object does not exist.

• Code

• 404 Not Found

ObjectRemovalFailed

• Description

• Unable to remove objects.

• Code

• 409 Conflict

Get Bucket or Object Policy

Read the policy of an object or bucket.

• caps
• buckets=read

Syntax

GET /{admin}/bucket?policy&format=json HTTP/1.1
Host {fqdn}

Request Parameters

bucket

• Description

• The bucket to read the policy from.

• Type

• String

• Example

• foo_bucket

• Required

• Yes

object

• Description

• The object to read the policy from.

• Type

• String

• Example

• foo.txt

• Required

• No

Response Entities

If successful, returns the object or bucket policy

policy

• Description

• Access control policy.

• Type

• Container

Special Error Responses

IncompleteBody

• Description

• Either bucket was not specified for a bucket policy request or bucketand object were not specified for an object policy request.

• Code

• 400 Bad Request

Add A User Capability

Add an administrative capability to a specified user.

• caps
• users=write

Syntax

PUT /{admin}/user?caps&format=json HTTP/1.1
Host {fqdn}

Request Parameters

uid

• Description

• The user ID to add an administrative capability to.

• Type

• String

• Example

• foo_user

• Required

• Yes

user-caps

• Description

• The administrative capability to add to the user.

• Type

• String

• Example

• usage=read,write;user=write

• Required

• Yes

Response Entities

If successful, the response contains the user’s capabilities.

user

• Description

• A container for the user data information.

• Type

• Container

• Parent

• user

user_id

• Description

• The user id.

• Type

• String

• Parent

• user

caps

• Description

• User capabilities.

• Type

• Container

• Parent

• user

Special Error Responses

InvalidCapability

• Description

• Attempt to grant invalid admin capability.

• Code

• 400 Bad Request

Example Request

PUT /{admin}/user?caps&user-caps=usage=read,write;user=write&format=json HTTP/1.1
Host: {fqdn}
Content-Type: text/plain
Authorization: {your-authorization-token}

Remove A User Capability

Remove an administrative capability from a specified user.

• caps
• users=write

Syntax

DELETE /{admin}/user?caps&format=json HTTP/1.1
Host {fqdn}

Request Parameters

uid

• Description

• The user ID to remove an administrative capability from.

• Type

• String

• Example

• foo_user

• Required

• Yes

user-caps

• Description

• The administrative capabilities to remove from the user.

• Type

• String

• Example

• usage=read, write

• Required

• Yes

Response Entities

If successful, the response contains the user’s capabilities.

user

• Description

• A container for the user data information.

• Type

• Container

• Parent

• user

user_id

• Description

• The user id.

• Type

• String

• Parent

• user

caps

• Description

• User capabilities.

• Type

• Container

• Parent

• user

Special Error Responses

InvalidCapability

• Description

• Attempt to remove an invalid admin capability.

• Code

• 400 Bad Request

NoSuchCap

• Description

• User does not possess specified capability.

• Code

• 404 Not Found

Quotas

The Admin Operations API enables you to set quotas on users and on bucket ownedby users. See Quota Management for additional details. Quotas include themaximum number of objects in a bucket and the maximum storage size in megabytes.

To view quotas, the user must have a users=read capability. To set,modify or disable a quota, the user must have users=write capability.See the Admin Guide for details.

Valid parameters for quotas include:

• Bucket: The bucket option allows you to specify a quota forbuckets owned by a user.

• Maximum Objects: The max-objects setting allows you to specifythe maximum number of objects. A negative value disables this setting.

• Maximum Size: The max-size option allows you to specify a quotafor the maximum number of bytes. The max-size-kb option allows youto specify it in KiB. A negative value disables this setting.

• Quota Type: The quota-type option sets the scope for the quota.The options are bucket and user.

• Enable/Disable Quota: The enabled option specifies whether thequota should be enabled. The value should be either ‘True’ or ‘False’.

Get User Quota

To get a quota, the user must have users capability set with readpermission.

GET /admin/user?quota&uid=<uid>&quota-type=user

Set User Quota

To set a quota, the user must have users capability set with writepermission.

PUT /admin/user?quota&uid=<uid>&quota-type=user

The content must include a JSON representation of the quota settingsas encoded in the corresponding read operation.

Get Bucket Quota

To get a quota, the user must have users capability set with readpermission.

GET /admin/user?quota&uid=<uid>&quota-type=bucket

Set Bucket Quota

To set a quota, the user must have users capability set with writepermission.

PUT /admin/user?quota&uid=<uid>&quota-type=bucket

The content must include a JSON representation of the quota settingsas encoded in the corresponding read operation.

Set Quota for an Individual Bucket

To set a quota, the user must have buckets capability set with writepermission.

PUT /admin/bucket?quota&uid=<uid>&bucket=<bucket-name>&quota

The content must include a JSON representation of the quota settingsas mentioned in Set Bucket Quota section above.

Standard Error Responses

AccessDenied

• Description

• Access denied.

• Code

• 403 Forbidden

InternalError

• Description

• Internal server error.

• Code

• 500 Internal Server Error

NoSuchUser

• Description

• User does not exist.

• Code

• 404 Not Found

NoSuchBucket

• Description

• Bucket does not exist.

• Code

• 404 Not Found

NoSuchKey

• Description

• No such access key.

• Code

• 404 Not Found

Binding libraries

Golang

• IrekFasikhov/go-rgwadmin

• QuentinPerez/go-radosgw

Java

• twonote/radosgw-admin4j

Python

• UMIACS/rgwadmin

• valerytschopp/python-radosgw-admin