5 An admin API request will be done on a URI that starts with the configurable 'admin'
6 resource entry point. Authorization for the admin API duplicates the S3 authorization
7 mechanism. Some operations require that the user holds special administrative capabilities.
8 The response entity type (XML or JSON) may be specified as the 'format' option in the
9 request and defaults to JSON if not specified.
14 Request bandwidth usage information.
16 Note: this feature is disabled by default, can be enabled by setting ``rgw
17 enable usage log = true`` in the appropriate section of ceph.conf. For changes
18 in ceph.conf to take effect, radosgw process restart is needed.
27 GET /{admin}/usage?format=json HTTP/1.1
37 :Description: The user for which the information is requested. If not specified will apply to all users.
39 :Example: ``foo_user``
44 :Description: Date and (optional) time that specifies the start time of the requested data.
46 :Example: ``2012-09-25 16:00:00``
51 :Description: Date and (optional) time that specifies the end time of the requested data (non-inclusive).
53 :Example: ``2012-09-25 16:00:00``
59 :Description: Specifies whether data entries should be returned.
67 :Description: Specifies whether data summary should be returned.
77 If successful, the response contains the requested information.
81 :Description: A container for the usage information.
86 :Description: A container for the usage entries information.
91 :Description: A container for the user data information.
96 :Description: The name of the user that owns the buckets.
101 :Description: The bucket name.
106 :Description: Time lower bound for which data is being specified (rounded to the beginning of the first relevant hour).
111 :Description: The time specified in seconds since 1/1/1970.
116 :Description: A container for stats categories.
121 :Description: A container for stats entry.
126 :Description: Name of request category for which the stats are provided.
131 :Description: Number of bytes sent by the RADOS Gateway.
136 :Description: Number of bytes received by the RADOS Gateway.
141 :Description: Number of operations.
146 :Description: Number of successful operations.
151 :Description: A container for stats summary.
156 :Description: A container for stats summary aggregated total.
159 Special Error Responses
160 ~~~~~~~~~~~~~~~~~~~~~~~
167 Remove usage information. With no dates specified, removes all usage
170 Note: this feature is disabled by default, can be enabled by setting ``rgw
171 enable usage log = true`` in the appropriate section of ceph.conf. For changes
172 in ceph.conf to take effect, radosgw process restart is needed.
181 DELETE /{admin}/usage?format=json HTTP/1.1
191 :Description: The user for which the information is requested. If not specified will apply to all users.
193 :Example: ``foo_user``
198 :Description: Date and (optional) time that specifies the start time of the requested data.
200 :Example: ``2012-09-25 16:00:00``
205 :Description: Date and (optional) time that specifies the end time of the requested data (none inclusive).
207 :Example: ``2012-09-25 16:00:00``
213 :Description: Required when uid is not specified, in order to acknowledge multi user data removal.
215 :Example: True [False]
218 Special Error Responses
219 ~~~~~~~~~~~~~~~~~~~~~~~
226 Get user information.
236 GET /{admin}/user?format=json HTTP/1.1
245 :Description: The user for which the information is requested.
247 :Example: ``foo_user``
254 If successful, the response contains the user information.
258 :Description: A container for the user data information.
263 :Description: The user id.
269 :Description: Display name for the user.
275 :Description: True if the user is suspended.
281 :Description: The maximum number of buckets to be owned by the user.
287 :Description: Subusers associated with this user account.
293 :Description: S3 keys associated with this user account.
299 :Description: Swift keys associated with this user account.
305 :Description: User capabilities.
309 Special Error Responses
310 ~~~~~~~~~~~~~~~~~~~~~~~
317 Create a new user. By default, a S3 key pair will be created automatically
318 and returned in the response. If only one of ``access-key`` or ``secret-key``
319 is provided, the omitted key will be automatically generated. By default, a
320 generated key is added to the keyring without replacing an existing key pair.
321 If ``access-key`` is specified and refers to an existing key owned by the user
322 then it will be modified.
331 PUT /{admin}/user?format=json HTTP/1.1
341 :Description: The user ID to be created.
343 :Example: ``foo_user``
348 :Description: The display name of the user to be created.
350 :Example: ``foo user``
356 :Description: The email address associated with the user.
358 :Example: ``foo@bar.com``
363 :Description: Key type to be generated, options are: swift, s3 (default).
365 :Example: ``s3`` [``s3``]
370 :Description: Specify access key.
372 :Example: ``ABCD0EF12GHIJ2K34LMN``
378 :Description: Specify secret key.
380 :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8``
385 :Description: User capabilities.
387 :Example: ``usage=read, write; users=read``
392 :Description: Generate a new key pair and add to the existing keyring.
394 :Example: True [True]
399 :Description: Specify the maximum number of buckets the user can own.
406 :Description: Specify whether the user should be suspended.
408 :Example: False [False]
414 If successful, the response contains the user information.
418 :Description: A container for the user data information.
423 :Description: The user id.
429 :Description: Display name for the user.
435 :Description: True if the user is suspended.
441 :Description: The maximum number of buckets to be owned by the user.
447 :Description: Subusers associated with this user account.
453 :Description: S3 keys associated with this user account.
459 :Description: Swift keys associated with this user account.
465 :Description: User capabilities.
469 Special Error Responses
470 ~~~~~~~~~~~~~~~~~~~~~~~
474 :Description: Attempt to create existing user.
479 :Description: Invalid access key specified.
480 :Code: 400 Bad Request
484 :Description: Invalid key type specified.
485 :Code: 400 Bad Request
489 :Description: Invalid secret key specified.
490 :Code: 400 Bad Request
494 :Description: Invalid key type specified.
495 :Code: 400 Bad Request
499 :Description: Provided access key exists and belongs to another user.
504 :Description: Provided email address exists.
507 ``InvalidCapability``
509 :Description: Attempt to grant invalid admin capability.
510 :Code: 400 Bad Request
525 POST /{admin}/user?format=json HTTP/1.1
534 :Description: The user ID to be modified.
536 :Example: ``foo_user``
541 :Description: The display name of the user to be modified.
543 :Example: ``foo user``
548 :Description: The email address to be associated with the user.
550 :Example: ``foo@bar.com``
555 :Description: Generate a new key pair and add to the existing keyring.
557 :Example: True [False]
562 :Description: Specify access key.
564 :Example: ``ABCD0EF12GHIJ2K34LMN``
569 :Description: Specify secret key.
571 :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8``
576 :Description: Key type to be generated, options are: swift, s3 (default).
583 :Description: User capabilities.
585 :Example: ``usage=read, write; users=read``
590 :Description: Specify the maximum number of buckets the user can own.
597 :Description: Specify whether the user should be suspended.
599 :Example: False [False]
605 If successful, the response contains the user information.
609 :Description: A container for the user data information.
614 :Description: The user id.
620 :Description: Display name for the user.
627 :Description: True if the user is suspended.
634 :Description: The maximum number of buckets to be owned by the user.
641 :Description: Subusers associated with this user account.
648 :Description: S3 keys associated with this user account.
655 :Description: Swift keys associated with this user account.
662 :Description: User capabilities.
667 Special Error Responses
668 ~~~~~~~~~~~~~~~~~~~~~~~
672 :Description: Invalid access key specified.
673 :Code: 400 Bad Request
677 :Description: Invalid key type specified.
678 :Code: 400 Bad Request
682 :Description: Invalid secret key specified.
683 :Code: 400 Bad Request
687 :Description: Provided access key exists and belongs to another user.
692 :Description: Provided email address exists.
695 ``InvalidCapability``
697 :Description: Attempt to grant invalid admin capability.
698 :Code: 400 Bad Request
703 Remove an existing user.
712 DELETE /{admin}/user?format=json HTTP/1.1
721 :Description: The user ID to be removed.
723 :Example: ``foo_user``
728 :Description: When specified the buckets and objects belonging
729 to the user will also be removed.
739 Special Error Responses
740 ~~~~~~~~~~~~~~~~~~~~~~~
747 Create a new subuser (primarily useful for clients using the Swift API).
748 Note that in general for a subuser to be useful, it must be granted
749 permissions by specifying ``access``. As with user creation if
750 ``subuser`` is specified without ``secret``, then a secret key will
751 be automatically generated.
760 PUT /{admin}/user?subuser&format=json HTTP/1.1
769 :Description: The user ID under which a subuser is to be created.
771 :Example: ``foo_user``
777 :Description: Specify the subuser ID to be created.
779 :Example: ``sub_foo``
784 :Description: Specify secret key.
786 :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8``
791 :Description: Key type to be generated, options are: swift (default), s3.
793 :Example: ``swift`` [``swift``]
798 :Description: Set access permissions for sub-user, should be one
799 of ``read, write, readwrite, full``.
806 :Description: Generate the secret key.
808 :Example: True [False]
814 If successful, the response contains the subuser information.
819 :Description: Subusers associated with the user account.
824 :Description: Subuser id.
826 :Parent: ``subusers``
830 :Description: Subuser access to user account.
832 :Parent: ``subusers``
834 Special Error Responses
835 ~~~~~~~~~~~~~~~~~~~~~~~
839 :Description: Specified subuser exists.
844 :Description: Invalid key type specified.
845 :Code: 400 Bad Request
849 :Description: Invalid secret key specified.
850 :Code: 400 Bad Request
854 :Description: Invalid subuser access specified.
855 :Code: 400 Bad Request
860 Modify an existing subuser
869 POST /{admin}/user?subuser&format=json HTTP/1.1
878 :Description: The user ID under which the subuser is to be modified.
880 :Example: ``foo_user``
885 :Description: The subuser ID to be modified.
887 :Example: ``sub_foo``
892 :Description: Generate a new secret key for the subuser,
893 replacing the existing key.
895 :Example: True [False]
900 :Description: Specify secret key.
902 :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8``
907 :Description: Key type to be generated, options are: swift (default), s3 .
909 :Example: ``swift`` [``swift``]
914 :Description: Set access permissions for sub-user, should be one
915 of ``read, write, readwrite, full``.
924 If successful, the response contains the subuser information.
929 :Description: Subusers associated with the user account.
934 :Description: Subuser id.
936 :Parent: ``subusers``
940 :Description: Subuser access to user account.
942 :Parent: ``subusers``
944 Special Error Responses
945 ~~~~~~~~~~~~~~~~~~~~~~~
949 :Description: Invalid key type specified.
950 :Code: 400 Bad Request
954 :Description: Invalid secret key specified.
955 :Code: 400 Bad Request
959 :Description: Invalid subuser access specified.
960 :Code: 400 Bad Request
965 Remove an existing subuser
974 DELETE /{admin}/user?subuser&format=json HTTP/1.1
983 :Description: The user ID under which the subuser is to be removed.
985 :Example: ``foo_user``
991 :Description: The subuser ID to be removed.
993 :Example: ``sub_foo``
998 :Description: Remove keys belonging to the subuser.
1000 :Example: True [True]
1008 Special Error Responses
1009 ~~~~~~~~~~~~~~~~~~~~~~~
1015 Create a new key. If a ``subuser`` is specified then by default created keys
1016 will be swift type. If only one of ``access-key`` or ``secret-key`` is provided the
1017 committed key will be automatically generated, that is if only ``secret-key`` is
1018 specified then ``access-key`` will be automatically generated. By default, a
1019 generated key is added to the keyring without replacing an existing key pair.
1020 If ``access-key`` is specified and refers to an existing key owned by the user
1021 then it will be modified. The response is a container listing all keys of the same
1022 type as the key created. Note that when creating a swift key, specifying the option
1023 ``access-key`` will have no effect. Additionally, only one swift key may be held by
1024 each user or subuser.
1034 PUT /{admin}/user?key&format=json HTTP/1.1
1043 :Description: The user ID to receive the new key.
1045 :Example: ``foo_user``
1050 :Description: The subuser ID to receive the new key.
1052 :Example: ``sub_foo``
1057 :Description: Key type to be generated, options are: swift, s3 (default).
1059 :Example: ``s3`` [``s3``]
1064 :Description: Specify the access key.
1066 :Example: ``AB01C2D3EF45G6H7IJ8K``
1071 :Description: Specify the secret key.
1073 :Example: ``0ab/CdeFGhij1klmnopqRSTUv1WxyZabcDEFgHij``
1078 :Description: Generate a new key pair and add to the existing keyring.
1080 :Example: True [``True``]
1089 :Description: Keys of type created associated with this user account.
1094 :Description: The user account associated with the key.
1100 :Description: The access key.
1106 :Description: The secret key
1111 Special Error Responses
1112 ~~~~~~~~~~~~~~~~~~~~~~~
1114 ``InvalidAccessKey``
1116 :Description: Invalid access key specified.
1117 :Code: 400 Bad Request
1121 :Description: Invalid key type specified.
1122 :Code: 400 Bad Request
1124 ``InvalidSecretKey``
1126 :Description: Invalid secret key specified.
1127 :Code: 400 Bad Request
1131 :Description: Invalid key type specified.
1132 :Code: 400 Bad Request
1136 :Description: Provided access key exists and belongs to another user.
1142 Remove an existing key.
1151 DELETE /{admin}/user?key&format=json HTTP/1.1
1160 :Description: The S3 access key belonging to the S3 key pair to remove.
1162 :Example: ``AB01C2D3EF45G6H7IJ8K``
1167 :Description: The user to remove the key from.
1169 :Example: ``foo_user``
1174 :Description: The subuser to remove the key from.
1176 :Example: ``sub_foo``
1181 :Description: Key type to be removed, options are: swift, s3.
1182 NOTE: Required to remove swift key.
1187 Special Error Responses
1188 ~~~~~~~~~~~~~~~~~~~~~~~
1200 Get information about a subset of the existing buckets. If ``uid`` is specified
1201 without ``bucket`` then all buckets beloning to the user will be returned. If
1202 ``bucket`` alone is specified, information for that particular bucket will be
1212 GET /{admin}/bucket?format=json HTTP/1.1
1221 :Description: The bucket to return info on.
1223 :Example: ``foo_bucket``
1228 :Description: The user to retrieve bucket information for.
1230 :Example: ``foo_user``
1235 :Description: Return bucket statistics.
1237 :Example: True [False]
1243 If successful the request returns a buckets container containing
1244 the desired bucket information.
1248 :Description: Per bucket information.
1253 :Description: Contains a list of one or more bucket containers.
1258 :Description: Container for single bucket information.
1260 :Parent: ``buckets``
1264 :Description: The name of the bucket.
1270 :Description: The pool the bucket is stored in.
1276 :Description: The unique bucket id.
1282 :Description: Internal bucket tag.
1288 :Description: The user id of the bucket owner.
1294 :Description: Storage usage information.
1300 :Description: Status of bucket index.
1304 Special Error Responses
1305 ~~~~~~~~~~~~~~~~~~~~~~~
1307 ``IndexRepairFailed``
1309 :Description: Bucket index repair failed.
1315 Check the index of an existing bucket. NOTE: to check multipart object
1316 accounting with ``check-objects``, ``fix`` must be set to True.
1318 :caps: buckets=write
1325 GET /{admin}/bucket?index&format=json HTTP/1.1
1334 :Description: The bucket to return info on.
1336 :Example: ``foo_bucket``
1341 :Description: Check multipart object accounting.
1343 :Example: True [False]
1348 :Description: Also fix the bucket index when checking.
1350 :Example: False [False]
1358 :Description: Status of bucket index.
1361 Special Error Responses
1362 ~~~~~~~~~~~~~~~~~~~~~~~
1364 ``IndexRepairFailed``
1366 :Description: Bucket index repair failed.
1372 Delete an existing bucket.
1374 :caps: buckets=write
1381 DELETE /{admin}/bucket?format=json HTTP/1.1
1391 :Description: The bucket to remove.
1393 :Example: ``foo_bucket``
1398 :Description: Remove a buckets objects before deletion.
1400 :Example: True [False]
1408 Special Error Responses
1409 ~~~~~~~~~~~~~~~~~~~~~~~
1413 :Description: Attempted to delete non-empty bucket.
1416 ``ObjectRemovalFailed``
1418 :Description: Unable to remove objects.
1424 Unlink a bucket from a specified user. Primarily useful for changing
1427 :caps: buckets=write
1434 POST /{admin}/bucket?format=json HTTP/1.1
1443 :Description: The bucket to unlink.
1445 :Example: ``foo_bucket``
1450 :Description: The user ID to unlink the bucket from.
1452 :Example: ``foo_user``
1460 Special Error Responses
1461 ~~~~~~~~~~~~~~~~~~~~~~~
1463 ``BucketUnlinkFailed``
1465 :Description: Unable to unlink bucket from specified user.
1471 Link a bucket to a specified user, unlinking the bucket from
1474 :caps: buckets=write
1481 PUT /{admin}/bucket?format=json HTTP/1.1
1490 :Description: The bucket name to unlink.
1492 :Example: ``foo_bucket``
1497 :Description: The bucket id to unlink.
1499 :Example: ``dev.6607669.420``
1504 :Description: The user ID to link the bucket to.
1506 :Example: ``foo_user``
1514 :Description: Container for single bucket information.
1519 :Description: The name of the bucket.
1525 :Description: The pool the bucket is stored in.
1531 :Description: The unique bucket id.
1537 :Description: Internal bucket tag.
1543 :Description: The user id of the bucket owner.
1549 :Description: Storage usage information.
1555 :Description: Status of bucket index.
1559 Special Error Responses
1560 ~~~~~~~~~~~~~~~~~~~~~~~
1562 ``BucketUnlinkFailed``
1564 :Description: Unable to unlink bucket from specified user.
1567 ``BucketLinkFailed``
1569 :Description: Unable to link bucket to specified user.
1575 Remove an existing object. NOTE: Does not require owner to be non-suspended.
1577 :caps: buckets=write
1584 DELETE /{admin}/bucket?object&format=json HTTP/1.1
1592 :Description: The bucket containing the object to be removed.
1594 :Example: ``foo_bucket``
1599 :Description: The object to remove.
1601 :Example: ``foo.txt``
1609 Special Error Responses
1610 ~~~~~~~~~~~~~~~~~~~~~~~
1614 :Description: Specified object does not exist.
1615 :Code: 404 Not Found
1617 ``ObjectRemovalFailed``
1619 :Description: Unable to remove objects.
1624 Get Bucket or Object Policy
1625 ===========================
1627 Read the policy of an object or bucket.
1636 GET /{admin}/bucket?policy&format=json HTTP/1.1
1645 :Description: The bucket to read the policy from.
1647 :Example: ``foo_bucket``
1652 :Description: The object to read the policy from.
1654 :Example: ``foo.txt``
1660 If successful, returns the object or bucket policy
1664 :Description: Access control policy.
1667 Special Error Responses
1668 ~~~~~~~~~~~~~~~~~~~~~~~
1672 :Description: Either bucket was not specified for a bucket policy request or bucket
1673 and object were not specified for an object policy request.
1674 :Code: 400 Bad Request
1676 Add A User Capability
1677 =====================
1679 Add an administrative capability to a specified user.
1688 PUT /{admin}/user?caps&format=json HTTP/1.1
1696 :Description: The user ID to add an administrative capability to.
1698 :Example: ``foo_user``
1703 :Description: The administrative capability to add to the user.
1705 :Example: ``usage=read,write;user=write``
1711 If successful, the response contains the user's capabilities.
1715 :Description: A container for the user data information.
1721 :Description: The user id.
1727 :Description: User capabilities.
1732 Special Error Responses
1733 ~~~~~~~~~~~~~~~~~~~~~~~
1735 ``InvalidCapability``
1737 :Description: Attempt to grant invalid admin capability.
1738 :Code: 400 Bad Request
1745 PUT /{admin}/user?caps&user-caps=usage=read,write;user=write&format=json HTTP/1.1
1747 Content-Type: text/plain
1748 Authorization: {your-authorization-token}
1752 Remove A User Capability
1753 ========================
1755 Remove an administrative capability from a specified user.
1764 DELETE /{admin}/user?caps&format=json HTTP/1.1
1772 :Description: The user ID to remove an administrative capability from.
1774 :Example: ``foo_user``
1779 :Description: The administrative capabilities to remove from the user.
1781 :Example: ``usage=read, write``
1787 If successful, the response contains the user's capabilities.
1791 :Description: A container for the user data information.
1797 :Description: The user id.
1803 :Description: User capabilities.
1808 Special Error Responses
1809 ~~~~~~~~~~~~~~~~~~~~~~~
1811 ``InvalidCapability``
1813 :Description: Attempt to remove an invalid admin capability.
1814 :Code: 400 Bad Request
1818 :Description: User does not possess specified capability.
1819 :Code: 404 Not Found
1825 The Admin Operations API enables you to set quotas on users and on bucket owned
1826 by users. See `Quota Management`_ for additional details. Quotas include the
1827 maximum number of objects in a bucket and the maximum storage size in megabytes.
1829 To view quotas, the user must have a ``users=read`` capability. To set,
1830 modify or disable a quota, the user must have ``users=write`` capability.
1831 See the `Admin Guide`_ for details.
1833 Valid parameters for quotas include:
1835 - **Bucket:** The ``bucket`` option allows you to specify a quota for
1836 buckets owned by a user.
1838 - **Maximum Objects:** The ``max-objects`` setting allows you to specify
1839 the maximum number of objects. A negative value disables this setting.
1841 - **Maximum Size:** The ``max-size`` option allows you to specify a quota
1842 for the maximum number of bytes. A negative value disables this setting.
1844 - **Quota Type:** The ``quota-type`` option sets the scope for the quota.
1845 The options are ``bucket`` and ``user``.
1847 - **Enable/Disable Quota:** The ``enabled`` option specifies whether the
1848 quota should be enabled. The value should be either 'True' or 'False'.
1853 To get a quota, the user must have ``users`` capability set with ``read``
1856 GET /admin/user?quota&uid=<uid>"a-type=user
1862 To set a quota, the user must have ``users`` capability set with ``write``
1865 PUT /admin/user?quota&uid=<uid>"a-type=user
1868 The content must include a JSON representation of the quota settings
1869 as encoded in the corresponding read operation.
1875 To get a quota, the user must have ``users`` capability set with ``read``
1878 GET /admin/user?quota&uid=<uid>"a-type=bucket
1884 To set a quota, the user must have ``users`` capability set with ``write``
1887 PUT /admin/user?quota&uid=<uid>"a-type=bucket
1889 The content must include a JSON representation of the quota settings
1890 as encoded in the corresponding read operation.
1895 Standard Error Responses
1896 ========================
1900 :Description: Access denied.
1901 :Code: 403 Forbidden
1905 :Description: Internal server error.
1906 :Code: 500 Internal Server Error
1910 :Description: User does not exist.
1911 :Code: 404 Not Found
1915 :Description: Bucket does not exist.
1916 :Code: 404 Not Found
1920 :Description: No such access key.
1921 :Code: 404 Not Found
1925 .. _Admin Guide: ../admin
1926 .. _Quota Management: ../admin#quota-management