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",
63 "access_key": "11BS02LGFB6AL6H1ADMW",
64 "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}],
67 "op_mask": "read, write, delete",
68 "default_placement": "",
70 "bucket_quota": { "enabled": false,
73 "user_quota": { "enabled": false,
78 Creating a user also creates an ``access_key`` and ``secret_key`` entry for use
79 with any S3 API-compatible client.
81 .. important:: Check the key output. Sometimes ``radosgw-admin``
82 generates a JSON escape (``\``) character, and some clients
83 do not know how to handle JSON escape characters. Remedies include
84 removing the JSON escape character (``\``), encapsulating the string
85 in quotes, regenerating the key and ensuring that it
86 does not have a JSON escape character or specify the key and secret
93 To create a subuser (Swift interface) for the user, you must specify the user ID
94 (``--uid={username}``), a subuser ID and the access level for the subuser. ::
96 radosgw-admin subuser create --uid={uid} --subuser={uid} --access=[ read | write | readwrite | full ]
100 radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full
103 .. note:: ``full`` is not ``readwrite``, as it also includes the access control policy.
105 .. code-block:: javascript
107 { "user_id": "johndoe",
108 "display_name": "John Doe",
109 "email": "john@example.com",
114 { "id": "johndoe:swift",
115 "permissions": "full-control"}],
118 "access_key": "11BS02LGFB6AL6H1ADMW",
119 "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}],
122 "op_mask": "read, write, delete",
123 "default_placement": "",
124 "placement_tags": [],
125 "bucket_quota": { "enabled": false,
128 "user_quota": { "enabled": false,
137 To get information about a user, you must specify ``user info`` and the user ID
138 (``--uid={username}``) . ::
140 radosgw-admin user info --uid=johndoe
147 To modify information about a user, you must specify the user ID (``--uid={username}``)
148 and the attributes you want to modify. Typical modifications are to keys and secrets,
149 email addresses, display names and access levels. For example::
151 radosgw-admin user modify --uid=johndoe --display-name="John E. Doe"
153 To modify subuser values, specify ``subuser modify`` and the subuser ID. For example::
155 radosgw-admin subuser modify --uid=johndoe:swift --access=full
161 When you create a user, the user is enabled by default. However, you may suspend
162 user privileges and re-enable them at a later time. To suspend a user, specify
163 ``user suspend`` and the user ID. ::
165 radosgw-admin user suspend --uid=johndoe
167 To re-enable a suspended user, specify ``user enable`` and the user ID. ::
169 radosgw-admin user enable --uid=johndoe
171 .. note:: Disabling the user disables the subuser.
177 When you remove a user, the user and subuser are removed from the system.
178 However, you may remove just the subuser if you wish. To remove a user (and
179 subuser), specify ``user rm`` and the user ID. ::
181 radosgw-admin user rm --uid=johndoe
183 To remove the subuser only, specify ``subuser rm`` and the subuser ID. ::
185 radosgw-admin subuser rm --subuser=johndoe:swift
190 - **Purge Data:** The ``--purge-data`` option purges all data associated
193 - **Purge Keys:** The ``--purge-keys`` option purges all keys associated
200 When you remove a sub user, you are removing access to the Swift interface.
201 The user will remain in the system. To remove the subuser, specify
202 ``subuser rm`` and the subuser ID. ::
204 radosgw-admin subuser rm --subuser=johndoe:swift
210 - **Purge Keys:** The ``--purge-keys`` option purges all keys associated
215 ------------------------
217 Both users and subusers require the key to access the S3 or Swift interface. To
218 use S3, the user needs a key pair which is composed of an access key and a
219 secret key. On the other hand, to use Swift, the user typically needs a secret
220 key (password), and use it together with the associated user ID. You may create
221 a key and either specify or generate the access key and/or secret key. You may
222 also remove a key. Options include:
224 - ``--key-type=<type>`` specifies the key type. The options are: s3, swift
225 - ``--access-key=<key>`` manually specifies an S3 access key.
226 - ``--secret-key=<key>`` manually specifies a S3 secret key or a Swift secret key.
227 - ``--gen-access-key`` automatically generates a S3 key.
228 - ``--gen-secret`` automatically generates a S3 secret key or a Swift secret key.
230 An example how to add a specified S3 key pair for a user. ::
232 radosgw-admin key create --uid=foo --key-type=s3 --access-key fooAccessKey --secret-key fooSecretKey
234 .. code-block:: javascript
238 "display_name": "foo",
239 "email": "foo@example.com",
243 "access_key": "fooAccessKey",
244 "secret_key": "fooSecretKey"}],
247 Note that you may create multiple S3 key pairs for a user.
249 To attach a specified swift secret key for a subuser. ::
251 radosgw-admin key create --subuser=foo:bar --key-type=swift --secret-key barSecret
253 .. code-block:: javascript
257 "display_name": "foo",
258 "email": "foo@example.com",
262 "permissions": "full-control"}],
265 "secret_key": "asfghjghghmgm"}]}
267 Note that a subuser can have only one swift secret key.
269 Subusers can also be used with S3 APIs if the subuser is associated with a S3 key pair. ::
271 radosgw-admin key create --subuser=foo:bar --key-type=s3 --access-key barAccessKey --secret-key barSecretKey
273 .. code-block:: javascript
277 "display_name": "foo",
278 "email": "foo@example.com",
282 "permissions": "full-control"}],
285 "access_key": "barAccessKey",
286 "secret_key": "barSecretKey"}],
290 To remove a S3 key pair, specify the access key. ::
292 radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey
294 To remove the swift secret key. ::
296 radosgw-admin key rm -subuser=foo:bar --key-type=swift
299 Add / Remove Admin Capabilities
300 -------------------------------
302 The Ceph Storage Cluster provides an administrative API that enables users to
303 execute administrative functions via the REST API. By default, users do NOT have
304 access to this API. To enable a user to exercise administrative functionality,
305 provide the user with administrative capabilities.
307 To add administrative capabilities to a user, execute the following::
309 radosgw-admin caps add --uid={uid} --caps={caps}
312 You can add read, write or all capabilities to users, buckets, metadata and
313 usage (utilization). For example::
315 --caps="[users|buckets|metadata|usage|zone]=[*|read|write|read, write]"
319 radosgw-admin caps add --uid=johndoe --caps="users=*;buckets=*"
322 To remove administrative capabilities from a user, execute the following::
324 radosgw-admin caps rm --uid=johndoe --caps={caps}
330 The Ceph Object Gateway enables you to set quotas on users and buckets owned by
331 users. Quotas include the maximum number of objects in a bucket and the maximum
332 storage size a bucket can hold.
334 - **Bucket:** The ``--bucket`` option allows you to specify a quota for
335 buckets the user owns.
337 - **Maximum Objects:** The ``--max-objects`` setting allows you to specify
338 the maximum number of objects. A negative value disables this setting.
340 - **Maximum Size:** The ``--max-size`` option allows you to specify a quota
341 size in B/K/M/G/T, where B is the default. A negative value disables this setting.
343 - **Quota Scope:** The ``--quota-scope`` option sets the scope for the quota.
344 The options are ``bucket`` and ``user``. Bucket quotas apply to buckets a
345 user owns. User quotas apply to a user.
351 Before you enable a quota, you must first set the quota parameters.
354 radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>]
358 radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024B
361 A negative value for num objects and / or max size means that the
362 specific quota attribute check is disabled.
365 Enable/Disable User Quota
366 -------------------------
368 Once you set a user quota, you may enable it. For example::
370 radosgw-admin quota enable --quota-scope=user --uid=<uid>
372 You may disable an enabled user quota. For example::
374 radosgw-admin quota disable --quota-scope=user --uid=<uid>
380 Bucket quotas apply to the buckets owned by the specified ``uid``. They are
381 independent of the user. ::
383 radosgw-admin quota set --uid=<uid> --quota-scope=bucket [--max-objects=<num objects>] [--max-size=<max size]
385 A negative value for num objects and / or max size means that the
386 specific quota attribute check is disabled.
389 Enable/Disable Bucket Quota
390 ---------------------------
392 Once you set a bucket quota, you may enable it. For example::
394 radosgw-admin quota enable --quota-scope=bucket --uid=<uid>
396 You may disable an enabled bucket quota. For example::
398 radosgw-admin quota disable --quota-scope=bucket --uid=<uid>
404 You may access each user's quota settings via the user information
405 API. To read user quota setting information with the CLI interface,
406 execute the following::
408 radosgw-admin user info --uid=<uid>
414 Quota stats get updated asynchronously. You can update quota
415 statistics for all users and all buckets manually to retrieve
416 the latest quota stats. ::
418 radosgw-admin user stats --uid=<uid> --sync-stats
424 To see how much of the quota a user has consumed, execute the following::
426 radosgw-admin user stats --uid=<uid>
428 .. note:: You should execute ``radosgw-admin user stats`` with the
429 ``--sync-stats`` option to receive the latest data.
434 You can set default quotas in the config. These defaults are used when
435 creating a new user and have no effect on existing users. If the
436 relevant default quota is set in config, then that quota is set on the
437 new user, and that quota is enabled. See ``rgw bucket default quota max objects``,
438 ``rgw bucket default quota max size``, ``rgw user default quota max objects``, and
439 ``rgw user default quota max size`` in `Ceph Object Gateway Config Reference`_
444 Quota statistics are cached on each RGW instance. If there are multiple
445 instances, then the cache can keep quotas from being perfectly enforced, as
446 each instance will have a different view of quotas. The options that control
447 this are ``rgw bucket quota ttl``, ``rgw user quota bucket sync interval`` and
448 ``rgw user quota sync interval``. The higher these values are, the more
449 efficient quota operations are, but the more out-of-sync multiple instances
450 will be. The lower these values are, the closer to perfect enforcement
451 multiple instances will achieve. If all three are 0, then quota caching is
452 effectively disabled, and multiple instances will have perfect quota
453 enforcement. See `Ceph Object Gateway Config Reference`_
455 Reading / Writing Global Quotas
456 -------------------------------
458 You can read and write global quota settings in the period configuration. To
459 view the global quota settings::
461 radosgw-admin global quota get
463 The global quota settings can be manipulated with the ``global quota``
464 counterparts of the ``quota set``, ``quota enable``, and ``quota disable``
467 radosgw-admin global quota set --quota-scope bucket --max-objects 1024
468 radosgw-admin global quota enable --quota-scope bucket
470 .. note:: In a multisite configuration, where there is a realm and period
471 present, changes to the global quotas must be committed using ``period
472 update --commit``. If there is no period present, the rados gateway(s) must
473 be restarted for the changes to take effect.
479 The Ceph Object Gateway logs usage for each user. You can track
480 user usage within date ranges too.
482 - Add ``rgw enable usage log = true`` in [client.rgw] section of ceph.conf and restart the radosgw service.
486 - **Start Date:** The ``--start-date`` option allows you to filter usage
487 stats from a particular start date (**format:** ``yyyy-mm-dd[HH:MM:SS]``).
489 - **End Date:** The ``--end-date`` option allows you to filter usage up
490 to a particular date (**format:** ``yyyy-mm-dd[HH:MM:SS]``).
492 - **Log Entries:** The ``--show-log-entries`` option allows you to specify
493 whether or not to include log entries with the usage stats
494 (options: ``true`` | ``false``).
496 .. note:: You may specify time with minutes and seconds, but it is stored
497 with 1 hour resolution.
503 To show usage statistics, specify the ``usage show``. To show usage for a
504 particular user, you must specify a user ID. You may also specify a start date,
505 end date, and whether or not to show log entries.::
507 radosgw-admin usage show --uid=johndoe --start-date=2012-03-01 --end-date=2012-04-01
509 You may also show a summary of usage information for all users by omitting a user ID. ::
511 radosgw-admin usage show --show-log-entries=false
517 With heavy use, usage logs can begin to take up storage space. You can trim
518 usage logs for all users and for specific users. You may also specify date
519 ranges for trim operations. ::
521 radosgw-admin usage trim --start-date=2010-01-01 --end-date=2010-12-31
522 radosgw-admin usage trim --uid=johndoe
523 radosgw-admin usage trim --uid=johndoe --end-date=2013-12-31
526 .. _radosgw-admin: ../../man/8/radosgw-admin/
527 .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/
528 .. _Ceph Object Gateway Config Reference: ../config-ref/