+++ /dev/null
-==================
- 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 authorization
-mechanism. 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 the
-request and defaults to JSON if not specified.
-
-Get Usage
-=========
-
-Request bandwidth usage information.
-
-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 [False]
-:Required: No
-
-
-``show-summary``
-
-:Description: Specifies whether data summary should be returned.
-:Type: Boolean
-:Example: True [False]
-: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 usage
-information.
-
-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. If no user is specified returns the list of all users along with suspension
-information.
-
-
-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: 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
-~~~~~~~~~~~~~~~~~~~~~~~
-
-None.
-
-Create User
-===========
-
-Create a new user. By Default, a S3 key pair will be created automatically
-and returned in the response. If only one of ``access-key`` or ``secret-key``
-is provided, the omitted key will be automatically generated. By default, a
-generated 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 user
-then it will be modified.
-
-
-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
-
-``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; user=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
-
-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
-~~~~~~~~~~~~~~~~~~~~~~~
-
-``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
-
-``InvalidCap``
-
-:Description: Attempt to grant invalid admin capability.
-:Code: 400 Bad Request
-
-
-Modify User
-===========
-
-Modify a user.
-
-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; user=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
-
-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
-
-``InvalidCap``
-
-:Description: Attempt to grant invalid admin capability.
-:Code: 400 Bad Request
-
-Remove User
-===========
-
-Remove an existing user.
-
-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 belonging
- to 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 either ``gen-subuser`` or ``subuser`` is required for a valid
-request. Note that in general for a subuser to be useful, it must be
-granted permissions by specifying ``access``. As with user creation if
-``subuser`` is specified without ``secret``, then a secret key will
-be automatically generated.
-
-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: 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 (default), s3.
-:Type: String
-:Example: ``swift`` [``swift``]
-:Required: No
-
-``access``
-
-:Description: Set access permissions for sub-user, should be one
- of ``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 acount.
-: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
-
-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 one
- of ``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 acount.
-: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
-
-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 keys
-will be swift type. If only one of ``access-key`` or ``secret-key`` is provided the
-committed key will be automatically generated, that is if only ``secret-key`` is
-specified then ``access-key`` will be automatically generated. By default, a
-generated 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 user
-then it will be modified. The response is a container listing all keys of the same
-type as the key created. Note that when creating a swift key, specifying the option
-``access-key`` will have no effect. Additionally, only one swift key may be held by
-each user or subuser.
-
-
-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.
-
-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 specified
-without ``bucket`` then all buckets beloning to the user will be returned. If
-``bucket`` alone is specified, information for that particular bucket will be
-retrieved.
-
-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 containing
-the 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 object
-accounting with ``check-objects``, ``fix`` must be set to True.
-
-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.
-
-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 changing
-bucket ownership.
-
-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 from
-any previous user.
-
-Syntax
-~~~~~~
-
-::
-
- PUT /{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 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.
-
-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.
-
-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 bucket
- and 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.
-
-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``
-: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
-~~~~~~~~~~~~~~~~~~~~~~~
-
-``InvalidCap``
-
-:Description: Attempt to grant invalid admin capability.
-:Code: 400 Bad Request
-
-Example Request
-~~~~~~~~~~~~~~~
-
-::
-
- PUT /{admin}/user?caps&format=json HTTP/1.1
- Host: {fqdn}
- Content-Type: text/plain
- Authorization: {your-authorization-token}
-
- usage=read
-
-
-Remove A User Capability
-========================
-
-Remove an administrative capability from a specified user.
-
-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
-~~~~~~~~~~~~~~~~~~~~~~~
-
-``InvalidCap``
-
-:Description: Attempt to remove an invalid admin capability.
-:Code: 400 Bad Request
-
-``NoSuchCap``
-
-:Description: User does not possess specified capability.
-:Code: 404 Not Found
-
-Special Error Responses
-~~~~~~~~~~~~~~~~~~~~~~~
-
-None.
-
-
-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
--- /dev/null
+==================
+ 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 authorization
+mechanism. 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 the
+request and defaults to JSON if not specified.
+
+Get Usage
+=========
+
+Request bandwidth usage information.
+
+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 [False]
+:Required: No
+
+
+``show-summary``
+
+:Description: Specifies whether data summary should be returned.
+:Type: Boolean
+:Example: True [False]
+: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 usage
+information.
+
+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. If no user is specified returns the list of all users along with suspension
+information.
+
+
+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: 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
+~~~~~~~~~~~~~~~~~~~~~~~
+
+None.
+
+Create User
+===========
+
+Create a new user. By Default, a S3 key pair will be created automatically
+and returned in the response. If only one of ``access-key`` or ``secret-key``
+is provided, the omitted key will be automatically generated. By default, a
+generated 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 user
+then it will be modified.
+
+
+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
+
+``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; user=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
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``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
+
+``InvalidCap``
+
+:Description: Attempt to grant invalid admin capability.
+:Code: 400 Bad Request
+
+
+Modify User
+===========
+
+Modify a user.
+
+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; user=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
+
+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
+
+``InvalidCap``
+
+:Description: Attempt to grant invalid admin capability.
+:Code: 400 Bad Request
+
+Remove User
+===========
+
+Remove an existing user.
+
+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 belonging
+ to 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 either ``gen-subuser`` or ``subuser`` is required for a valid
+request. Note that in general for a subuser to be useful, it must be
+granted permissions by specifying ``access``. As with user creation if
+``subuser`` is specified without ``secret``, then a secret key will
+be automatically generated.
+
+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: 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 (default), s3.
+:Type: String
+:Example: ``swift`` [``swift``]
+:Required: No
+
+``access``
+
+:Description: Set access permissions for sub-user, should be one
+ of ``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 acount.
+: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
+
+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 one
+ of ``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 acount.
+: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
+
+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 keys
+will be swift type. If only one of ``access-key`` or ``secret-key`` is provided the
+committed key will be automatically generated, that is if only ``secret-key`` is
+specified then ``access-key`` will be automatically generated. By default, a
+generated 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 user
+then it will be modified. The response is a container listing all keys of the same
+type as the key created. Note that when creating a swift key, specifying the option
+``access-key`` will have no effect. Additionally, only one swift key may be held by
+each user or subuser.
+
+
+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.
+
+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 specified
+without ``bucket`` then all buckets beloning to the user will be returned. If
+``bucket`` alone is specified, information for that particular bucket will be
+retrieved.
+
+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 containing
+the 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 object
+accounting with ``check-objects``, ``fix`` must be set to True.
+
+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.
+
+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 changing
+bucket ownership.
+
+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 from
+any previous user.
+
+Syntax
+~~~~~~
+
+::
+
+ PUT /{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 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.
+
+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.
+
+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 bucket
+ and 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.
+
+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``
+: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
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``InvalidCap``
+
+:Description: Attempt to grant invalid admin capability.
+:Code: 400 Bad Request
+
+Example Request
+~~~~~~~~~~~~~~~
+
+::
+
+ PUT /{admin}/user?caps&format=json HTTP/1.1
+ Host: {fqdn}
+ Content-Type: text/plain
+ Authorization: {your-authorization-token}
+
+ usage=read
+
+
+Remove A User Capability
+========================
+
+Remove an administrative capability from a specified user.
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``InvalidCap``
+
+:Description: Attempt to remove an invalid admin capability.
+:Code: 400 Bad Request
+
+``NoSuchCap``
+
+:Description: User does not possess specified capability.
+:Code: 404 Not Found
+
+Special Error Responses
+~~~~~~~~~~~~~~~~~~~~~~~
+
+None.
+
+
+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
Purging Temp Data <purge-temp>
S3 API <s3>
Swift API <swift>
- Admin API <admin/index>
+ Admin Ops API <adminops>
troubleshooting
Manpage radosgw <../../man/8/radosgw>
Manpage radosgw-admin <../../man/8/radosgw-admin>
projects / ceph.git / commitdiff