From: John Wilkins Date: Mon, 5 May 2014 19:33:30 +0000 (-0700) Subject: doc: New Admin Guide for Ceph Object Storage. X-Git-Tag: v0.81~70^2~3 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=e97b56eb3aef14acefb656b1cc8e3b429fac54db;p=ceph.git doc: New Admin Guide for Ceph Object Storage. Signed-off-by: John Wilkins --- diff --git a/doc/radosgw/admin.rst b/doc/radosgw/admin.rst index e300b99973f1..3d4bf8cc3ad5 100644 --- a/doc/radosgw/admin.rst +++ b/doc/radosgw/admin.rst @@ -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": "john@example.com", "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": "john@example.com", "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= specify secret key - --gen-access-key generate random access key (for S3) - --gen-secret generate random secret key - --key-type= key type, options are: swift, s3 +- ``--secret=`` 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=`` 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= [--max-objects=] [--max-size= [--max-objects=] [--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= + radosgw-admin quota enable --quota-scope=user --uid= -You may disable an enabled quota. For example:: +You may disable an enabled user quota. For example:: - radosgw-admin quota-disable --uid= + radosgw-admin quota-disable --quota-scope=user --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= + radosgw-admin quota set --uid= --bucket-scope=bucket [--max-objects=] [--max-size= +Once you set a bucket quota, you may enable it. For example:: + radosgw-admin quota enable --quota-scope=bucket --uid= + +You may disable an enabled bucket quota. For example:: + + radosgw-admin quota-disable --quota-scope=bucket --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= Update Quota Stats @@ -342,6 +390,17 @@ the latest quota stats. :: radosgw-admin user stats --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= + +.. 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. ::