-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc: New Admin Guide for Ceph Object Storage.
Signed-off-by: John Wilkins <[email protected]>
- Loading branch information
John Wilkins
committed
May 5, 2014
1 parent
8217600
commit e97b56e
Showing
1 changed file
with
146 additions
and
85 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -20,7 +20,7 @@ There are two user types: | |
| - **User:** The term 'user' reflects a user of the S3 interface. | ||
|
|
||
| - **Subuser:** The term 'subuser' reflects a user of the Swift interface. A subuser | ||
| is associated to a user. | ||
| is associated to a user . | ||
|
|
||
| .. ditaa:: +---------+ | ||
| | User | | ||
|
|
@@ -43,7 +43,7 @@ Create a User | |
|
|
||
| To create a user (S3 interface), execute the following:: | ||
|
|
||
| sudo rados-admin user create --uid={username} --display-name="{display-name}" [--email={email}] | ||
| rados-admin user create --uid={username} --display-name="{display-name}" [--email={email}] | ||
|
|
||
| For example:: | ||
|
|
||
|
|
@@ -52,48 +52,83 @@ For example:: | |
| .. code-block:: javascript | ||
| { "user_id": "johndoe", | ||
| "rados_uid": 0, | ||
| "display_name": "John Doe", | ||
| "email": "[email protected]", | ||
| "suspended": 0, | ||
| "max_buckets": 1000, | ||
| "auid": 0, | ||
| "subusers": [], | ||
| "keys": [ | ||
| { "user": "johndoe", | ||
| "access_key": "QFAMEDSJP5DEKJO0DDXY", | ||
| "secret_key": "iaSFLDVvDdQt6lkNzHyW4fPLZugBAI1g17LO0+87"}], | ||
| "swift_keys": []} | ||
| { "user": "johndoe", | ||
| "access_key": "11BS02LGFB6AL6H1ADMW", | ||
| "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}], | ||
| "swift_keys": [], | ||
| "caps": [], | ||
| "op_mask": "read, write, delete", | ||
| "default_placement": "", | ||
| "placement_tags": [], | ||
| "bucket_quota": { "enabled": false, | ||
| "max_size_kb": -1, | ||
| "max_objects": -1}, | ||
| "user_quota": { "enabled": false, | ||
| "max_size_kb": -1, | ||
| "max_objects": -1}, | ||
| "temp_url_keys": []} | ||
| Creating a user also creates an ``access_key`` and ``secret_key`` entry for use | ||
| with any S3 API-compatible client. | ||
|
|
||
| .. important:: Check the key output. Sometimes ``radosgw-admin`` | ||
| generates a key with an escape (``\``) character, and some clients | ||
| do not know how to handle escape characters. Remedies include | ||
| removing the escape character (``\``), encapsulating the string | ||
| generates a JSON escape (``\``) character, and some clients | ||
| do not know how to handle JSON escape characters. Remedies include | ||
| removing the JSON escape character (``\``), encapsulating the string | ||
| in quotes, regenerating the key and ensuring that it | ||
| does not have an escape character or specify the key and secret manually. | ||
| does not have a JSON escape character or specify the key and secret | ||
| manually. | ||
|
|
||
|
|
||
| Create a Subuser | ||
| ---------------- | ||
|
|
||
| To create a subuser (Swift interface) for the user, you must specify the user ID | ||
| (``--uid={username}``), a subuser ID and the access level for the subuser. :: | ||
|
|
||
| sudo radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full | ||
| radosgw-admin subuser create --uid={uid} --subuser={uid} --access=[ read | write | readwrite | full ] | ||
|
|
||
| For example:: | ||
|
|
||
| radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full | ||
|
|
||
|
|
||
| .. note:: ``full`` is not ``readwrite``, as it also includes the access control policy. | ||
|
|
||
| .. code-block:: javascript | ||
| { "user_id": "johndoe", | ||
| "rados_uid": 0, | ||
| "display_name": "John Doe", | ||
| "email": "[email protected]", | ||
| "suspended": 0, | ||
| "max_buckets": 1000, | ||
| "auid": 0, | ||
| "subusers": [ | ||
| { "id": "johndoe:swift", | ||
| "permissions": "full-control"}], | ||
| { "id": "johndoe:swift", | ||
| "permissions": "full-control"}], | ||
| "keys": [ | ||
| { "user": "johndoe", | ||
| "access_key": "QFAMEDSJP5DEKJO0DDXY", | ||
| "secret_key": "iaSFLDVvDdQt6lkNzHyW4fPLZugBAI1g17LO0+87"}], | ||
| "swift_keys": []} | ||
| { "user": "johndoe", | ||
| "access_key": "11BS02LGFB6AL6H1ADMW", | ||
| "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}], | ||
| "swift_keys": [], | ||
| "caps": [], | ||
| "op_mask": "read, write, delete", | ||
| "default_placement": "", | ||
| "placement_tags": [], | ||
| "bucket_quota": { "enabled": false, | ||
| "max_size_kb": -1, | ||
| "max_objects": -1}, | ||
| "user_quota": { "enabled": false, | ||
| "max_size_kb": -1, | ||
| "max_objects": -1}, | ||
| "temp_url_keys": []} | ||
| Get User Info | ||
|
|
@@ -159,8 +194,21 @@ Options include: | |
| to the UID. | ||
|
|
||
|
|
||
| .. todo:: Need clarification on syntax. Does --purge-data only purge data, or | ||
| does it purge data and the user? Same with --purge-keys. | ||
| Remove a Subuser | ||
| ---------------- | ||
|
|
||
| When you remove a sub user, you are removing access to the Swift interface. | ||
| The user will remain in the system. The Ceph Object Gateway To remove the subuser, specify | ||
| ``subuser rm`` and the subuser ID. :: | ||
|
|
||
| radosgw-admin subuser rm --uid=johndoe:swift | ||
|
|
||
|
|
||
|
|
||
| Options include: | ||
|
|
||
| - **Purge Keys:** The ``--purge-keys`` option purges all keys associated | ||
| to the UID. | ||
|
|
||
|
|
||
| Create a Key | ||
|
|
@@ -170,7 +218,7 @@ To create a key for a user, you must specify ``key create``. For a user, specify | |
| the user ID and the ``s3` key type. To create a key for subuser, you must | ||
| specify the subuser ID and the ``swift`` keytype. For example:: | ||
|
|
||
| sudo radosgw-admin key create --subuser=johndoe:swift --key-type=swift --gen-secret | ||
| radosgw-admin key create --subuser=johndoe:swift --key-type=swift --gen-secret | ||
|
|
||
| .. code-block:: javascript | ||
|
|
@@ -199,67 +247,48 @@ Users and subusers must have access keys to use the S3 and Swift | |
| interfaces. When you create a user or subuser and you do not specify | ||
| an access key and secret, the key and secret get generated automatically. | ||
| You may create a key and either specify or generate the access key and/or | ||
| secret. You may also remove an access key and secret. | ||
| secret. You may also remove an access key and secret. Options include: | ||
|
|
||
|
|
||
| --secret=<key> specify secret key | ||
| --gen-access-key generate random access key (for S3) | ||
| --gen-secret generate random secret key | ||
| --key-type=<type> key type, options are: swift, s3 | ||
| - ``--secret=<key>`` specifies a secret key (e.g,. manually generated). | ||
| - ``--gen-access-key`` generates random access key (for S3 user by default). | ||
| - ``--gen-secret`` generates a random secret key. | ||
| - ``--key-type=<type>`` specifies a key type. The options are: swift, s3 | ||
|
|
||
|
|
||
| To add a key, specify the user. | ||
|
|
||
| radosgw-admin key create --uid=johndoe --gen-key --gen-secret | ||
|
|
||
|
|
||
| You may also specify a key and a secret. | ||
|
|
||
| radosgw-admin key create --uid=johndoe | ||
| radosgw-admin key create --uid=johndoe --key-type=s3 --gen-key --gen-secret | ||
|
|
||
| You may also specify a key and a secret. | ||
|
|
||
| To remove an access key, | ||
|
|
||
| radosgw-admin key rm --uid=johndoe | ||
|
|
||
|
|
||
| key create create access key | ||
| key rm remove access key | ||
|
|
||
|
|
||
| .. todo:: Need clarification on syntax. | ||
|
|
||
|
|
||
| Add / Remove Admin Capabilties | ||
| ------------------------------ | ||
|
|
||
| The Ceph Storage Cluster provides an administrative API that enables | ||
| users to execute administrative functions via the REST API. By default, | ||
| users do NOT have access to this API. To enable a user to exercise | ||
| administrative functionality, provide the user with administrative capabilities. | ||
| Add / Remove Admin Capabilities | ||
| ------------------------------- | ||
|
|
||
| The Ceph Storage Cluster provides an administrative API that enables users to | ||
| execute administrative functions via the REST API. By default, users do NOT have | ||
| access to this API. To enable a user to exercise administrative functionality, | ||
| provide the user with administrative capabilities. | ||
|
|
||
| To add administrative capabilities to a user, execute the following:: | ||
|
|
||
| radosgw-admin caps add --uid=johndoe --caps={caps} | ||
| radosgw-admin caps add --uid={uid} --caps={caps} | ||
|
|
||
| You can add read, write or all capabilities to users, buckets, metadata and | ||
| usage (utilization): | ||
|
|
||
| - **Users:** ``--caps="users=*"``, ``--caps="users=read"``, | ||
| ``--caps="users=write"``, ``--caps="users=read, write"`` | ||
| You can add read, write or all capabilities to users, buckets, metadata and | ||
| usage (utilization). For example:: | ||
|
|
||
| - **Buckets:** ``--caps="buckets=*"``, ``--caps="buckets=read"``, | ||
| ``--caps="buckets=write"``, ``--caps="buckets=read, write"`` | ||
| --caps="[users|buckets|metadata|usage|zone]=[*|read|write|read, write]" | ||
|
|
||
| - **Metadata:** ``--caps="metadata=*"``, ``--caps="metadata=read"``, | ||
| ``--caps="metadata=write"``, ``--caps="metadata=read, write"`` | ||
| For example:: | ||
|
|
||
| - **Usage:** ``--caps="usage=*"``, ``--caps="usage=read"``, | ||
| ``--caps="usage=write"``, ``--caps="usage=read, write"`` | ||
|
|
||
| - **Zone:** ``--caps="zone=*"``, ``--caps="zone=read"``, | ||
| ``--caps="zone=write"``, ``--caps="zone=read, write"`` | ||
| radosgw-admin caps add --uid=johndoe --caps="users=*" | ||
|
|
||
|
|
||
| To remove administrative capabilities from a user, execute the following:: | ||
|
|
@@ -270,13 +299,12 @@ To remove administrative capabilities from a user, execute the following:: | |
| Quota Management | ||
| ================ | ||
|
|
||
| The Ceph Object Gateway enables you to set quotas on users and buckets. | ||
| Quotas include the maximum number of objects in a bucket and the maximum | ||
| The Ceph Object Gateway enables you to set quotas on users and buckets owned by | ||
| users. Quotas include the maximum number of objects in a bucket and the maximum | ||
| storage size in megabytes. | ||
|
|
||
|
|
||
| - **Bucket:** The ``--bucket`` option allows you to specify a quota for | ||
| a particular bucket. | ||
| buckets the user owns. | ||
|
|
||
| - **Maximum Objects:** The ``--max-objects`` setting allows you to specify | ||
| the maximum number of objects. A negative value disables this setting. | ||
|
|
@@ -285,8 +313,8 @@ storage size in megabytes. | |
| for the maximum number of bytes. A negative value disables this setting. | ||
|
|
||
| - **Quota Scope:** The ``--quota-scope`` option sets the scope for the quota. | ||
| The options are ``bucket`` and ``user``. | ||
|
|
||
| The options are ``bucket`` and ``user``. Bucket quotas apply to buckets a | ||
| user owns. User quotas apply to a user. | ||
|
|
||
|
|
||
| Set User Quota | ||
|
|
@@ -295,7 +323,12 @@ Set User Quota | |
| Before you enable a quota, you must first set the quota parameters. | ||
| For example:: | ||
|
|
||
| radosgw-admin quota set --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size] | ||
| radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>] | ||
|
|
||
| For example:: | ||
|
|
||
| radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024 | ||
|
|
||
|
|
||
| A negative value for num objects and / or max size means that the | ||
| specific quota attribute check is disabled. | ||
|
|
@@ -306,30 +339,45 @@ Enable/Disable User Quota | |
|
|
||
| Once you set a user quota, you may enable it. For example:: | ||
|
|
||
| radosgw-admin quota enable --uid=<uid> | ||
| radosgw-admin quota enable --quota-scope=user --uid=<uid> | ||
|
|
||
| You may disable an enabled quota. For example:: | ||
| You may disable an enabled user quota. For example:: | ||
|
|
||
| radosgw-admin quota-disable --uid=<uid> | ||
| radosgw-admin quota-disable --quota-scope=user --uid=<uid> | ||
|
|
||
|
|
||
| Get User Quota Settings | ||
| ----------------------- | ||
| Set Bucket Quota | ||
| ---------------- | ||
|
|
||
| You may access each user's quota settings via the user information | ||
| API. To read user quota setting information with the CLI interface, | ||
| execute the following:: | ||
| Bucket quotas apply to the buckets owned by the specified ``uid``. They are | ||
| independent of the user. :: | ||
|
|
||
| radosgw-admin user info --uid=<uid> | ||
| radosgw-admin quota set --uid=<uid> --bucket-scope=bucket [--max-objects=<num objects>] [--max-size=<max size] | ||
|
|
||
| A negative value for num objects and / or max size means that the | ||
| specific quota attribute check is disabled. | ||
|
|
||
| Get User Usage Stats | ||
| -------------------- | ||
|
|
||
| To see how much of the quota a user has consumed, execute the following:: | ||
| Enable/Disable Bucket Quota | ||
| --------------------------- | ||
|
|
||
| radosgw-admin user stats --uid=<uid> | ||
| Once you set a bucket quota, you may enable it. For example:: | ||
|
|
||
| radosgw-admin quota enable --quota-scope=bucket --uid=<uid> | ||
|
|
||
| You may disable an enabled bucket quota. For example:: | ||
|
|
||
| radosgw-admin quota-disable --quota-scope=bucket --uid=<uid> | ||
|
|
||
|
|
||
| Get Quota Settings | ||
| ------------------ | ||
|
|
||
| You may access each user's quota settings via the user information | ||
| API. To read user quota setting information with the CLI interface, | ||
| execute the following:: | ||
|
|
||
| radosgw-admin user info --uid=<uid> | ||
|
|
||
|
|
||
| Update Quota Stats | ||
|
|
@@ -342,6 +390,17 @@ the latest quota stats. :: | |
| radosgw-admin user stats --uid=<uid> --sync-stats | ||
|
|
||
|
|
||
| Get User Usage Stats | ||
| -------------------- | ||
|
|
||
| To see how much of the quota a user has consumed, execute the following:: | ||
|
|
||
| radosgw-admin user stats --uid=<uid> | ||
|
|
||
| .. note:: You should execute ``radosgw-admin user stats`` with the | ||
| ``--sync-stats`` option to receive the latest data. | ||
|
|
||
|
|
||
| Reading / Writing Global Quotas | ||
| ------------------------------- | ||
|
|
||
|
|
@@ -356,7 +415,6 @@ update the region map. :: | |
|
|
||
| radosgw-admin region set < regionmap.json | ||
|
|
||
|
|
||
| .. note:: After updating the region map, you must restart the gateway. | ||
|
|
||
|
|
||
|
|
@@ -369,14 +427,17 @@ user usage within date ranges too. | |
| Options include: | ||
|
|
||
| - **Start Date:** The ``--start-date`` option allows you to filter usage | ||
| stats from a particular start date (format: yyyy-mm-dd). | ||
| stats from a particular start date (**format:** ``yyyy-mm-dd[HH:MM:SS]``). | ||
|
|
||
| - **End Date:** The ``--end-date`` option allows you to filter usage up | ||
| to a particular date (format: yyyy-mm-dd). | ||
| to a particular date (**format:** ``yyyy-mm-dd[HH:MM:SS]``). | ||
|
|
||
| - **Log Entries:** The ``--show-log-entries`` option allows you to specify | ||
| whether or not to include log entries with the usage stats | ||
| (options: true | false). | ||
| (options: ``true`` | ``false``). | ||
|
|
||
| .. note:: You may specify time with minutes and seconds, but it is stored | ||
| with 1 hour resolution. | ||
|
|
||
|
|
||
| Show Usage | ||
|
|
@@ -386,7 +447,7 @@ To show usage statistics, specify the ``usage show``. To show usage for a | |
| particular user, you must specify a user ID. You may also specify a start date, | ||
| end date, and whether or not to show log entries.:: | ||
|
|
||
| radosgw-admin usage show --uid=johnny --start-date=2012-03-01 --end-date=2012-04-01 | ||
| radosgw-admin usage show --uid=johndoe --start-date=2012-03-01 --end-date=2012-04-01 | ||
|
|
||
| You may also show a summary of usage information for all users by omitting a user ID. :: | ||
|
|
||
|
|
||