--- /dev/null
+=============
+ Admin Guide
+=============
+
+Once you have your Ceph Object Storage service up and running, you may
+administer the service with user management, access controls, quotas
+and usage tracking among other features.
+
+
+User Management
+===============
+
+Ceph Object Storage user management refers to users of the Ceph Object Storage
+service (i.e., not the Ceph Object Gateway as a user of the Ceph Storage
+Cluster). You must create a user, access key and secret to enable end users to
+interact with Ceph Object Gateway services.
+
+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.
+
+.. ditaa:: +---------+
+ | User |
+ +----+----+
+ |
+ | +-----------+
+ +-----+ Subuser |
+ +-----------+
+
+You can create, modify, view, suspend and remove users and subusers. In addition
+to user and subuser IDs, you may add a display name and an email address for a
+user. You can specify a key and secret, or generate a key and secret
+automatically. When generating or specifying keys, note that user IDs correspond
+to an S3 key type and subuser IDs correspond to a swift key type. Swift keys
+also have access levels of ``read``, ``write``, ``readwrite`` and ``full``.
+
+
+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}]
+
+For example::
+
+ radosgw-admin user create --uid=johndoe --display-name="John Doe" --email=john@example.com
+
+.. code-block:: javascript
+
+ { "user_id": "johndoe",
+ "rados_uid": 0,
+ "display_name": "John Doe",
+ "email": "john@example.com",
+ "suspended": 0,
+ "subusers": [],
+ "keys": [
+ { "user": "johndoe",
+ "access_key": "QFAMEDSJP5DEKJO0DDXY",
+ "secret_key": "iaSFLDVvDdQt6lkNzHyW4fPLZugBAI1g17LO0+87"}],
+ "swift_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
+ in quotes, regenerating the key and ensuring that it
+ does not have an escape character or specify the key and secret manually.
+
+
+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
+
+.. code-block:: javascript
+
+ { "user_id": "johndoe",
+ "rados_uid": 0,
+ "display_name": "John Doe",
+ "email": "john@example.com",
+ "suspended": 0,
+ "subusers": [
+ { "id": "johndoe:swift",
+ "permissions": "full-control"}],
+ "keys": [
+ { "user": "johndoe",
+ "access_key": "QFAMEDSJP5DEKJO0DDXY",
+ "secret_key": "iaSFLDVvDdQt6lkNzHyW4fPLZugBAI1g17LO0+87"}],
+ "swift_keys": []}
+
+
+Get User Info
+-------------
+
+To get information about a user, you must specify ``user info`` and the user ID
+(``--uid={username}``) . ::
+
+ radosgw-admin user info --uid=johndoe
+
+
+
+Modify User Info
+----------------
+
+To modify information about a user, you must specify the user ID (``--uid={username}``)
+and the attributes you want to modify. Typical modifications are to keys and secrets,
+email addresses, display names and access levels. For example::
+
+ radosgw-admin user modify --uid=johndoe --display-name="John E. Doe"
+
+To modify subuser values, specify ``subuser modify`` and the subuser ID. For example::
+
+ radosgw-admin subuser modify --uid=johndoe:swift --access=full
+
+
+User Enable/Suspend
+-------------------
+
+When you create a user, the user is enabled by default. However, you may suspend
+user privileges and re-enable them at a later time. To suspend a user, specify
+``user suspend`` and the user ID. ::
+
+ radosgw-admin user suspend --uid=johndoe
+
+To re-enable a suspended user, specify ``user enable`` and the user ID. ::
+
+ radosgw-admin user enable --uid=johndoe
+
+.. note:: Disabling the user disables the subuser.
+
+
+Remove a User
+-------------
+
+When you remove a user, the user and subuser are removed from the system.
+However, you may remove just the subuser if you wish. To remove a user (and
+subuser), specify ``user rm`` and the user ID. ::
+
+ radosgw-admin user rm --uid=johndoe
+
+To remove the subuser only, specify ``subuser rm`` and the subuser ID. ::
+
+ radosgw-admin subuser rm --uid=johndoe:swift
+
+
+Options include:
+
+- **Purge Data:** The ``--purge-data`` option purges all data associated
+ to the UID.
+
+- **Purge Keys:** The ``--purge-keys`` option purges all keys associated
+ 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.
+
+
+Create a Key
+------------
+
+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
+
+.. code-block:: javascript
+
+ { "user_id": "johndoe",
+ "rados_uid": 0,
+ "display_name": "John Doe",
+ "email": "john@example.com",
+ "suspended": 0,
+ "subusers": [
+ { "id": "johndoe:swift",
+ "permissions": "full-control"}],
+ "keys": [
+ { "user": "johndoe",
+ "access_key": "QFAMEDSJP5DEKJO0DDXY",
+ "secret_key": "iaSFLDVvDdQt6lkNzHyW4fPLZugBAI1g17LO0+87"}],
+ "swift_keys": [
+ { "user": "johndoe:swift",
+ "secret_key": "E9T2rUZNu2gxUjcwUBO8n\/Ev4KX6\/GprEuH4qhu1"}]}
+
+
+
+Add / Remove Access Keys
+------------------------
+
+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=<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
+
+
+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
+
+
+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.
+
+
+To add administrative capabilities to a user, execute the following::
+
+ radosgw-admin caps add --uid=johndoe --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"``
+
+- **Buckets:** ``--caps="buckets=*"``, ``--caps="buckets=read"``,
+ ``--caps="buckets=write"``, ``--caps="buckets=read, write"``
+
+- **Metadata:** ``--caps="metadata=*"``, ``--caps="metadata=read"``,
+ ``--caps="metadata=write"``, ``--caps="metadata=read, write"``
+
+- **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"``
+
+
+To remove administrative capabilities from a user, execute the following::
+
+ radosgw-admin caps remove --uid=johndoe --caps={caps}
+
+
+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
+storage size in megabytes.
+
+
+- **Bucket:** The ``--bucket`` option allows you to specify a quota for
+ a particular bucket.
+
+- **Maximum Objects:** The ``--max-objects`` setting allows you to specify
+ the maximum number of objects. A negative value disables this setting.
+
+- **Maximum Size:** The ``--max-size`` option allows you to specify a quota
+ 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``.
+
+
+
+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]
+
+A negative value for num objects and / or max size means that the
+specific quota attribute check is disabled.
+
+
+Enable/Disable User Quota
+-------------------------
+
+Once you set a user quota, you may enable it. For example::
+
+ radosgw-admin quota enable --uid=<uid>
+
+You may disable an enabled quota. For example::
+
+ radosgw-admin quota-disable --uid=<uid>
+
+
+Get User 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>
+
+
+Get User Usage Stats
+--------------------
+
+To see how much of the quota a user has consumed, execute the following::
+
+ radosgw-admin user stats --uid=<uid>
+
+
+
+Update Quota Stats
+------------------
+
+Quota stats get updated asynchronously. You can update quota
+statistics for all users and all buckets manually to retrieve
+the latest quota stats. ::
+
+ radosgw-admin user stats --uid=<uid> --sync-stats
+
+
+Reading / Writing Global Quotas
+-------------------------------
+
+You can read and write quota settings in a region map. To get a
+region map, execute the following. ::
+
+ radosgw-admin regionmap get > regionmap.json
+
+To set quota settings for the entire region, simply modify the
+quota settings in the region map. Then, use ``region set`` to
+update the region map. ::
+
+ radosgw-admin region set < regionmap.json
+
+
+.. note:: After updating the region map, you must restart the gateway.
+
+
+Usage
+=====
+
+The Ceph Object Gateway logs usage for each user. You can track
+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).
+
+- **End Date:** The ``--end-date`` option allows you to filter usage up
+ to a particular date (format: yyyy-mm-dd).
+
+- **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).
+
+
+Show Usage
+----------
+
+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
+
+You may also show a summary of usage information for all users by omitting a user ID. ::
+
+ radosgw-admin usage show --show-log-entries=false
+
+
+Trim Usage
+----------
+
+With heavy use, usage logs can begin to take up storage space. You can trim
+usage logs for all users and for specific users. You may also specify date
+ranges for trim operations. ::
+
+ radosgw-admin usage trim --start-date=2010-01-01 --end-date=2010-12-31
+ radosgw-admin usage trim --uid=johndoe
+ radosgw-admin usage trim --uid=johndoe --end-date=2013-12-31
+
+
+.. _radosgw-admin: ../../man/8/radosgw-admin/
+.. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/
projects / ceph.git / commitdiff