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 .
34 You can create, modify, view, suspend and remove users and subusers. In addition
35 to user and subuser IDs, you may add a display name and an email address for a
36 user. You can specify a key and secret, or generate a key and secret
37 automatically. When generating or specifying keys, note that user IDs correspond
38 to an S3 key type and subuser IDs correspond to a swift key type. Swift keys
39 also have access levels of ``read``, ``write``, ``readwrite`` and ``full``.
45 To create a user (S3 interface), execute the following::
47 radosgw-admin user create --uid={username} --display-name="{display-name}" [--email={email}]
51 radosgw-admin user create --uid=johndoe --display-name="John Doe" --email=john@example.com
53 .. code-block:: javascript
55 { "user_id": "johndoe",
56 "display_name": "John Doe",
57 "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",
113 { "id": "johndoe:swift",
114 "permissions": "full-control"}],
117 "access_key": "11BS02LGFB6AL6H1ADMW",
118 "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}],
121 "op_mask": "read, write, delete",
122 "default_placement": "",
123 "placement_tags": [],
124 "bucket_quota": { "enabled": false,
127 "user_quota": { "enabled": false,
136 To get information about a user, you must specify ``user info`` and the user ID
137 (``--uid={username}``) . ::
139 radosgw-admin user info --uid=johndoe
146 To modify information about a user, you must specify the user ID (``--uid={username}``)
147 and the attributes you want to modify. Typical modifications are to keys and secrets,
148 email addresses, display names and access levels. For example::
150 radosgw-admin user modify --uid=johndoe --display-name="John E. Doe"
152 To modify subuser values, specify ``subuser modify``, user ID and the subuser ID. For example::
154 radosgw-admin subuser modify --uid=johndoe --subuser=johndoe:swift --access=full
160 When you create a user, the user is enabled by default. However, you may suspend
161 user privileges and re-enable them at a later time. To suspend a user, specify
162 ``user suspend`` and the user ID. ::
164 radosgw-admin user suspend --uid=johndoe
166 To re-enable a suspended user, specify ``user enable`` and the user ID. ::
168 radosgw-admin user enable --uid=johndoe
170 .. note:: Disabling the user disables the subuser.
176 When you remove a user, the user and subuser are removed from the system.
177 However, you may remove just the subuser if you wish. To remove a user (and
178 subuser), specify ``user rm`` and the user ID. ::
180 radosgw-admin user rm --uid=johndoe
182 To remove the subuser only, specify ``subuser rm`` and the subuser ID. ::
184 radosgw-admin subuser rm --subuser=johndoe:swift
189 - **Purge Data:** The ``--purge-data`` option purges all data associated
192 - **Purge Keys:** The ``--purge-keys`` option purges all keys associated
199 When you remove a sub user, you are removing access to the Swift interface.
200 The user will remain in the system. To remove the subuser, specify
201 ``subuser rm`` and the subuser ID. ::
203 radosgw-admin subuser rm --subuser=johndoe:swift
209 - **Purge Keys:** The ``--purge-keys`` option purges all keys associated
214 ------------------------
216 Both users and subusers require the key to access the S3 or Swift interface. To
217 use S3, the user needs a key pair which is composed of an access key and a
218 secret key. On the other hand, to use Swift, the user typically needs a secret
219 key (password), and use it together with the associated user ID. You may create
220 a key and either specify or generate the access key and/or secret key. You may
221 also remove a key. Options include:
223 - ``--key-type=<type>`` specifies the key type. The options are: s3, swift
224 - ``--access-key=<key>`` manually specifies an S3 access key.
225 - ``--secret-key=<key>`` manually specifies a S3 secret key or a Swift secret key.
226 - ``--gen-access-key`` automatically generates a random S3 access key.
227 - ``--gen-secret`` automatically generates a random S3 secret key or a random Swift secret key.
229 An example how to add a specified S3 key pair for a user. ::
231 radosgw-admin key create --uid=foo --key-type=s3 --access-key fooAccessKey --secret-key fooSecretKey
233 .. code-block:: javascript
237 "display_name": "foo",
238 "email": "foo@example.com",
242 "access_key": "fooAccessKey",
243 "secret_key": "fooSecretKey"}],
246 Note that you may create multiple S3 key pairs for a user.
248 To attach a specified swift secret key for a subuser. ::
250 radosgw-admin key create --subuser=foo:bar --key-type=swift --secret-key barSecret
252 .. code-block:: javascript
256 "display_name": "foo",
257 "email": "foo@example.com",
261 "permissions": "full-control"}],
264 "secret_key": "asfghjghghmgm"}]}
266 Note that a subuser can have only one swift secret key.
268 Subusers can also be used with S3 APIs if the subuser is associated with a S3 key pair. ::
270 radosgw-admin key create --subuser=foo:bar --key-type=s3 --access-key barAccessKey --secret-key barSecretKey
272 .. code-block:: javascript
276 "display_name": "foo",
277 "email": "foo@example.com",
281 "permissions": "full-control"}],
284 "access_key": "barAccessKey",
285 "secret_key": "barSecretKey"}],
289 To remove a S3 key pair, specify the access key. ::
291 radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey
293 To remove the swift secret key. ::
295 radosgw-admin key rm --subuser=foo:bar --key-type=swift
298 Add / Remove Admin Capabilities
299 -------------------------------
301 The Ceph Storage Cluster provides an administrative API that enables users to
302 execute administrative functions via the REST API. By default, users do NOT have
303 access to this API. To enable a user to exercise administrative functionality,
304 provide the user with administrative capabilities.
306 To add administrative capabilities to a user, execute the following::
308 radosgw-admin caps add --uid={uid} --caps={caps}
311 You can add read, write or all capabilities to users, buckets, metadata and
312 usage (utilization). For example::
314 --caps="[users|buckets|metadata|usage|zone|amz-cache|info|bilog|mdlog|datalog|user-policy|oidc-provider|roles|ratelimit]=[*|read|write|read, write]"
318 radosgw-admin caps add --uid=johndoe --caps="users=*;buckets=*"
321 To remove administrative capabilities from a user, execute the following::
323 radosgw-admin caps rm --uid=johndoe --caps={caps}
329 The Ceph Object Gateway enables you to set quotas on users and buckets owned by
330 users. Quotas include the maximum number of objects in a bucket and the maximum
331 storage size a bucket can hold.
333 - **Bucket:** The ``--bucket`` option allows you to specify a quota for
334 buckets the user owns.
336 - **Maximum Objects:** The ``--max-objects`` setting allows you to specify
337 the maximum number of objects. A negative value disables this setting.
339 - **Maximum Size:** The ``--max-size`` option allows you to specify a quota
340 size in B/K/M/G/T, where B is the default. A negative value disables this setting.
342 - **Quota Scope:** The ``--quota-scope`` option sets the scope for the quota.
343 The options are ``bucket`` and ``user``. Bucket quotas apply to buckets a
344 user owns. User quotas apply to a user.
350 Before you enable a quota, you must first set the quota parameters.
353 radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>]
357 radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024B
360 A negative value for num objects and / or max size means that the
361 specific quota attribute check is disabled.
364 Enable/Disable User Quota
365 -------------------------
367 Once you set a user quota, you may enable it. For example::
369 radosgw-admin quota enable --quota-scope=user --uid=<uid>
371 You may disable an enabled user quota. For example::
373 radosgw-admin quota disable --quota-scope=user --uid=<uid>
379 Bucket quotas apply to the buckets owned by the specified ``uid``. They are
380 independent of the user. ::
382 radosgw-admin quota set --uid=<uid> --quota-scope=bucket [--max-objects=<num objects>] [--max-size=<max size]
384 A negative value for num objects and / or max size means that the
385 specific quota attribute check is disabled.
388 Enable/Disable Bucket Quota
389 ---------------------------
391 Once you set a bucket quota, you may enable it. For example::
393 radosgw-admin quota enable --quota-scope=bucket --uid=<uid>
395 You may disable an enabled bucket quota. For example::
397 radosgw-admin quota disable --quota-scope=bucket --uid=<uid>
403 You may access each user's quota settings via the user information
404 API. To read user quota setting information with the CLI interface,
405 execute the following::
407 radosgw-admin user info --uid=<uid>
413 Quota stats get updated asynchronously. You can update quota
414 statistics for all users and all buckets manually to retrieve
415 the latest quota stats. ::
417 radosgw-admin user stats --uid=<uid> --sync-stats
419 .. _rgw_user_usage_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.
476 Rate Limit Management
477 =====================
479 The Ceph Object Gateway enables you to set rate limits on users and buckets.
480 Rate limit includes the maximum number of read ops and write ops per minute
481 and how many bytes per minute could be written or read per user or per bucket.
482 Requests that are using GET or HEAD method in the REST request are considered as "read requests", otherwise they are considered as "write requests".
483 Every Object Gateway tracks per user and bucket metrics separately, these metrics are not shared with other gateways.
484 That means that the desired limits configured should be divide by the number of active Object Gateways.
485 For example, if userA should be limited by 10 ops per minute and there are 2 Object Gateways in the cluster,
486 the limit over userA should be 5 (10 ops per minute / 2 RGWs).
487 if the requests are ``not`` balanced between RGWs, the rate limit may be underutilized.
488 For example, if the ops limit is 5 and there are 2 RGWs, ``but`` the Load Balancer send load only to one of those RGWs,
489 The effective limit would be 5 ops, because this limit is enforced per RGW.
490 If there is a limit reached for bucket not for user or vice versa the request would be cancelled as well.
491 The bandwidth counting happens after the request is being accepted, as a result, even if in the middle of the request the bucket/user has reached its bandwidth limit this request will proceed.
492 The RGW will keep a "debt" of used bytes more than the configured value and will prevent this user/bucket from sending more requests until there "debt" is being paid.
493 The "debt" maximum size is twice the max-read/write-bytes per minute.
494 If userA has 1 byte read limit per minute and this user tries to GET 1 GB object, the user will be able to do it.
495 After userA completes this 1GB operation, the RGW will block the user request for up to 2 minutes until userA will be able to send GET request again.
498 - **Bucket:** The ``--bucket`` option allows you to specify a rate limit for a
501 - **User:** The ``--uid`` option allows you to specify a rate limit for a
504 - **Maximum Read Ops:** The ``--max-read-ops`` setting allows you to specify
505 the maximum number of read ops per minute per RGW. A 0 value disables this setting (which means unlimited access).
507 - **Maximum Read Bytes:** The ``--max-read-bytes`` setting allows you to specify
508 the maximum number of read bytes per minute per RGW. A 0 value disables this setting (which means unlimited access).
510 - **Maximum Write Ops:** The ``--max-write-ops`` setting allows you to specify
511 the maximum number of write ops per minute per RGW. A 0 value disables this setting (which means unlimited access).
513 - **Maximum Write Bytes:** The ``--max-write-bytes`` setting allows you to specify
514 the maximum number of write bytes per minute per RGW. A 0 value disables this setting (which means unlimited access).
516 - **Rate Limit Scope:** The ``--ratelimit-scope`` option sets the scope for the rate limit.
517 The options are ``bucket`` , ``user`` and ``anonymous``. Bucket rate limit apply to buckets.
518 The user rate limit applies to a user. Anonymous applies to an unauthenticated user.
519 Anonymous scope is only available for global rate limit.
525 Before you enable a rate limit, you must first set the rate limit parameters.
528 radosgw-admin ratelimit set --ratelimit-scope=user --uid=<uid> <[--max-read-ops=<num ops>] [--max-read-bytes=<num bytes>]
529 [--max-write-ops=<num ops>] [--max-write-bytes=<num bytes>]>
533 radosgw-admin ratelimit set --ratelimit-scope=user --uid=johndoe --max-read-ops=1024 --max-write-bytes=10240
536 A 0 value for num ops and / or num bytes means that the
537 specific rate limit attribute check is disabled.
542 Get the current configured rate limit parameters
545 radosgw-admin ratelimit get --ratelimit-scope=user --uid=<uid>
549 radosgw-admin ratelimit get --ratelimit-scope=user --uid=johndoe
552 A 0 value for num ops and / or num bytes means that the
553 specific rate limit attribute check is disabled.
556 Enable/Disable User Rate Limit
557 ------------------------------
559 Once you set a user rate limit, you may enable it. For example::
561 radosgw-admin ratelimit enable --ratelimit-scope=user --uid=<uid>
563 You may disable an enabled user rate limit. For example::
565 radosgw-admin ratelimit disable --ratelimit-scope=user --uid=johndoe
568 Set Bucket Rate Limit
569 ---------------------
571 Before you enable a rate limit, you must first set the rate limit parameters.
574 radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=<bucket> <[--max-read-ops=<num ops>] [--max-read-bytes=<num bytes>]
575 [--max-write-ops=<num ops>] [--max-write-bytes=<num bytes>]>
579 radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=mybucket --max-read-ops=1024 --max-write-bytes=10240
582 A 0 value for num ops and / or num bytes means that the
583 specific rate limit attribute check is disabled.
585 Get Bucket Rate Limit
586 ---------------------
588 Get the current configured rate limit parameters
591 radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=<bucket>
595 radosgw-admin ratelimit get --ratelimit-scope=bucket --bucket=mybucket
598 A 0 value for num ops and / or num bytes means that the
599 specific rate limit attribute check is disabled.
602 Enable/Disable Bucket Rate Limit
603 --------------------------------
605 Once you set a bucket rate limit, you may enable it. For example::
607 radosgw-admin ratelimit enable --ratelimit-scope=bucket --bucket=<bucket>
609 You may disable an enabled bucket rate limit. For example::
611 radosgw-admin ratelimit disable --ratelimit-scope=bucket --uid=mybucket
614 Reading / Writing Global Rate Limit Configuration
615 -------------------------------------------------
617 You can read and write global rate limit settings in the period configuration. To
618 view the global rate limit settings::
620 radosgw-admin global ratelimit get
622 The global rate limit settings can be manipulated with the ``global ratelimit``
623 counterparts of the ``ratelimit set``, ``ratelimit enable``, and ``ratelimit disable``
624 commands. Per user and per bucket ratelimit configuration is overriding the global configuration::
626 radosgw-admin global ratelimit set --ratelimit-scope bucket --max-read-ops=1024
627 radosgw-admin global ratelimit enable --ratelimit-scope bucket
629 The global rate limit can configure rate limit scope for all authenticated users::
631 radosgw-admin global ratelimit set --ratelimit-scope user --max-read-ops=1024
632 radosgw-admin global ratelimit enable --ratelimit-scope user
634 The global rate limit can configure rate limit scope for all unauthenticated users::
636 radosgw-admin global ratelimit set --ratelimit-scope=anonymous --max-read-ops=1024
637 radosgw-admin global ratelimit enable --ratelimit-scope=anonymous
639 .. note:: In a multisite configuration, where there is a realm and period
640 present, changes to the global rate limit must be committed using ``period
641 update --commit``. If there is no period present, the rados gateway(s) must
642 be restarted for the changes to take effect.
647 The Ceph Object Gateway logs usage for each user. You can track
648 user usage within date ranges too.
650 - Add ``rgw enable usage log = true`` in [client.rgw] section of ceph.conf and restart the radosgw service.
654 - **Start Date:** The ``--start-date`` option allows you to filter usage
655 stats from a particular start date (**format:** ``yyyy-mm-dd[HH:MM:SS]``).
657 - **End Date:** The ``--end-date`` option allows you to filter usage up
658 to a particular date (**format:** ``yyyy-mm-dd[HH:MM:SS]``).
660 - **Log Entries:** The ``--show-log-entries`` option allows you to specify
661 whether or not to include log entries with the usage stats
662 (options: ``true`` | ``false``).
664 .. note:: You may specify time with minutes and seconds, but it is stored
665 with 1 hour resolution.
671 To show usage statistics, specify the ``usage show``. To show usage for a
672 particular user, you must specify a user ID. You may also specify a start date,
673 end date, and whether or not to show log entries.::
675 radosgw-admin usage show --uid=johndoe --start-date=2012-03-01 --end-date=2012-04-01
677 You may also show a summary of usage information for all users by omitting a user ID. ::
679 radosgw-admin usage show --show-log-entries=false
685 With heavy use, usage logs can begin to take up storage space. You can trim
686 usage logs for all users and for specific users. You may also specify date
687 ranges for trim operations. ::
689 radosgw-admin usage trim --start-date=2010-01-01 --end-date=2010-12-31
690 radosgw-admin usage trim --uid=johndoe
691 radosgw-admin usage trim --uid=johndoe --end-date=2013-12-31
694 .. _radosgw-admin: ../../man/8/radosgw-admin/
695 .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/
696 .. _Ceph Object Gateway Config Reference: ../config-ref/