diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/radosgw/admin.rst | 715 |
1 files changed, 715 insertions, 0 deletions
diff --git a/doc/radosgw/admin.rst b/doc/radosgw/admin.rst new file mode 100644 index 000000000..8d70252fe --- /dev/null +++ b/doc/radosgw/admin.rst @@ -0,0 +1,715 @@ +============= + 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:: + + radosgw-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", + "display_name": "John Doe", + "email": "john@example.com", + "suspended": 0, + "max_buckets": 1000, + "subusers": [], + "keys": [ + { "user": "johndoe", + "access_key": "11BS02LGFB6AL6H1ADMW", + "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}], + "swift_keys": [], + "caps": [], + "op_mask": "read, write, delete", + "default_placement": "", + "placement_tags": [], + "bucket_quota": { "enabled": false, + "max_size_kb": -1, + "max_objects": -1}, + "user_quota": { "enabled": false, + "max_size_kb": -1, + "max_objects": -1}, + "temp_url_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 JSON escape (``\``) character, and some clients + do not know how to handle JSON escape characters. Remedies include + removing the JSON escape character (``\``), encapsulating the string + in quotes, regenerating the key and ensuring that it + does not have a JSON escape character or specify the key and secret + manually. + + +Create a Subuser +---------------- + +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. :: + + radosgw-admin subuser create --uid={uid} --subuser={uid} --access=[ read | write | readwrite | full ] + +For example:: + + radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full + + +.. note:: ``full`` is not ``readwrite``, as it also includes the access control policy. + +.. code-block:: javascript + + { "user_id": "johndoe", + "display_name": "John Doe", + "email": "john@example.com", + "suspended": 0, + "max_buckets": 1000, + "subusers": [ + { "id": "johndoe:swift", + "permissions": "full-control"}], + "keys": [ + { "user": "johndoe", + "access_key": "11BS02LGFB6AL6H1ADMW", + "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}], + "swift_keys": [], + "caps": [], + "op_mask": "read, write, delete", + "default_placement": "", + "placement_tags": [], + "bucket_quota": { "enabled": false, + "max_size_kb": -1, + "max_objects": -1}, + "user_quota": { "enabled": false, + "max_size_kb": -1, + "max_objects": -1}, + "temp_url_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``, user ID and the subuser ID. For example:: + + radosgw-admin subuser modify --uid=johndoe --subuser=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 --subuser=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. + + +Remove a Subuser +---------------- + +When you remove a sub user, you are removing access to the Swift interface. +The user will remain in the system. To remove the subuser, specify +``subuser rm`` and the subuser ID. :: + + radosgw-admin subuser rm --subuser=johndoe:swift + + + +Options include: + +- **Purge Keys:** The ``--purge-keys`` option purges all keys associated + to the UID. + + +Add / Remove a Key +------------------------ + +Both users and subusers require the key to access the S3 or Swift interface. To +use S3, the user needs a key pair which is composed of an access key and a +secret key. On the other hand, to use Swift, the user typically needs a secret +key (password), and use it together with the associated user ID. You may create +a key and either specify or generate the access key and/or secret key. You may +also remove a key. Options include: + +- ``--key-type=<type>`` specifies the key type. The options are: s3, swift +- ``--access-key=<key>`` manually specifies an S3 access key. +- ``--secret-key=<key>`` manually specifies a S3 secret key or a Swift secret key. +- ``--gen-access-key`` automatically generates a random S3 access key. +- ``--gen-secret`` automatically generates a random S3 secret key or a random Swift secret key. + +An example how to add a specified S3 key pair for a user. :: + + 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": "foo@example.com", + "suspended": 0, + "keys": [ + { "user": "foo", + "access_key": "fooAccessKey", + "secret_key": "fooSecretKey"}], + } + +Note that you may create multiple S3 key pairs for a user. + +To attach a specified swift secret key for a subuser. :: + + radosgw-admin key create --subuser=foo:bar --key-type=swift --secret-key barSecret + +.. code-block:: javascript + + { "user_id": "foo", + "rados_uid": 0, + "display_name": "foo", + "email": "foo@example.com", + "suspended": 0, + "subusers": [ + { "id": "foo:bar", + "permissions": "full-control"}], + "swift_keys": [ + { "user": "foo:bar", + "secret_key": "asfghjghghmgm"}]} + +Note that a subuser can have only one swift secret key. + +Subusers can also be used with S3 APIs if the subuser is associated with a S3 key pair. :: + + 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": "foo@example.com", + "suspended": 0, + "subusers": [ + { "id": "foo:bar", + "permissions": "full-control"}], + "keys": [ + { "user": "foo:bar", + "access_key": "barAccessKey", + "secret_key": "barSecretKey"}], + } + + +To remove a S3 key pair, specify the access key. :: + + radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey + +To remove the swift secret key. :: + + radosgw-admin key rm --subuser=foo:bar --key-type=swift + + +Add / Remove Admin Capabilities +------------------------------- + +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={uid} --caps={caps} + + +You can add read, write or all capabilities to users, buckets, metadata and +usage (utilization). For example:: + + --caps="[users|buckets|metadata|usage|zone|amz-cache|info|bilog|mdlog|datalog|user-policy|oidc-provider|roles|ratelimit]=[*|read|write|read, write]" + +For example:: + + radosgw-admin caps add --uid=johndoe --caps="users=*;buckets=*" + + +To remove administrative capabilities from a user, execute the following:: + + radosgw-admin caps rm --uid=johndoe --caps={caps} + + +Quota Management +================ + +The Ceph Object Gateway enables 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. + +- **Bucket:** The ``--bucket`` option allows you to specify a quota for + buckets the user owns. + +- **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``. Bucket quotas apply to buckets a + user owns. User quotas apply to a user. + + +Set User Quota +-------------- + +Before you enable a quota, you must first set the quota parameters. +For example:: + + radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>] + +For example:: + + radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024B + + +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 --quota-scope=user --uid=<uid> + +You may disable an enabled user quota. For example:: + + radosgw-admin quota disable --quota-scope=user --uid=<uid> + + +Set Bucket Quota +---------------- + +Bucket quotas apply to the buckets owned by the specified ``uid``. They are +independent of the user. :: + + radosgw-admin quota set --uid=<uid> --quota-scope=bucket [--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 Bucket Quota +--------------------------- + +Once you set a bucket quota, you may enable it. For example:: + + radosgw-admin quota enable --quota-scope=bucket --uid=<uid> + +You may disable an enabled bucket quota. For example:: + + radosgw-admin quota disable --quota-scope=bucket --uid=<uid> + + +Get 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> + + +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 + +.. _rgw_user_usage_stats: + +Get User Usage Stats +-------------------- + +To see how much of the quota a user has consumed, execute the following:: + + radosgw-admin user stats --uid=<uid> + +.. note:: You should execute ``radosgw-admin user stats`` with the + ``--sync-stats`` option to receive the latest data. + +Default Quotas +-------------- + +You can set default quotas in the config. These defaults are used when +creating a new user and have no effect on existing users. If the +relevant default quota is set in config, then that quota is set on the +new user, and that quota is enabled. See ``rgw bucket default quota max objects``, +``rgw bucket default quota max size``, ``rgw user default quota max objects``, and +``rgw user default quota max size`` in `Ceph Object Gateway Config Reference`_ + +Quota Cache +----------- + +Quota statistics are cached on each RGW instance. If there are multiple +instances, then the cache can keep quotas from being perfectly enforced, as +each instance will have a different view of quotas. The options that control +this are ``rgw bucket quota ttl``, ``rgw user quota bucket sync interval`` and +``rgw user quota sync interval``. The higher these values are, the more +efficient quota operations are, but the more out-of-sync multiple instances +will be. The lower these values are, the closer to perfect enforcement +multiple instances will achieve. If all three are 0, then quota caching is +effectively disabled, and multiple instances will have perfect quota +enforcement. See `Ceph Object Gateway Config Reference`_ + +Reading / Writing Global Quotas +------------------------------- + +You can read and write global quota settings in the period configuration. To +view the global quota settings:: + + radosgw-admin global quota get + +The global quota settings can be manipulated with the ``global quota`` +counterparts of the ``quota set``, ``quota enable``, and ``quota disable`` +commands. :: + + 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 there is no period present, the rados gateway(s) must + be restarted for the changes to take effect. + + +Rate Limit Management +===================== + +The Ceph Object Gateway makes it possible to set rate limits on users and +buckets. "Rate limit" includes the maximum number of read operations (read +ops) and write operations (write ops) per minute and the number of bytes per +minute that can be written or read per user or per bucket. + +Operations that use the ``GET`` method or the ``HEAD`` method in their REST +requests are "read requests". All other requests are "write requests". + +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 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. 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 minute. If "user A" is subject to a 1-byte +read limit per minute 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 minutes. 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 minute per RGW. A 0 value disables this setting (which means unlimited access). + +- **Maximum Read Bytes:** The ``--max-read-bytes`` setting allows you to specify + the maximum number of read bytes per minute per RGW. A 0 value disables this setting (which means unlimited access). + +- **Maximum Write Ops:** The ``--max-write-ops`` setting allows you to specify + the maximum number of write ops per minute per RGW. A 0 value disables this setting (which means unlimited access). + +- **Maximum Write Bytes:** The ``--max-write-bytes`` setting allows you to specify + the maximum number of write bytes per minute per RGW. A 0 value disables this setting (which means unlimited access). + +- **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. Anonymous applies to an unauthenticated user. + Anonymous scope is only available for global rate limit. + + +Set User Rate Limit +------------------- + +Before you enable a rate limit, you must first set the rate limit parameters. +For example:: + + 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>]> + +For example:: + + radosgw-admin ratelimit set --ratelimit-scope=user --uid=johndoe --max-read-ops=1024 --max-write-bytes=10240 + + +A 0 value for num ops and / or num bytes means that the +specific rate limit attribute check is disabled. + +Get User Rate Limit +------------------- + +Get the current configured rate limit parameters +For example:: + + radosgw-admin ratelimit get --ratelimit-scope=user --uid=<uid> + +For example:: + + radosgw-admin ratelimit get --ratelimit-scope=user --uid=johndoe + + +A 0 value for num ops and / or num bytes means that the +specific rate limit attribute check is disabled. + + +Enable/Disable User Rate Limit +------------------------------ + +Once you set a user rate limit, you may enable it. For example:: + + radosgw-admin ratelimit enable --ratelimit-scope=user --uid=<uid> + +You may disable an enabled user rate limit. For example:: + + 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. +For example:: + + 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>]> + +For example:: + + radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=mybucket --max-read-ops=1024 --max-write-bytes=10240 + + +A 0 value for num ops and / or num bytes means that the +specific rate limit attribute check is disabled. + +Get Bucket Rate Limit +--------------------- + +Get the current configured rate limit parameters +For example:: + + radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=<bucket> + +For example:: + + radosgw-admin ratelimit get --ratelimit-scope=bucket --bucket=mybucket + + +A 0 value for num ops and / or num bytes means that the +specific rate limit attribute check is disabled. + + +Enable/Disable Bucket Rate Limit +-------------------------------- + +Once you set a bucket rate limit, you may enable it. For example:: + + radosgw-admin ratelimit enable --ratelimit-scope=bucket --bucket=<bucket> + +You may disable an enabled bucket rate limit. For example:: + + radosgw-admin ratelimit disable --ratelimit-scope=bucket --uid=mybucket + + +Reading / Writing Global Rate Limit Configuration +------------------------------------------------- + +You can read and write global rate limit settings in the period configuration. To +view the global rate limit settings:: + + 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 configuration is overriding the global configuration:: + + 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 configure rate limit scope for all authenticated users:: + + 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 configure rate limit scope for all unauthenticated users:: + + 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 there is a realm and period + present, changes to the global rate limit must be committed using ``period + update --commit``. If there is no period present, the rados gateway(s) must + be restarted for the changes to take effect. + +Usage +===== + +The Ceph Object Gateway logs usage for each user. You can track +user usage within date ranges too. + +- Add ``rgw enable usage log = true`` in [client.rgw] section of ceph.conf and restart the radosgw service. + +Options include: + +- **Start Date:** The ``--start-date`` option allows you to filter usage + stats from a particular 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 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 or not to include log entries with the usage stats + (options: ``true`` | ``false``). + +.. note:: You may specify time with minutes and seconds, but it is stored + with 1 hour resolution. + + +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=johndoe --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/ +.. _Ceph Object Gateway Config Reference: ../config-ref/ |