To add a specific S3 key pair for a user, run a command of the following form:

.. prompt:: bash #

   radosgw-admin key create --uid=foo --key-type=s3 --access-key fooAccessKey --secret-key fooSecretKey

.. code-block:: javascript

  { "user_id": "foo",
    "rados_uid": 0,
    "display_name": "foo",
    "email": "[email protected]",
    "suspended": 0,
    "keys": [
      { "user": "foo",
        "access_key": "fooAccessKey",
        "secret_key": "fooSecretKey"}],
  }

.. note:: You can create multiple S3 key pairs for a user.

Adding Swift secret keys

Subusers can also be used with S3 APIs if the subuser is associated with a S3
key pair. To associate a subuser with an S3 key pair, run a command of the
following form:

.. prompt:: bash #

   radosgw-admin key create --subuser=foo:bar --key-type=s3 --access-key barAccessKey --secret-key barSecretKey
	
.. code-block:: javascript

  { "user_id": "foo",
    "rados_uid": 0,
    "display_name": "foo",
    "email": "[email protected]",
    "suspended": 0,
    "subusers": [
       { "id": "foo:bar",
         "permissions": "full-control"}],
    "keys": [
      { "user": "foo:bar",
        "access_key": "barAccessKey",
        "secret_key": "barSecretKey"}],
  }


Removing S3 Key Pairs
~~~~~~~~~~~~~~~~~~~~~

To remove a S3 key pair, specify the access key to be removed. Run a command of the following form: 

.. prompt:: bash #

   radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey 

Removing Swift Secret Keys
~~~~~~~~~~~~~~~~~~~~~~~~~~

To remove a Swift secret key, run a command of the following form: 

.. prompt:: bash #

   radosgw-admin key rm --subuser=foo:bar --key-type=swift


Add or Remove Admin Capabilities
--------------------------------

The Ceph Storage Cluster provides an :ref:`Admin Ops API <radosgw admin ops>` 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, run a command of the following
form: 

.. prompt:: bash #

   radosgw-admin caps add --uid={uid} --caps={caps}

You can add read, write or all capabilities to users, buckets, metadata and
usage (utilization). To do this, use a command-line option of the following
form:

::

    --caps="[users|buckets|metadata|usage|zone|amz-cache|info|bilog|mdlog|datalog|user-policy|oidc-provider|roles|ratelimit|user-info-without-keys|accounts]=[\*|read|write|read, write]"

For example:

.. prompt:: bash #

	radosgw-admin caps add --uid=johndoe --caps="users=*;buckets=*"

To remove administrative capabilities from a user, run a command of the
following form: 

.. prompt:: bash #

   radosgw-admin caps rm --uid=johndoe --caps={caps}

Admin and System Users
----------------------

Users with the ``--admin`` or ``--system`` flag have global read and write
permissions. These permissions apply to all APIs including S3 and Swift,
unlike Admin Capabilities, and cannot be denied by IAM policy.

The ``--system`` flag should only be used as documented in :ref:`Multisite Configuration <multisite>`.

The ``--admin`` flag can be useful for troubleshooting and recovery. For
example, if a user accidentally removes their permissions to a bucket or
object, the admin user's credentials can be used to issue the S3/Swift API
requests necessary to restore them.

.. warning:: When not in use, consider deleting the admin user or disabling
   its access keys. Do not give admin permissions to untrusted users.

To create an admin user:

.. prompt:: bash #

   radosgw-admin user create --uid={username} --display-name="{display-name}" --admin

To add the admin flag to an existing user:

.. prompt:: bash #

   radosgw-admin user modify --uid={username} --admin

To remove the admin flag from an existing user:

.. prompt:: bash #

   radosgw-admin user modify --uid={username} --admin=0

.. _radosgw-quota-management:

Quota Management
================

The Ceph Object Gateway makes it possible for 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 a bucket can hold.

- **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
  size in B/K/M/G/T, where B is the default. 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
--------------

User Quotas are summed across all buckets owned by the user.

Before you enable a quota, you must first set the quota parameters.
To set quota parameters, run a command of the following form: 

.. prompt:: bash #

   radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>]

For example:

.. prompt:: bash #

   radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024B

Passing a negative value as an argument of ``--max-objects`` or ``--max-size``
disables the given quota attribute.  


Enabling and Disabling User Quota
---------------------------------

After a user quota is set, it must be enabled in order to take effect. To enable a user quota, run a command of the following form: 

.. prompt:: bash #

   radosgw-admin quota enable --quota-scope=user --uid=<uid>

To disable an enabled user quota, run a command of the following form: 

.. prompt:: bash #

   radosgw-admin quota disable --quota-scope=user --uid=<uid>


Set Bucket Quota
----------------

If the ``--bucket`` option is specified, the bucket quota applies to a single bucket with the specified name.
Else, if the ``--uid`` option is specified, the bucket quota applies to all buckets owned by the user with the specified UID.

To set a bucket quota, run a command of the following form:

.. prompt:: bash #

   radosgw-admin quota set --quota-scope=bucket {--bucket=<bucket name> | --uid=<uid>} [--max-objects=<num objects>] [--max-size=<max size>]

A negative value for ``--max-objects`` or ``--max-size`` means that the
specific quota attribute is disabled.


Enable and Disabling Bucket Quota
---------------------------------

After a bucket quota has been set, it must be enabled in order to take effect.
To enable a bucket quota, run a command of the following form:

.. prompt:: bash #

   radosgw-admin quota enable --quota-scope=bucket --uid=<uid>

To disable an enabled bucket quota, run a command of the following form: 

.. prompt:: bash #

   radosgw-admin quota disable --quota-scope=bucket --uid=<uid>


Get Quota Settings
------------------

You can access each user's quota settings via the user information
API. To read user quota setting information with the CLI interface, 
run a command of the following form:

.. prompt:: bash #

   radosgw-admin user info --uid=<uid>


Update Quota Stats
------------------

Quota stats are updated asynchronously. You can update quota statistics for all
users and all buckets manually to force an update of the latest quota stats. To
update quota statistics for all users and all buckets in order to retrieve the
latest quota statistics, run a command of the following form:

.. prompt:: bash #

   radosgw-admin user stats --uid=<uid> --sync-stats

.. _rgw_user_usage_stats:

Get User Usage Stats
--------------------

To see how much of a quota a user has consumed, run a command of the following
form: 

.. prompt:: bash #

   radosgw-admin user stats --uid=<uid>

.. note:: Run ``radosgw-admin user stats`` with the ``--sync-stats`` option to
   receive the latest data.

Default Quotas
--------------

You can set default quotas in the Ceph Object Gateway config. **These defaults
will be used only when creating new users and will have no effect on existing
users.** If a default quota is set in the Ceph Object Gateway Config, then that
quota is set for all subsequently-created users, and that quota is enabled. See
``rgw_bucket_default_quota_max_objects``,
``rgw_bucket_default_quota_max_size``, ``rgw_user_default_quota_max_objects``,
``rgw_user_default_quota_max_size``, ``rgw_account_default_quota_max_objects``,
and ``rgw_account_default_quota_max_size`` in :ref:`radosgw-config-ref`.

Quota Cache
-----------

Quota statistics are cached by each RGW instance. If multiple RGW instances are
deployed, then this cache may prevent quotas from being perfectly enforced,
because each instance may have a different set of quota settings.  

Here are the options that control this behavior: 

:confval:`rgw_bucket_quota_ttl`
:confval:`rgw_user_quota_bucket_sync_interval`
:confval:`rgw_user_quota_sync_interval`

Increasing these values will make quota operations more efficient at the cost
of increasing the likelihood that the multiple RGW instances may not
consistently have the latest quota settings. Decreasing these values brings
the multiple RGW instances closer to perfect quota synchronization. 

If all three values are set to ``0`` , then quota caching is effectively
disabled, and multiple instances will have perfect quota enforcement.  See
:ref:`radosgw-config-ref`.

Reading / Writing Global Quotas
-------------------------------

You can read and write global quota settings in the period configuration. To
view the global quota settings, run the following command:

.. prompt:: bash #

   radosgw-admin global quota get

Global quota settings can be manipulated with the ``global quota``
counterparts of the ``quota set``, ``quota enable``, and ``quota disable``
commands, as in the following examples:  

.. prompt:: bash #

	radosgw-admin global quota set --quota-scope bucket --max-objects 1024
	radosgw-admin global quota enable --quota-scope bucket

.. note:: In a multisite configuration where there is a realm and period
   present, changes to the global quotas must be committed using ``period
   update --commit``. If no period is present, the RGW instances must
   be restarted for the changes to take effect.


.. _radosgw-rate-limit-management:

Rate Limit Management
=====================

Quotas can be set for The Ceph Object Gateway on users and buckets. The "rate
limit" includes the maximum number of read operations and write operations
per accumulation interval as well as the number of bytes per accumulation interval
that can be written or read per user or per bucket. It also includes the maximum
number of list requests and delete operations per accumulation interval.
The accumulation interval is configured by the :confval:`rgw_ratelimit_interval` option.
The default value is 60 seconds.
(Note: S3 Multi-Object Delete operation are currently not supported by rate limiting)

The configured limits should be divided by the number of active object gateways. For example,
if "user A" is to be be limited to 10 ops per minute and there are two object gateways in the cluster,
then the limit on "user A" should be 5 (10 ops per minute / 2 RGWs).
If the requests are not balanced between RGWs, the rate limit might be underutilized.
For example: if the ops limit is 5 and there are two RGWs,
but the Load Balancer sends load to only one of those RGWs,
the effective limit is 5 ops, because this limit is enforced per RGW.

Read Requests and Write Requests
--------------------------------
Operations that use the ``GET`` method or the ``HEAD`` method in their REST
requests are "read requests". All other requests are "write requests".  

How Metrics Work
----------------
Each object gateway tracks per-user metrics separately from bucket metrics.
These metrics are not shared with other gateways. The configured limits should
be divided by the number of active object gateways. For example, if "user A" is
to be be limited to 10 ops per accumulation interval and there are two object gateways in the
cluster, then the limit on "user A" should be ``5`` (10 ops per accumulation interval / 2
RGWs). If the requests are **not** balanced between RGWs, the rate limit might
be underutilized. For example: if the ops limit is ``5`` and there are two
RGWs, **but** the Load Balancer sends load to only one of those RGWs, the
effective limit is 5 ops, because this limit is enforced per RGW. If the rate
limit that has been set for the bucket has been reached but the rate limit that
has been set for the user has not been reached, then the request is cancelled.
The contrary holds as well: if the rate limit that has been set for the user
has been reached but the rate limit that has been set for the bucket has not
been reached, then the request is cancelled.

The accounting of bandwidth happens only after a request has been accepted.
This means that requests will proceed even if the bucket rate limit or user
rate limit is reached during the execution of the request. The RGW keeps track
of a "debt" consisting of bytes used in excess of the configured value; users
or buckets that incur this kind of debt are prevented from sending more
requests until the "debt" has been repaid. The maximum size of the "debt" is
twice the max-read/write-bytes per accumulation interval. If "user A" is subject to a 1-byte
read limit per accumulation interval and they attempt to ``GET`` an object that is 1 GB in size,
then the ``GET`` action will fail. After "user A" has completed this 1 GB
operation, RGW blocks the user's requests for up to two accumulation intervals. After this
time has elapsed, "user A" will be able to send ``GET`` requests again.


- **Bucket:** The ``--bucket`` option allows you to specify a rate limit for a
  bucket.

- **User:** The ``--uid`` option allows you to specify a rate limit for a
  user.

- **Maximum Read Ops:** The ``--max-read-ops`` setting allows you to specify
  the maximum number of read ops per accumulation interval per RGW instance. A ``0`` value
  disables throttling.
  
- **Maximum Read Bytes:** The ``--max-read-bytes`` setting allows you to limit
  read bytes per accumulation interval per RGW instance. A ``0`` value disables throttling.

- **Maximum Write Ops:** The ``--max-write-ops`` setting allows you to specify
  the maximum number of write ops per accumulation interval per RGW instance. A ``0`` value
  disables throttling.
  
- **Maximum Write Bytes:** The ``--max-write-bytes`` setting allows you to
  specify the maximum number of write bytes per accumulation interval per RGW instance. A
  ``0`` value disables throttling.

- **Maximum List Ops:** The ``--max-list-ops`` setting allows you to
  specify the maximum number of bucket listing requests per accumulation interval per RGW instance.
  A ``0`` value disables throttling.

- **Maximum Delete Ops:** The ``--max-delete-ops`` setting allows you to
  specify the maximum number of delete operations per accumulation interval per RGW instance.
  A ``0`` value disables throttling.

- **Rate Limit Scope:** The ``--ratelimit-scope`` option sets the scope for the
  rate limit.  The options are ``bucket`` , ``user`` and ``anonymous``. Bucket
  rate limit apply to buckets.  The user rate limit applies to a user.  The
  ``anonymous`` option applies to an unauthenticated user. Anonymous scope is
  available only for global rate limit.


Set User Rate Limit
-------------------

Before you can enable a rate limit, you must first set the rate limit
parameters. The following is the general form of commands that set rate limit
parameters: 

.. prompt:: bash #

   radosgw-admin ratelimit set --ratelimit-scope=user --uid=<uid> \
                                 <[--max-read-ops=<num ops>] [--max-read-bytes=<num bytes>] \
                                 [--max-write-ops=<num ops>] [--max-write-bytes=<num bytes>] \
                                 [--max-list-ops=<num ops>] [--max-delete-ops=<num ops>]>

An example of using ``radosgw-admin ratelimit set`` to set a rate limit might
look like this: 

.. prompt:: bash #

   radosgw-admin ratelimit set --ratelimit-scope=user --uid=johndoe --max-read-ops=1024 --max-write-bytes=10240

A value of ``0`` assigned to ``--max-read-ops``, ``--max-read-bytes``,
``--max-write-ops``, or ``--max-write-bytes`` disables the specified rate
limit.  

Get User Rate Limit
-------------------

The ``radosgw-admin ratelimit get`` command returns the currently configured
rate limit parameters.

The following is the general form of the command that returns the current
configured limit parameters:  

.. prompt:: bash #

   radosgw-admin ratelimit get --ratelimit-scope=user --uid=<uid>

An example of using ``radosgw-admin ratelimit get`` to return the rate limit
parameters might look like this: 

.. prompt:: bash #

   radosgw-admin ratelimit get --ratelimit-scope=user --uid=johndoe

A value of ``0`` assigned to ``--max-read-ops``, ``--max-read-bytes``,
``--max-write-ops``, or ``--max-write-bytes`` disables the specified rate
limit.  


Enable and Disable User Rate Limit
----------------------------------

After you have set a user rate limit, you must enable it in order for it to
take effect. Run a command of the following form to enable a user rate limit: 

.. prompt:: bash #

   radosgw-admin ratelimit enable --ratelimit-scope=user --uid=<uid>

To disable an enabled user rate limit, run a command of the following form: 

.. prompt:: bash #

   radosgw-admin ratelimit disable --ratelimit-scope=user --uid=johndoe


Set Bucket Rate Limit
---------------------

Before you enable a rate limit, you must first set the rate limit parameters.
The following is the general form of commands that set rate limit parameters:

.. prompt:: bash #

   radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=<bucket> \
                                 <[--max-read-ops=<num ops>] [--max-read-bytes=<num bytes>] \
                                 [--max-write-ops=<num ops>] [--max-write-bytes=<num bytes>] \
                                 [--max-list-ops=<num ops>] [--max-delete-ops=<num ops>]>

An example of using ``radosgw-admin ratelimit set`` to set a rate limit for a
bucket might look like this: 

.. prompt:: bash #

   radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=mybucket --max-read-ops=1024 --max-write-bytes=10240


A value of ``0`` assigned to ``--max-read-ops``, ``--max-read-bytes``,
``--max-write-ops``, or ``-max-write-bytes`` disables the specified bucket rate
limit. 

Get Bucket Rate Limit
---------------------

The ``radosgw-admin ratelimit get`` command returns the current configured rate
limit parameters.

The following is the general form of the command that returns the current
configured limit parameters:

.. prompt:: bash #

   radosgw-admin ratelimit get --ratelimit-scope=bucket --bucket=<bucket>

An example of using ``radosgw-admin ratelimit get`` to return the rate limit
parameters for a bucket might look like this:

.. prompt:: bash #

   radosgw-admin ratelimit get --ratelimit-scope=bucket --bucket=mybucket

A value of ``0`` assigned to ``--max-read-ops``, ``--max-read-bytes``,
``--max-write-ops``, or ``--max-write-bytes`` disables the specified rate
limit.


Enable and Disable Bucket Rate Limit
------------------------------------

After you set a bucket rate limit, you can enable it. The following is the
general form of the ``radosgw-admin ratelimit enable`` command that enables
bucket rate limits: 

.. prompt:: bash #

   radosgw-admin ratelimit enable --ratelimit-scope=bucket --bucket=<bucket>

An enabled bucket rate limit can be disabled by running a command of the following form:

.. prompt:: bash #

   radosgw-admin ratelimit disable --ratelimit-scope=bucket --bucket=mybucket

Reading and Writing Global Rate Limit Configuration
---------------------------------------------------

You can read and write global rate limit settings in the period's configuration.
To view the global rate limit settings, run the following command:

.. prompt:: bash #

   radosgw-admin global ratelimit get

The global rate limit settings can be manipulated with the ``global ratelimit``
counterparts of the ``ratelimit set``, ``ratelimit enable``, and ``ratelimit
disable`` commands. Per-user and per-bucket ratelimit configurations override
the global configuration:

.. prompt:: bash #

   radosgw-admin global ratelimit set --ratelimit-scope bucket --max-read-ops=1024
   radosgw-admin global ratelimit enable --ratelimit-scope bucket

The global rate limit can be used to configure the scope of the rate limit for
all authenticated users:

.. prompt:: bash #

   radosgw-admin global ratelimit set --ratelimit-scope user --max-read-ops=1024
   radosgw-admin global ratelimit enable --ratelimit-scope user

The global rate limit can be used to configure the scope of the rate limit for
all unauthenticated users:

.. prompt:: bash #
  
   radosgw-admin global ratelimit set --ratelimit-scope=anonymous --max-read-ops=1024
   radosgw-admin global ratelimit enable --ratelimit-scope=anonymous

.. note:: In a multisite configuration where a realm and a period are present,
   any changes to the global rate limit must be committed using ``period update
   --commit``. If no period is present, the RGW instances must be restarted
   for the changes to take effect.

Usage
=====

The Ceph Object Gateway logs the usage of each user. You can track the usage of
each user within a specified date range.

- Add ``rgw_enable_usage_log = true`` in the ``[client.rgw]`` section of
  ``ceph.conf`` and restart the ``radosgw`` service. 

  .. note:: Until Ceph has a linkable macro that handles all the many ways that options can be set, we advise that you set ``rgw_enable_usage_log = true`` in central config or in ``ceph.conf`` and restart all RGWs.


Options include: 

- **Start Date:** The ``--start-date`` option allows you to filter usage
  stats from a specified start date and an optional start time
  (**format:** ``yyyy-mm-dd [HH:MM:SS]``).

- **End Date:** The ``--end-date`` option allows you to filter usage up
  to a particular end date and an optional end time
  (**format:** ``yyyy-mm-dd [HH:MM:SS]``). 
  
- **Log Entries:** The ``--show-log-entries`` option allows you to specify
  whether to include log entries with the usage stats 
  (options: ``true`` | ``false``).

.. note:: You can specify time to a precision of minutes and seconds, but the
   specified time is stored only with a one-hour resolution.

Show Usage
----------

To show usage statistics, use the ``radosgw-admin usage show`` command. To show
usage for a particular user, you must specify a user ID. You can also specify a
start date, end date, and whether to show log entries. The following is an example
of such a command:

.. prompt:: bash #

   radosgw-admin usage show --uid=johndoe --start-date=2012-03-01 --end-date=2012-04-01

You can show a summary of usage information for all users by omitting the user
ID, as in the following example command:

.. prompt:: bash #

   radosgw-admin usage show --show-log-entries=false


Trim Usage
----------

Usage logs can consume significant storage space, especially over time and with
heavy use. You can trim the usage logs for all users and for specific users.
You can also specify date ranges for trim operations, as in the following
example commands:

.. prompt:: bash #

   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

Usage Log Key Transition
-------------------------

.. versionadded:: Umbrella

The ``rgw_usage_log_key_transition`` configuration option controls how RGW handles
usage log keys in the Umbrella release. This option is enabled by default to ensure
compatibility with existing usage logs.

In previous versions, usage log keys for user/payer IDs starting with '0' could interfere
with time-based log keys, causing issues with log trimming and iteration. The new key format
adds a '~' prefix to prevent this conflict.

When ``rgw_usage_log_key_transition`` is enabled (default: ``true``), RGW will:

- Handle both old and new usage log key formats
- Automatically migrate old keys to the new format during normal operations
- Ensure proper trimming and reading of usage logs during the transition period

You can disable this option once all old usage logs have been migrated to improve performance:

.. prompt:: bash #

   ceph config set client.rgw rgw_usage_log_key_transition false

.. note:: Only disable ``rgw_usage_log_key_transition`` after confirming that no old
   usage log entries remain in your system, as this will prevent RGW from handling
   the old key format and may result in incomplete usage statistics or failed trim operations.