]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ============= |
2 | Admin Guide | |
3 | ============= | |
4 | ||
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. | |
8 | ||
9 | ||
10 | User Management | |
11 | =============== | |
12 | ||
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. | |
17 | ||
18 | There are two user types: | |
19 | ||
20 | - **User:** The term 'user' reflects a user of the S3 interface. | |
21 | ||
22 | - **Subuser:** The term 'subuser' reflects a user of the Swift interface. A subuser | |
23 | is associated to a user . | |
24 | ||
f91f0fd5 TL |
25 | .. ditaa:: |
26 | +---------+ | |
7c673cae FG |
27 | | User | |
28 | +----+----+ | |
29 | | | |
30 | | +-----------+ | |
31 | +-----+ Subuser | | |
32 | +-----------+ | |
33 | ||
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``. | |
40 | ||
41 | ||
42 | Create a User | |
43 | ------------- | |
44 | ||
45 | To create a user (S3 interface), execute the following:: | |
46 | ||
47 | radosgw-admin user create --uid={username} --display-name="{display-name}" [--email={email}] | |
48 | ||
49 | For example:: | |
50 | ||
51 | radosgw-admin user create --uid=johndoe --display-name="John Doe" --email=john@example.com | |
52 | ||
53 | .. code-block:: javascript | |
54 | ||
55 | { "user_id": "johndoe", | |
56 | "display_name": "John Doe", | |
57 | "email": "john@example.com", | |
58 | "suspended": 0, | |
59 | "max_buckets": 1000, | |
7c673cae FG |
60 | "subusers": [], |
61 | "keys": [ | |
62 | { "user": "johndoe", | |
63 | "access_key": "11BS02LGFB6AL6H1ADMW", | |
64 | "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}], | |
65 | "swift_keys": [], | |
66 | "caps": [], | |
67 | "op_mask": "read, write, delete", | |
68 | "default_placement": "", | |
69 | "placement_tags": [], | |
70 | "bucket_quota": { "enabled": false, | |
71 | "max_size_kb": -1, | |
72 | "max_objects": -1}, | |
73 | "user_quota": { "enabled": false, | |
74 | "max_size_kb": -1, | |
75 | "max_objects": -1}, | |
76 | "temp_url_keys": []} | |
77 | ||
78 | Creating a user also creates an ``access_key`` and ``secret_key`` entry for use | |
79 | with any S3 API-compatible client. | |
80 | ||
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 | |
87 | manually. | |
88 | ||
89 | ||
90 | Create a Subuser | |
91 | ---------------- | |
92 | ||
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. :: | |
95 | ||
96 | radosgw-admin subuser create --uid={uid} --subuser={uid} --access=[ read | write | readwrite | full ] | |
97 | ||
98 | For example:: | |
99 | ||
100 | radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full | |
101 | ||
102 | ||
103 | .. note:: ``full`` is not ``readwrite``, as it also includes the access control policy. | |
104 | ||
105 | .. code-block:: javascript | |
106 | ||
107 | { "user_id": "johndoe", | |
108 | "display_name": "John Doe", | |
109 | "email": "john@example.com", | |
110 | "suspended": 0, | |
111 | "max_buckets": 1000, | |
7c673cae FG |
112 | "subusers": [ |
113 | { "id": "johndoe:swift", | |
114 | "permissions": "full-control"}], | |
115 | "keys": [ | |
116 | { "user": "johndoe", | |
117 | "access_key": "11BS02LGFB6AL6H1ADMW", | |
118 | "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}], | |
119 | "swift_keys": [], | |
120 | "caps": [], | |
121 | "op_mask": "read, write, delete", | |
122 | "default_placement": "", | |
123 | "placement_tags": [], | |
124 | "bucket_quota": { "enabled": false, | |
125 | "max_size_kb": -1, | |
126 | "max_objects": -1}, | |
127 | "user_quota": { "enabled": false, | |
128 | "max_size_kb": -1, | |
129 | "max_objects": -1}, | |
130 | "temp_url_keys": []} | |
131 | ||
132 | ||
133 | Get User Info | |
134 | ------------- | |
135 | ||
136 | To get information about a user, you must specify ``user info`` and the user ID | |
137 | (``--uid={username}``) . :: | |
138 | ||
139 | radosgw-admin user info --uid=johndoe | |
140 | ||
141 | ||
142 | ||
143 | Modify User Info | |
144 | ---------------- | |
145 | ||
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:: | |
149 | ||
150 | radosgw-admin user modify --uid=johndoe --display-name="John E. Doe" | |
151 | ||
9f95a23c | 152 | To modify subuser values, specify ``subuser modify``, user ID and the subuser ID. For example:: |
7c673cae | 153 | |
9f95a23c | 154 | radosgw-admin subuser modify --uid=johndoe --subuser=johndoe:swift --access=full |
7c673cae FG |
155 | |
156 | ||
157 | User Enable/Suspend | |
158 | ------------------- | |
159 | ||
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. :: | |
163 | ||
164 | radosgw-admin user suspend --uid=johndoe | |
165 | ||
166 | To re-enable a suspended user, specify ``user enable`` and the user ID. :: | |
167 | ||
168 | radosgw-admin user enable --uid=johndoe | |
169 | ||
170 | .. note:: Disabling the user disables the subuser. | |
171 | ||
172 | ||
173 | Remove a User | |
174 | ------------- | |
175 | ||
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. :: | |
179 | ||
180 | radosgw-admin user rm --uid=johndoe | |
181 | ||
182 | To remove the subuser only, specify ``subuser rm`` and the subuser ID. :: | |
183 | ||
184 | radosgw-admin subuser rm --subuser=johndoe:swift | |
185 | ||
186 | ||
187 | Options include: | |
188 | ||
189 | - **Purge Data:** The ``--purge-data`` option purges all data associated | |
190 | to the UID. | |
191 | ||
192 | - **Purge Keys:** The ``--purge-keys`` option purges all keys associated | |
193 | to the UID. | |
194 | ||
195 | ||
196 | Remove a Subuser | |
197 | ---------------- | |
198 | ||
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. :: | |
202 | ||
203 | radosgw-admin subuser rm --subuser=johndoe:swift | |
204 | ||
205 | ||
206 | ||
207 | Options include: | |
208 | ||
209 | - **Purge Keys:** The ``--purge-keys`` option purges all keys associated | |
210 | to the UID. | |
211 | ||
212 | ||
213 | Add / Remove a Key | |
214 | ------------------------ | |
215 | ||
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: | |
222 | ||
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. | |
11fdf7f2 TL |
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. | |
7c673cae FG |
228 | |
229 | An example how to add a specified S3 key pair for a user. :: | |
230 | ||
231 | radosgw-admin key create --uid=foo --key-type=s3 --access-key fooAccessKey --secret-key fooSecretKey | |
232 | ||
233 | .. code-block:: javascript | |
234 | ||
235 | { "user_id": "foo", | |
236 | "rados_uid": 0, | |
237 | "display_name": "foo", | |
238 | "email": "foo@example.com", | |
239 | "suspended": 0, | |
240 | "keys": [ | |
241 | { "user": "foo", | |
242 | "access_key": "fooAccessKey", | |
243 | "secret_key": "fooSecretKey"}], | |
244 | } | |
245 | ||
246 | Note that you may create multiple S3 key pairs for a user. | |
247 | ||
248 | To attach a specified swift secret key for a subuser. :: | |
249 | ||
250 | radosgw-admin key create --subuser=foo:bar --key-type=swift --secret-key barSecret | |
251 | ||
252 | .. code-block:: javascript | |
253 | ||
254 | { "user_id": "foo", | |
255 | "rados_uid": 0, | |
256 | "display_name": "foo", | |
257 | "email": "foo@example.com", | |
258 | "suspended": 0, | |
259 | "subusers": [ | |
260 | { "id": "foo:bar", | |
261 | "permissions": "full-control"}], | |
262 | "swift_keys": [ | |
263 | { "user": "foo:bar", | |
264 | "secret_key": "asfghjghghmgm"}]} | |
265 | ||
266 | Note that a subuser can have only one swift secret key. | |
267 | ||
268 | Subusers can also be used with S3 APIs if the subuser is associated with a S3 key pair. :: | |
269 | ||
270 | radosgw-admin key create --subuser=foo:bar --key-type=s3 --access-key barAccessKey --secret-key barSecretKey | |
271 | ||
272 | .. code-block:: javascript | |
273 | ||
274 | { "user_id": "foo", | |
275 | "rados_uid": 0, | |
276 | "display_name": "foo", | |
277 | "email": "foo@example.com", | |
278 | "suspended": 0, | |
279 | "subusers": [ | |
280 | { "id": "foo:bar", | |
281 | "permissions": "full-control"}], | |
282 | "keys": [ | |
283 | { "user": "foo:bar", | |
284 | "access_key": "barAccessKey", | |
285 | "secret_key": "barSecretKey"}], | |
286 | } | |
287 | ||
288 | ||
289 | To remove a S3 key pair, specify the access key. :: | |
290 | ||
291 | radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey | |
292 | ||
293 | To remove the swift secret key. :: | |
294 | ||
f67539c2 | 295 | radosgw-admin key rm --subuser=foo:bar --key-type=swift |
7c673cae FG |
296 | |
297 | ||
298 | Add / Remove Admin Capabilities | |
299 | ------------------------------- | |
300 | ||
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. | |
305 | ||
306 | To add administrative capabilities to a user, execute the following:: | |
307 | ||
308 | radosgw-admin caps add --uid={uid} --caps={caps} | |
309 | ||
310 | ||
311 | You can add read, write or all capabilities to users, buckets, metadata and | |
312 | usage (utilization). For example:: | |
313 | ||
20effc67 | 314 | --caps="[users|buckets|metadata|usage|zone|amz-cache|info|bilog|mdlog|datalog|user-policy|oidc-provider|roles|ratelimit]=[*|read|write|read, write]" |
7c673cae FG |
315 | |
316 | For example:: | |
317 | ||
318 | radosgw-admin caps add --uid=johndoe --caps="users=*;buckets=*" | |
319 | ||
320 | ||
321 | To remove administrative capabilities from a user, execute the following:: | |
322 | ||
323 | radosgw-admin caps rm --uid=johndoe --caps={caps} | |
324 | ||
325 | ||
326 | Quota Management | |
327 | ================ | |
328 | ||
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. | |
332 | ||
333 | - **Bucket:** The ``--bucket`` option allows you to specify a quota for | |
334 | buckets the user owns. | |
335 | ||
336 | - **Maximum Objects:** The ``--max-objects`` setting allows you to specify | |
337 | the maximum number of objects. A negative value disables this setting. | |
338 | ||
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. | |
341 | ||
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. | |
345 | ||
346 | ||
347 | Set User Quota | |
348 | -------------- | |
349 | ||
350 | Before you enable a quota, you must first set the quota parameters. | |
351 | For example:: | |
352 | ||
353 | radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>] | |
354 | ||
355 | For example:: | |
356 | ||
357 | radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024B | |
358 | ||
359 | ||
360 | A negative value for num objects and / or max size means that the | |
361 | specific quota attribute check is disabled. | |
362 | ||
363 | ||
364 | Enable/Disable User Quota | |
365 | ------------------------- | |
366 | ||
367 | Once you set a user quota, you may enable it. For example:: | |
368 | ||
369 | radosgw-admin quota enable --quota-scope=user --uid=<uid> | |
370 | ||
371 | You may disable an enabled user quota. For example:: | |
372 | ||
373 | radosgw-admin quota disable --quota-scope=user --uid=<uid> | |
374 | ||
375 | ||
376 | Set Bucket Quota | |
377 | ---------------- | |
378 | ||
379 | Bucket quotas apply to the buckets owned by the specified ``uid``. They are | |
380 | independent of the user. :: | |
381 | ||
382 | radosgw-admin quota set --uid=<uid> --quota-scope=bucket [--max-objects=<num objects>] [--max-size=<max size] | |
383 | ||
384 | A negative value for num objects and / or max size means that the | |
385 | specific quota attribute check is disabled. | |
386 | ||
387 | ||
388 | Enable/Disable Bucket Quota | |
389 | --------------------------- | |
390 | ||
391 | Once you set a bucket quota, you may enable it. For example:: | |
392 | ||
393 | radosgw-admin quota enable --quota-scope=bucket --uid=<uid> | |
394 | ||
395 | You may disable an enabled bucket quota. For example:: | |
396 | ||
397 | radosgw-admin quota disable --quota-scope=bucket --uid=<uid> | |
398 | ||
399 | ||
400 | Get Quota Settings | |
401 | ------------------ | |
402 | ||
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:: | |
406 | ||
407 | radosgw-admin user info --uid=<uid> | |
408 | ||
409 | ||
410 | Update Quota Stats | |
411 | ------------------ | |
412 | ||
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. :: | |
416 | ||
417 | radosgw-admin user stats --uid=<uid> --sync-stats | |
418 | ||
9f95a23c | 419 | .. _rgw_user_usage_stats: |
7c673cae FG |
420 | |
421 | Get User Usage Stats | |
422 | -------------------- | |
423 | ||
424 | To see how much of the quota a user has consumed, execute the following:: | |
425 | ||
426 | radosgw-admin user stats --uid=<uid> | |
427 | ||
428 | .. note:: You should execute ``radosgw-admin user stats`` with the | |
429 | ``--sync-stats`` option to receive the latest data. | |
430 | ||
431 | Default Quotas | |
432 | -------------- | |
433 | ||
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`_ | |
440 | ||
31f18b77 FG |
441 | Quota Cache |
442 | ----------- | |
443 | ||
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`_ | |
454 | ||
7c673cae FG |
455 | Reading / Writing Global Quotas |
456 | ------------------------------- | |
457 | ||
458 | You can read and write global quota settings in the period configuration. To | |
459 | view the global quota settings:: | |
460 | ||
461 | radosgw-admin global quota get | |
462 | ||
463 | The global quota settings can be manipulated with the ``global quota`` | |
464 | counterparts of the ``quota set``, ``quota enable``, and ``quota disable`` | |
465 | commands. :: | |
466 | ||
467 | radosgw-admin global quota set --quota-scope bucket --max-objects 1024 | |
468 | radosgw-admin global quota enable --quota-scope bucket | |
469 | ||
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. | |
474 | ||
475 | ||
20effc67 TL |
476 | Rate Limit Management |
477 | ===================== | |
478 | ||
aee94f69 TL |
479 | The Ceph Object Gateway makes it possible to set rate limits on users and |
480 | buckets. "Rate limit" includes the maximum number of read operations (read | |
481 | ops) and write operations (write ops) per minute and the number of bytes per | |
482 | minute that can be written or read per user or per bucket. | |
483 | ||
484 | Operations that use the ``GET`` method or the ``HEAD`` method in their REST | |
485 | requests are "read requests". All other requests are "write requests". | |
486 | ||
487 | Each object gateway tracks per-user metrics separately from bucket metrics. | |
488 | These metrics are not shared with other gateways. The configured limits should | |
489 | be divided by the number of active object gateways. For example, if "user A" is | |
490 | to be be limited to 10 ops per minute and there are two object gateways in the | |
491 | cluster, then the limit on "user A" should be ``5`` (10 ops per minute / 2 | |
492 | RGWs). If the requests are **not** balanced between RGWs, the rate limit might | |
493 | be underutilized. For example: if the ops limit is ``5`` and there are two | |
494 | RGWs, **but** the Load Balancer sends load to only one of those RGWs, the | |
495 | effective limit is 5 ops, because this limit is enforced per RGW. If the rate | |
496 | limit that has been set for the bucket has been reached but the rate limit that | |
497 | has been set for the user has not been reached, then the request is cancelled. | |
498 | The contrary holds as well: if the rate limit that has been set for the user | |
499 | has been reached but the rate limit that has been set for the bucket has not | |
500 | been reached, then the request is cancelled. | |
501 | ||
502 | The accounting of bandwidth happens only after a request has been accepted. | |
503 | This means that requests will proceed even if the bucket rate limit or user | |
504 | rate limit is reached during the execution of the request. The RGW keeps track | |
505 | of a "debt" consisting of bytes used in excess of the configured value; users | |
506 | or buckets that incur this kind of debt are prevented from sending more | |
507 | requests until the "debt" has been repaid. The maximum size of the "debt" is | |
508 | twice the max-read/write-bytes per minute. If "user A" is subject to a 1-byte | |
509 | read limit per minute and they attempt to GET an object that is 1 GB in size, | |
510 | then the ``GET`` action will fail. After "user A" has completed this 1 GB | |
511 | operation, RGW blocks the user's requests for up to two minutes. After this | |
512 | time has elapsed, "user A" will be able to send ``GET`` requests again. | |
20effc67 TL |
513 | |
514 | ||
515 | - **Bucket:** The ``--bucket`` option allows you to specify a rate limit for a | |
516 | bucket. | |
517 | ||
518 | - **User:** The ``--uid`` option allows you to specify a rate limit for a | |
519 | user. | |
520 | ||
521 | - **Maximum Read Ops:** The ``--max-read-ops`` setting allows you to specify | |
522 | the maximum number of read ops per minute per RGW. A 0 value disables this setting (which means unlimited access). | |
523 | ||
524 | - **Maximum Read Bytes:** The ``--max-read-bytes`` setting allows you to specify | |
525 | the maximum number of read bytes per minute per RGW. A 0 value disables this setting (which means unlimited access). | |
526 | ||
527 | - **Maximum Write Ops:** The ``--max-write-ops`` setting allows you to specify | |
528 | the maximum number of write ops per minute per RGW. A 0 value disables this setting (which means unlimited access). | |
529 | ||
530 | - **Maximum Write Bytes:** The ``--max-write-bytes`` setting allows you to specify | |
531 | the maximum number of write bytes per minute per RGW. A 0 value disables this setting (which means unlimited access). | |
532 | ||
533 | - **Rate Limit Scope:** The ``--ratelimit-scope`` option sets the scope for the rate limit. | |
534 | The options are ``bucket`` , ``user`` and ``anonymous``. Bucket rate limit apply to buckets. | |
535 | The user rate limit applies to a user. Anonymous applies to an unauthenticated user. | |
536 | Anonymous scope is only available for global rate limit. | |
537 | ||
538 | ||
539 | Set User Rate Limit | |
540 | ------------------- | |
541 | ||
542 | Before you enable a rate limit, you must first set the rate limit parameters. | |
543 | For example:: | |
544 | ||
545 | radosgw-admin ratelimit set --ratelimit-scope=user --uid=<uid> <[--max-read-ops=<num ops>] [--max-read-bytes=<num bytes>] | |
546 | [--max-write-ops=<num ops>] [--max-write-bytes=<num bytes>]> | |
547 | ||
548 | For example:: | |
549 | ||
550 | radosgw-admin ratelimit set --ratelimit-scope=user --uid=johndoe --max-read-ops=1024 --max-write-bytes=10240 | |
551 | ||
552 | ||
553 | A 0 value for num ops and / or num bytes means that the | |
554 | specific rate limit attribute check is disabled. | |
555 | ||
556 | Get User Rate Limit | |
557 | ------------------- | |
558 | ||
559 | Get the current configured rate limit parameters | |
560 | For example:: | |
561 | ||
562 | radosgw-admin ratelimit get --ratelimit-scope=user --uid=<uid> | |
563 | ||
564 | For example:: | |
565 | ||
566 | radosgw-admin ratelimit get --ratelimit-scope=user --uid=johndoe | |
567 | ||
568 | ||
569 | A 0 value for num ops and / or num bytes means that the | |
570 | specific rate limit attribute check is disabled. | |
571 | ||
572 | ||
573 | Enable/Disable User Rate Limit | |
574 | ------------------------------ | |
575 | ||
576 | Once you set a user rate limit, you may enable it. For example:: | |
577 | ||
578 | radosgw-admin ratelimit enable --ratelimit-scope=user --uid=<uid> | |
579 | ||
580 | You may disable an enabled user rate limit. For example:: | |
581 | ||
582 | radosgw-admin ratelimit disable --ratelimit-scope=user --uid=johndoe | |
583 | ||
584 | ||
585 | Set Bucket Rate Limit | |
586 | --------------------- | |
587 | ||
588 | Before you enable a rate limit, you must first set the rate limit parameters. | |
589 | For example:: | |
590 | ||
591 | radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=<bucket> <[--max-read-ops=<num ops>] [--max-read-bytes=<num bytes>] | |
592 | [--max-write-ops=<num ops>] [--max-write-bytes=<num bytes>]> | |
593 | ||
594 | For example:: | |
595 | ||
596 | radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=mybucket --max-read-ops=1024 --max-write-bytes=10240 | |
597 | ||
598 | ||
599 | A 0 value for num ops and / or num bytes means that the | |
600 | specific rate limit attribute check is disabled. | |
601 | ||
602 | Get Bucket Rate Limit | |
603 | --------------------- | |
604 | ||
605 | Get the current configured rate limit parameters | |
606 | For example:: | |
607 | ||
608 | radosgw-admin ratelimit set --ratelimit-scope=bucket --bucket=<bucket> | |
609 | ||
610 | For example:: | |
611 | ||
612 | radosgw-admin ratelimit get --ratelimit-scope=bucket --bucket=mybucket | |
613 | ||
614 | ||
615 | A 0 value for num ops and / or num bytes means that the | |
616 | specific rate limit attribute check is disabled. | |
617 | ||
618 | ||
619 | Enable/Disable Bucket Rate Limit | |
620 | -------------------------------- | |
621 | ||
622 | Once you set a bucket rate limit, you may enable it. For example:: | |
623 | ||
624 | radosgw-admin ratelimit enable --ratelimit-scope=bucket --bucket=<bucket> | |
625 | ||
626 | You may disable an enabled bucket rate limit. For example:: | |
627 | ||
628 | radosgw-admin ratelimit disable --ratelimit-scope=bucket --uid=mybucket | |
629 | ||
630 | ||
631 | Reading / Writing Global Rate Limit Configuration | |
632 | ------------------------------------------------- | |
633 | ||
634 | You can read and write global rate limit settings in the period configuration. To | |
635 | view the global rate limit settings:: | |
636 | ||
1e59de90 | 637 | radosgw-admin global ratelimit get |
20effc67 TL |
638 | |
639 | The global rate limit settings can be manipulated with the ``global ratelimit`` | |
640 | counterparts of the ``ratelimit set``, ``ratelimit enable``, and ``ratelimit disable`` | |
641 | commands. Per user and per bucket ratelimit configuration is overriding the global configuration:: | |
642 | ||
643 | radosgw-admin global ratelimit set --ratelimit-scope bucket --max-read-ops=1024 | |
644 | radosgw-admin global ratelimit enable --ratelimit-scope bucket | |
645 | ||
646 | The global rate limit can configure rate limit scope for all authenticated users:: | |
647 | ||
648 | radosgw-admin global ratelimit set --ratelimit-scope user --max-read-ops=1024 | |
649 | radosgw-admin global ratelimit enable --ratelimit-scope user | |
650 | ||
651 | The global rate limit can configure rate limit scope for all unauthenticated users:: | |
652 | ||
653 | radosgw-admin global ratelimit set --ratelimit-scope=anonymous --max-read-ops=1024 | |
654 | radosgw-admin global ratelimit enable --ratelimit-scope=anonymous | |
655 | ||
656 | .. note:: In a multisite configuration, where there is a realm and period | |
657 | present, changes to the global rate limit must be committed using ``period | |
658 | update --commit``. If there is no period present, the rados gateway(s) must | |
659 | be restarted for the changes to take effect. | |
660 | ||
7c673cae FG |
661 | Usage |
662 | ===== | |
663 | ||
664 | The Ceph Object Gateway logs usage for each user. You can track | |
665 | user usage within date ranges too. | |
666 | ||
667 | - Add ``rgw enable usage log = true`` in [client.rgw] section of ceph.conf and restart the radosgw service. | |
668 | ||
669 | Options include: | |
670 | ||
671 | - **Start Date:** The ``--start-date`` option allows you to filter usage | |
05a536ef TL |
672 | stats from a particular start date and an optional start time |
673 | (**format:** ``yyyy-mm-dd [HH:MM:SS]``). | |
7c673cae FG |
674 | |
675 | - **End Date:** The ``--end-date`` option allows you to filter usage up | |
05a536ef TL |
676 | to a particular date and an optional end time |
677 | (**format:** ``yyyy-mm-dd [HH:MM:SS]``). | |
7c673cae FG |
678 | |
679 | - **Log Entries:** The ``--show-log-entries`` option allows you to specify | |
680 | whether or not to include log entries with the usage stats | |
681 | (options: ``true`` | ``false``). | |
682 | ||
683 | .. note:: You may specify time with minutes and seconds, but it is stored | |
684 | with 1 hour resolution. | |
685 | ||
686 | ||
687 | Show Usage | |
688 | ---------- | |
689 | ||
690 | To show usage statistics, specify the ``usage show``. To show usage for a | |
691 | particular user, you must specify a user ID. You may also specify a start date, | |
692 | end date, and whether or not to show log entries.:: | |
693 | ||
694 | radosgw-admin usage show --uid=johndoe --start-date=2012-03-01 --end-date=2012-04-01 | |
695 | ||
696 | You may also show a summary of usage information for all users by omitting a user ID. :: | |
697 | ||
698 | radosgw-admin usage show --show-log-entries=false | |
699 | ||
700 | ||
701 | Trim Usage | |
702 | ---------- | |
703 | ||
704 | With heavy use, usage logs can begin to take up storage space. You can trim | |
705 | usage logs for all users and for specific users. You may also specify date | |
706 | ranges for trim operations. :: | |
707 | ||
708 | radosgw-admin usage trim --start-date=2010-01-01 --end-date=2010-12-31 | |
709 | radosgw-admin usage trim --uid=johndoe | |
710 | radosgw-admin usage trim --uid=johndoe --end-date=2013-12-31 | |
711 | ||
712 | ||
713 | .. _radosgw-admin: ../../man/8/radosgw-admin/ | |
714 | .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/ | |
715 | .. _Ceph Object Gateway Config Reference: ../config-ref/ |