5 Once you have your Ceph Object Storage service up and running, you may
6 administer the service with user management, access controls, quotas
7 and usage tracking among other features.
13 Ceph Object Storage user management refers to users of the Ceph Object Storage
14 service (i.e., not the Ceph Object Gateway as a user of the Ceph Storage
15 Cluster). You must create a user, access key and secret to enable end users to
16 interact with Ceph Object Gateway services.
18 There are two user types:
20 - **User:** The term 'user' reflects a user of the S3 interface.
22 - **Subuser:** The term 'subuser' reflects a user of the Swift interface. A subuser
23 is associated to a user .
25 .. ditaa:: +---------+
33 You can create, modify, view, suspend and remove users and subusers. In addition
34 to user and subuser IDs, you may add a display name and an email address for a
35 user. You can specify a key and secret, or generate a key and secret
36 automatically. When generating or specifying keys, note that user IDs correspond
37 to an S3 key type and subuser IDs correspond to a swift key type. Swift keys
38 also have access levels of ``read``, ``write``, ``readwrite`` and ``full``.
44 To create a user (S3 interface), execute the following::
46 radosgw-admin user create --uid={username} --display-name="{display-name}" [--email={email}]
50 radosgw-admin user create --uid=johndoe --display-name="John Doe" --email=john@example.com
52 .. code-block:: javascript
54 { "user_id": "johndoe",
55 "display_name": "John Doe",
56 "email": "john@example.com",
62 "access_key": "11BS02LGFB6AL6H1ADMW",
63 "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}],
66 "op_mask": "read, write, delete",
67 "default_placement": "",
69 "bucket_quota": { "enabled": false,
72 "user_quota": { "enabled": false,
77 Creating a user also creates an ``access_key`` and ``secret_key`` entry for use
78 with any S3 API-compatible client.
80 .. important:: Check the key output. Sometimes ``radosgw-admin``
81 generates a JSON escape (``\``) character, and some clients
82 do not know how to handle JSON escape characters. Remedies include
83 removing the JSON escape character (``\``), encapsulating the string
84 in quotes, regenerating the key and ensuring that it
85 does not have a JSON escape character or specify the key and secret
92 To create a subuser (Swift interface) for the user, you must specify the user ID
93 (``--uid={username}``), a subuser ID and the access level for the subuser. ::
95 radosgw-admin subuser create --uid={uid} --subuser={uid} --access=[ read | write | readwrite | full ]
99 radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full
102 .. note:: ``full`` is not ``readwrite``, as it also includes the access control policy.
104 .. code-block:: javascript
106 { "user_id": "johndoe",
107 "display_name": "John Doe",
108 "email": "john@example.com",
112 { "id": "johndoe:swift",
113 "permissions": "full-control"}],
116 "access_key": "11BS02LGFB6AL6H1ADMW",
117 "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}],
120 "op_mask": "read, write, delete",
121 "default_placement": "",
122 "placement_tags": [],
123 "bucket_quota": { "enabled": false,
126 "user_quota": { "enabled": false,
135 To get information about a user, you must specify ``user info`` and the user ID
136 (``--uid={username}``) . ::
138 radosgw-admin user info --uid=johndoe
145 To modify information about a user, you must specify the user ID (``--uid={username}``)
146 and the attributes you want to modify. Typical modifications are to keys and secrets,
147 email addresses, display names and access levels. For example::
149 radosgw-admin user modify --uid=johndoe --display-name="John E. Doe"
151 To modify subuser values, specify ``subuser modify`` and the subuser ID. For example::
153 radosgw-admin subuser modify --subuser=johndoe:swift --access=full
159 When you create a user, the user is enabled by default. However, you may suspend
160 user privileges and re-enable them at a later time. To suspend a user, specify
161 ``user suspend`` and the user ID. ::
163 radosgw-admin user suspend --uid=johndoe
165 To re-enable a suspended user, specify ``user enable`` and the user ID. ::
167 radosgw-admin user enable --uid=johndoe
169 .. note:: Disabling the user disables the subuser.
175 When you remove a user, the user and subuser are removed from the system.
176 However, you may remove just the subuser if you wish. To remove a user (and
177 subuser), specify ``user rm`` and the user ID. ::
179 radosgw-admin user rm --uid=johndoe
181 To remove the subuser only, specify ``subuser rm`` and the subuser ID. ::
183 radosgw-admin subuser rm --subuser=johndoe:swift
188 - **Purge Data:** The ``--purge-data`` option purges all data associated
191 - **Purge Keys:** The ``--purge-keys`` option purges all keys associated
198 When you remove a sub user, you are removing access to the Swift interface.
199 The user will remain in the system. To remove the subuser, specify
200 ``subuser rm`` and the subuser ID. ::
202 radosgw-admin subuser rm --subuser=johndoe:swift
208 - **Purge Keys:** The ``--purge-keys`` option purges all keys associated
213 ------------------------
215 Both users and subusers require the key to access the S3 or Swift interface. To
216 use S3, the user needs a key pair which is composed of an access key and a
217 secret key. On the other hand, to use Swift, the user typically needs a secret
218 key (password), and use it together with the associated user ID. You may create
219 a key and either specify or generate the access key and/or secret key. You may
220 also remove a key. Options include:
222 - ``--key-type=<type>`` specifies the key type. The options are: s3, swift
223 - ``--access-key=<key>`` manually specifies an S3 access key.
224 - ``--secret-key=<key>`` manually specifies a S3 secret key or a Swift secret key.
225 - ``--gen-access-key`` automatically generates a random S3 access key.
226 - ``--gen-secret`` automatically generates a random S3 secret key or a random Swift secret key.
228 An example how to add a specified S3 key pair for a user. ::
230 radosgw-admin key create --uid=foo --key-type=s3 --access-key fooAccessKey --secret-key fooSecretKey
232 .. code-block:: javascript
236 "display_name": "foo",
237 "email": "foo@example.com",
241 "access_key": "fooAccessKey",
242 "secret_key": "fooSecretKey"}],
245 Note that you may create multiple S3 key pairs for a user.
247 To attach a specified swift secret key for a subuser. ::
249 radosgw-admin key create --subuser=foo:bar --key-type=swift --secret-key barSecret
251 .. code-block:: javascript
255 "display_name": "foo",
256 "email": "foo@example.com",
260 "permissions": "full-control"}],
263 "secret_key": "asfghjghghmgm"}]}
265 Note that a subuser can have only one swift secret key.
267 Subusers can also be used with S3 APIs if the subuser is associated with a S3 key pair. ::
269 radosgw-admin key create --subuser=foo:bar --key-type=s3 --access-key barAccessKey --secret-key barSecretKey
271 .. code-block:: javascript
275 "display_name": "foo",
276 "email": "foo@example.com",
280 "permissions": "full-control"}],
283 "access_key": "barAccessKey",
284 "secret_key": "barSecretKey"}],
288 To remove a S3 key pair, specify the access key. ::
290 radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey
292 To remove the swift secret key. ::
294 radosgw-admin key rm -subuser=foo:bar --key-type=swift
297 Add / Remove Admin Capabilities
298 -------------------------------
300 The Ceph Storage Cluster provides an administrative API that enables users to
301 execute administrative functions via the REST API. By default, users do NOT have
302 access to this API. To enable a user to exercise administrative functionality,
303 provide the user with administrative capabilities.
305 To add administrative capabilities to a user, execute the following::
307 radosgw-admin caps add --uid={uid} --caps={caps}
310 You can add read, write or all capabilities to users, buckets, metadata and
311 usage (utilization). For example::
313 --caps="[users|buckets|metadata|usage|zone]=[*|read|write|read, write]"
317 radosgw-admin caps add --uid=johndoe --caps="users=*;buckets=*"
320 To remove administrative capabilities from a user, execute the following::
322 radosgw-admin caps rm --uid=johndoe --caps={caps}
328 The Ceph Object Gateway enables you to set quotas on users and buckets owned by
329 users. Quotas include the maximum number of objects in a bucket and the maximum
330 storage size a bucket can hold.
332 - **Bucket:** The ``--bucket`` option allows you to specify a quota for
333 buckets the user owns.
335 - **Maximum Objects:** The ``--max-objects`` setting allows you to specify
336 the maximum number of objects. A negative value disables this setting.
338 - **Maximum Size:** The ``--max-size`` option allows you to specify a quota
339 size in B/K/M/G/T, where B is the default. A negative value disables this setting.
341 - **Quota Scope:** The ``--quota-scope`` option sets the scope for the quota.
342 The options are ``bucket`` and ``user``. Bucket quotas apply to buckets a
343 user owns. User quotas apply to a user.
349 Before you enable a quota, you must first set the quota parameters.
352 radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>]
356 radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024B
359 A negative value for num objects and / or max size means that the
360 specific quota attribute check is disabled.
363 Enable/Disable User Quota
364 -------------------------
366 Once you set a user quota, you may enable it. For example::
368 radosgw-admin quota enable --quota-scope=user --uid=<uid>
370 You may disable an enabled user quota. For example::
372 radosgw-admin quota disable --quota-scope=user --uid=<uid>
378 Bucket quotas apply to the buckets owned by the specified ``uid``. They are
379 independent of the user. ::
381 radosgw-admin quota set --uid=<uid> --quota-scope=bucket [--max-objects=<num objects>] [--max-size=<max size]
383 A negative value for num objects and / or max size means that the
384 specific quota attribute check is disabled.
387 Enable/Disable Bucket Quota
388 ---------------------------
390 Once you set a bucket quota, you may enable it. For example::
392 radosgw-admin quota enable --quota-scope=bucket --uid=<uid>
394 You may disable an enabled bucket quota. For example::
396 radosgw-admin quota disable --quota-scope=bucket --uid=<uid>
402 You may access each user's quota settings via the user information
403 API. To read user quota setting information with the CLI interface,
404 execute the following::
406 radosgw-admin user info --uid=<uid>
412 Quota stats get updated asynchronously. You can update quota
413 statistics for all users and all buckets manually to retrieve
414 the latest quota stats. ::
416 radosgw-admin user stats --uid=<uid> --sync-stats
422 To see how much of the quota a user has consumed, execute the following::
424 radosgw-admin user stats --uid=<uid>
426 .. note:: You should execute ``radosgw-admin user stats`` with the
427 ``--sync-stats`` option to receive the latest data.
432 You can set default quotas in the config. These defaults are used when
433 creating a new user and have no effect on existing users. If the
434 relevant default quota is set in config, then that quota is set on the
435 new user, and that quota is enabled. See ``rgw bucket default quota max objects``,
436 ``rgw bucket default quota max size``, ``rgw user default quota max objects``, and
437 ``rgw user default quota max size`` in `Ceph Object Gateway Config Reference`_
442 Quota statistics are cached on each RGW instance. If there are multiple
443 instances, then the cache can keep quotas from being perfectly enforced, as
444 each instance will have a different view of quotas. The options that control
445 this are ``rgw bucket quota ttl``, ``rgw user quota bucket sync interval`` and
446 ``rgw user quota sync interval``. The higher these values are, the more
447 efficient quota operations are, but the more out-of-sync multiple instances
448 will be. The lower these values are, the closer to perfect enforcement
449 multiple instances will achieve. If all three are 0, then quota caching is
450 effectively disabled, and multiple instances will have perfect quota
451 enforcement. See `Ceph Object Gateway Config Reference`_
453 Reading / Writing Global Quotas
454 -------------------------------
456 You can read and write global quota settings in the period configuration. To
457 view the global quota settings::
459 radosgw-admin global quota get
461 The global quota settings can be manipulated with the ``global quota``
462 counterparts of the ``quota set``, ``quota enable``, and ``quota disable``
465 radosgw-admin global quota set --quota-scope bucket --max-objects 1024
466 radosgw-admin global quota enable --quota-scope bucket
468 .. note:: In a multisite configuration, where there is a realm and period
469 present, changes to the global quotas must be committed using ``period
470 update --commit``. If there is no period present, the rados gateway(s) must
471 be restarted for the changes to take effect.
477 The Ceph Object Gateway logs usage for each user. You can track
478 user usage within date ranges too.
480 - Add ``rgw enable usage log = true`` in [client.rgw] section of ceph.conf and restart the radosgw service.
484 - **Start Date:** The ``--start-date`` option allows you to filter usage
485 stats from a particular start date (**format:** ``yyyy-mm-dd[HH:MM:SS]``).
487 - **End Date:** The ``--end-date`` option allows you to filter usage up
488 to a particular date (**format:** ``yyyy-mm-dd[HH:MM:SS]``).
490 - **Log Entries:** The ``--show-log-entries`` option allows you to specify
491 whether or not to include log entries with the usage stats
492 (options: ``true`` | ``false``).
494 .. note:: You may specify time with minutes and seconds, but it is stored
495 with 1 hour resolution.
501 To show usage statistics, specify the ``usage show``. To show usage for a
502 particular user, you must specify a user ID. You may also specify a start date,
503 end date, and whether or not to show log entries.::
505 radosgw-admin usage show --uid=johndoe --start-date=2012-03-01 --end-date=2012-04-01
507 You may also show a summary of usage information for all users by omitting a user ID. ::
509 radosgw-admin usage show --show-log-entries=false
515 With heavy use, usage logs can begin to take up storage space. You can trim
516 usage logs for all users and for specific users. You may also specify date
517 ranges for trim operations. ::
519 radosgw-admin usage trim --start-date=2010-01-01 --end-date=2010-12-31
520 radosgw-admin usage trim --uid=johndoe
521 radosgw-admin usage trim --uid=johndoe --end-date=2013-12-31
524 .. _radosgw-admin: ../../man/8/radosgw-admin/
525 .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/
526 .. _Ceph Object Gateway Config Reference: ../config-ref/