]>
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 | ||
25 | .. ditaa:: +---------+ | |
26 | | User | | |
27 | +----+----+ | |
28 | | | |
29 | | +-----------+ | |
30 | +-----+ Subuser | | |
31 | +-----------+ | |
32 | ||
33 | You can create, modify, view, suspend and remove users and subusers. In addition | |
34 | to user and subuser IDs, you may add a display name and an email address for a | |
35 | user. You can specify a key and secret, or generate a key and secret | |
36 | automatically. When generating or specifying keys, note that user IDs correspond | |
37 | to an S3 key type and subuser IDs correspond to a swift key type. Swift keys | |
38 | also have access levels of ``read``, ``write``, ``readwrite`` and ``full``. | |
39 | ||
40 | ||
41 | Create a User | |
42 | ------------- | |
43 | ||
44 | To create a user (S3 interface), execute the following:: | |
45 | ||
46 | radosgw-admin user create --uid={username} --display-name="{display-name}" [--email={email}] | |
47 | ||
48 | For example:: | |
49 | ||
50 | radosgw-admin user create --uid=johndoe --display-name="John Doe" --email=john@example.com | |
51 | ||
52 | .. code-block:: javascript | |
53 | ||
54 | { "user_id": "johndoe", | |
55 | "display_name": "John Doe", | |
56 | "email": "john@example.com", | |
57 | "suspended": 0, | |
58 | "max_buckets": 1000, | |
7c673cae FG |
59 | "subusers": [], |
60 | "keys": [ | |
61 | { "user": "johndoe", | |
62 | "access_key": "11BS02LGFB6AL6H1ADMW", | |
63 | "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}], | |
64 | "swift_keys": [], | |
65 | "caps": [], | |
66 | "op_mask": "read, write, delete", | |
67 | "default_placement": "", | |
68 | "placement_tags": [], | |
69 | "bucket_quota": { "enabled": false, | |
70 | "max_size_kb": -1, | |
71 | "max_objects": -1}, | |
72 | "user_quota": { "enabled": false, | |
73 | "max_size_kb": -1, | |
74 | "max_objects": -1}, | |
75 | "temp_url_keys": []} | |
76 | ||
77 | Creating a user also creates an ``access_key`` and ``secret_key`` entry for use | |
78 | with any S3 API-compatible client. | |
79 | ||
80 | .. important:: Check the key output. Sometimes ``radosgw-admin`` | |
81 | generates a JSON escape (``\``) character, and some clients | |
82 | do not know how to handle JSON escape characters. Remedies include | |
83 | removing the JSON escape character (``\``), encapsulating the string | |
84 | in quotes, regenerating the key and ensuring that it | |
85 | does not have a JSON escape character or specify the key and secret | |
86 | manually. | |
87 | ||
88 | ||
89 | Create a Subuser | |
90 | ---------------- | |
91 | ||
92 | To create a subuser (Swift interface) for the user, you must specify the user ID | |
93 | (``--uid={username}``), a subuser ID and the access level for the subuser. :: | |
94 | ||
95 | radosgw-admin subuser create --uid={uid} --subuser={uid} --access=[ read | write | readwrite | full ] | |
96 | ||
97 | For example:: | |
98 | ||
99 | radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full | |
100 | ||
101 | ||
102 | .. note:: ``full`` is not ``readwrite``, as it also includes the access control policy. | |
103 | ||
104 | .. code-block:: javascript | |
105 | ||
106 | { "user_id": "johndoe", | |
107 | "display_name": "John Doe", | |
108 | "email": "john@example.com", | |
109 | "suspended": 0, | |
110 | "max_buckets": 1000, | |
7c673cae FG |
111 | "subusers": [ |
112 | { "id": "johndoe:swift", | |
113 | "permissions": "full-control"}], | |
114 | "keys": [ | |
115 | { "user": "johndoe", | |
116 | "access_key": "11BS02LGFB6AL6H1ADMW", | |
117 | "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}], | |
118 | "swift_keys": [], | |
119 | "caps": [], | |
120 | "op_mask": "read, write, delete", | |
121 | "default_placement": "", | |
122 | "placement_tags": [], | |
123 | "bucket_quota": { "enabled": false, | |
124 | "max_size_kb": -1, | |
125 | "max_objects": -1}, | |
126 | "user_quota": { "enabled": false, | |
127 | "max_size_kb": -1, | |
128 | "max_objects": -1}, | |
129 | "temp_url_keys": []} | |
130 | ||
131 | ||
132 | Get User Info | |
133 | ------------- | |
134 | ||
135 | To get information about a user, you must specify ``user info`` and the user ID | |
136 | (``--uid={username}``) . :: | |
137 | ||
138 | radosgw-admin user info --uid=johndoe | |
139 | ||
140 | ||
141 | ||
142 | Modify User Info | |
143 | ---------------- | |
144 | ||
145 | To modify information about a user, you must specify the user ID (``--uid={username}``) | |
146 | and the attributes you want to modify. Typical modifications are to keys and secrets, | |
147 | email addresses, display names and access levels. For example:: | |
148 | ||
149 | radosgw-admin user modify --uid=johndoe --display-name="John E. Doe" | |
150 | ||
151 | To modify subuser values, specify ``subuser modify`` and the subuser ID. For example:: | |
152 | ||
11fdf7f2 | 153 | radosgw-admin subuser modify --subuser=johndoe:swift --access=full |
7c673cae FG |
154 | |
155 | ||
156 | User Enable/Suspend | |
157 | ------------------- | |
158 | ||
159 | When you create a user, the user is enabled by default. However, you may suspend | |
160 | user privileges and re-enable them at a later time. To suspend a user, specify | |
161 | ``user suspend`` and the user ID. :: | |
162 | ||
163 | radosgw-admin user suspend --uid=johndoe | |
164 | ||
165 | To re-enable a suspended user, specify ``user enable`` and the user ID. :: | |
166 | ||
167 | radosgw-admin user enable --uid=johndoe | |
168 | ||
169 | .. note:: Disabling the user disables the subuser. | |
170 | ||
171 | ||
172 | Remove a User | |
173 | ------------- | |
174 | ||
175 | When you remove a user, the user and subuser are removed from the system. | |
176 | However, you may remove just the subuser if you wish. To remove a user (and | |
177 | subuser), specify ``user rm`` and the user ID. :: | |
178 | ||
179 | radosgw-admin user rm --uid=johndoe | |
180 | ||
181 | To remove the subuser only, specify ``subuser rm`` and the subuser ID. :: | |
182 | ||
183 | radosgw-admin subuser rm --subuser=johndoe:swift | |
184 | ||
185 | ||
186 | Options include: | |
187 | ||
188 | - **Purge Data:** The ``--purge-data`` option purges all data associated | |
189 | to the UID. | |
190 | ||
191 | - **Purge Keys:** The ``--purge-keys`` option purges all keys associated | |
192 | to the UID. | |
193 | ||
194 | ||
195 | Remove a Subuser | |
196 | ---------------- | |
197 | ||
198 | When you remove a sub user, you are removing access to the Swift interface. | |
199 | The user will remain in the system. To remove the subuser, specify | |
200 | ``subuser rm`` and the subuser ID. :: | |
201 | ||
202 | radosgw-admin subuser rm --subuser=johndoe:swift | |
203 | ||
204 | ||
205 | ||
206 | Options include: | |
207 | ||
208 | - **Purge Keys:** The ``--purge-keys`` option purges all keys associated | |
209 | to the UID. | |
210 | ||
211 | ||
212 | Add / Remove a Key | |
213 | ------------------------ | |
214 | ||
215 | Both users and subusers require the key to access the S3 or Swift interface. To | |
216 | use S3, the user needs a key pair which is composed of an access key and a | |
217 | secret key. On the other hand, to use Swift, the user typically needs a secret | |
218 | key (password), and use it together with the associated user ID. You may create | |
219 | a key and either specify or generate the access key and/or secret key. You may | |
220 | also remove a key. Options include: | |
221 | ||
222 | - ``--key-type=<type>`` specifies the key type. The options are: s3, swift | |
223 | - ``--access-key=<key>`` manually specifies an S3 access key. | |
224 | - ``--secret-key=<key>`` manually specifies a S3 secret key or a Swift secret key. | |
11fdf7f2 TL |
225 | - ``--gen-access-key`` automatically generates a random S3 access key. |
226 | - ``--gen-secret`` automatically generates a random S3 secret key or a random Swift secret key. | |
7c673cae FG |
227 | |
228 | An example how to add a specified S3 key pair for a user. :: | |
229 | ||
230 | radosgw-admin key create --uid=foo --key-type=s3 --access-key fooAccessKey --secret-key fooSecretKey | |
231 | ||
232 | .. code-block:: javascript | |
233 | ||
234 | { "user_id": "foo", | |
235 | "rados_uid": 0, | |
236 | "display_name": "foo", | |
237 | "email": "foo@example.com", | |
238 | "suspended": 0, | |
239 | "keys": [ | |
240 | { "user": "foo", | |
241 | "access_key": "fooAccessKey", | |
242 | "secret_key": "fooSecretKey"}], | |
243 | } | |
244 | ||
245 | Note that you may create multiple S3 key pairs for a user. | |
246 | ||
247 | To attach a specified swift secret key for a subuser. :: | |
248 | ||
249 | radosgw-admin key create --subuser=foo:bar --key-type=swift --secret-key barSecret | |
250 | ||
251 | .. code-block:: javascript | |
252 | ||
253 | { "user_id": "foo", | |
254 | "rados_uid": 0, | |
255 | "display_name": "foo", | |
256 | "email": "foo@example.com", | |
257 | "suspended": 0, | |
258 | "subusers": [ | |
259 | { "id": "foo:bar", | |
260 | "permissions": "full-control"}], | |
261 | "swift_keys": [ | |
262 | { "user": "foo:bar", | |
263 | "secret_key": "asfghjghghmgm"}]} | |
264 | ||
265 | Note that a subuser can have only one swift secret key. | |
266 | ||
267 | Subusers can also be used with S3 APIs if the subuser is associated with a S3 key pair. :: | |
268 | ||
269 | radosgw-admin key create --subuser=foo:bar --key-type=s3 --access-key barAccessKey --secret-key barSecretKey | |
270 | ||
271 | .. code-block:: javascript | |
272 | ||
273 | { "user_id": "foo", | |
274 | "rados_uid": 0, | |
275 | "display_name": "foo", | |
276 | "email": "foo@example.com", | |
277 | "suspended": 0, | |
278 | "subusers": [ | |
279 | { "id": "foo:bar", | |
280 | "permissions": "full-control"}], | |
281 | "keys": [ | |
282 | { "user": "foo:bar", | |
283 | "access_key": "barAccessKey", | |
284 | "secret_key": "barSecretKey"}], | |
285 | } | |
286 | ||
287 | ||
288 | To remove a S3 key pair, specify the access key. :: | |
289 | ||
290 | radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey | |
291 | ||
292 | To remove the swift secret key. :: | |
293 | ||
294 | radosgw-admin key rm -subuser=foo:bar --key-type=swift | |
295 | ||
296 | ||
297 | Add / Remove Admin Capabilities | |
298 | ------------------------------- | |
299 | ||
300 | The Ceph Storage Cluster provides an administrative API that enables users to | |
301 | execute administrative functions via the REST API. By default, users do NOT have | |
302 | access to this API. To enable a user to exercise administrative functionality, | |
303 | provide the user with administrative capabilities. | |
304 | ||
305 | To add administrative capabilities to a user, execute the following:: | |
306 | ||
307 | radosgw-admin caps add --uid={uid} --caps={caps} | |
308 | ||
309 | ||
310 | You can add read, write or all capabilities to users, buckets, metadata and | |
311 | usage (utilization). For example:: | |
312 | ||
313 | --caps="[users|buckets|metadata|usage|zone]=[*|read|write|read, write]" | |
314 | ||
315 | For example:: | |
316 | ||
317 | radosgw-admin caps add --uid=johndoe --caps="users=*;buckets=*" | |
318 | ||
319 | ||
320 | To remove administrative capabilities from a user, execute the following:: | |
321 | ||
322 | radosgw-admin caps rm --uid=johndoe --caps={caps} | |
323 | ||
324 | ||
325 | Quota Management | |
326 | ================ | |
327 | ||
328 | The Ceph Object Gateway enables you to set quotas on users and buckets owned by | |
329 | users. Quotas include the maximum number of objects in a bucket and the maximum | |
330 | storage size a bucket can hold. | |
331 | ||
332 | - **Bucket:** The ``--bucket`` option allows you to specify a quota for | |
333 | buckets the user owns. | |
334 | ||
335 | - **Maximum Objects:** The ``--max-objects`` setting allows you to specify | |
336 | the maximum number of objects. A negative value disables this setting. | |
337 | ||
338 | - **Maximum Size:** The ``--max-size`` option allows you to specify a quota | |
339 | size in B/K/M/G/T, where B is the default. A negative value disables this setting. | |
340 | ||
341 | - **Quota Scope:** The ``--quota-scope`` option sets the scope for the quota. | |
342 | The options are ``bucket`` and ``user``. Bucket quotas apply to buckets a | |
343 | user owns. User quotas apply to a user. | |
344 | ||
345 | ||
346 | Set User Quota | |
347 | -------------- | |
348 | ||
349 | Before you enable a quota, you must first set the quota parameters. | |
350 | For example:: | |
351 | ||
352 | radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>] | |
353 | ||
354 | For example:: | |
355 | ||
356 | radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024B | |
357 | ||
358 | ||
359 | A negative value for num objects and / or max size means that the | |
360 | specific quota attribute check is disabled. | |
361 | ||
362 | ||
363 | Enable/Disable User Quota | |
364 | ------------------------- | |
365 | ||
366 | Once you set a user quota, you may enable it. For example:: | |
367 | ||
368 | radosgw-admin quota enable --quota-scope=user --uid=<uid> | |
369 | ||
370 | You may disable an enabled user quota. For example:: | |
371 | ||
372 | radosgw-admin quota disable --quota-scope=user --uid=<uid> | |
373 | ||
374 | ||
375 | Set Bucket Quota | |
376 | ---------------- | |
377 | ||
378 | Bucket quotas apply to the buckets owned by the specified ``uid``. They are | |
379 | independent of the user. :: | |
380 | ||
381 | radosgw-admin quota set --uid=<uid> --quota-scope=bucket [--max-objects=<num objects>] [--max-size=<max size] | |
382 | ||
383 | A negative value for num objects and / or max size means that the | |
384 | specific quota attribute check is disabled. | |
385 | ||
386 | ||
387 | Enable/Disable Bucket Quota | |
388 | --------------------------- | |
389 | ||
390 | Once you set a bucket quota, you may enable it. For example:: | |
391 | ||
392 | radosgw-admin quota enable --quota-scope=bucket --uid=<uid> | |
393 | ||
394 | You may disable an enabled bucket quota. For example:: | |
395 | ||
396 | radosgw-admin quota disable --quota-scope=bucket --uid=<uid> | |
397 | ||
398 | ||
399 | Get Quota Settings | |
400 | ------------------ | |
401 | ||
402 | You may access each user's quota settings via the user information | |
403 | API. To read user quota setting information with the CLI interface, | |
404 | execute the following:: | |
405 | ||
406 | radosgw-admin user info --uid=<uid> | |
407 | ||
408 | ||
409 | Update Quota Stats | |
410 | ------------------ | |
411 | ||
412 | Quota stats get updated asynchronously. You can update quota | |
413 | statistics for all users and all buckets manually to retrieve | |
414 | the latest quota stats. :: | |
415 | ||
416 | radosgw-admin user stats --uid=<uid> --sync-stats | |
417 | ||
418 | ||
419 | Get User Usage Stats | |
420 | -------------------- | |
421 | ||
422 | To see how much of the quota a user has consumed, execute the following:: | |
423 | ||
424 | radosgw-admin user stats --uid=<uid> | |
425 | ||
426 | .. note:: You should execute ``radosgw-admin user stats`` with the | |
427 | ``--sync-stats`` option to receive the latest data. | |
428 | ||
429 | Default Quotas | |
430 | -------------- | |
431 | ||
432 | You can set default quotas in the config. These defaults are used when | |
433 | creating a new user and have no effect on existing users. If the | |
434 | relevant default quota is set in config, then that quota is set on the | |
435 | new user, and that quota is enabled. See ``rgw bucket default quota max objects``, | |
436 | ``rgw bucket default quota max size``, ``rgw user default quota max objects``, and | |
437 | ``rgw user default quota max size`` in `Ceph Object Gateway Config Reference`_ | |
438 | ||
31f18b77 FG |
439 | Quota Cache |
440 | ----------- | |
441 | ||
442 | Quota statistics are cached on each RGW instance. If there are multiple | |
443 | instances, then the cache can keep quotas from being perfectly enforced, as | |
444 | each instance will have a different view of quotas. The options that control | |
445 | this are ``rgw bucket quota ttl``, ``rgw user quota bucket sync interval`` and | |
446 | ``rgw user quota sync interval``. The higher these values are, the more | |
447 | efficient quota operations are, but the more out-of-sync multiple instances | |
448 | will be. The lower these values are, the closer to perfect enforcement | |
449 | multiple instances will achieve. If all three are 0, then quota caching is | |
450 | effectively disabled, and multiple instances will have perfect quota | |
451 | enforcement. See `Ceph Object Gateway Config Reference`_ | |
452 | ||
7c673cae FG |
453 | Reading / Writing Global Quotas |
454 | ------------------------------- | |
455 | ||
456 | You can read and write global quota settings in the period configuration. To | |
457 | view the global quota settings:: | |
458 | ||
459 | radosgw-admin global quota get | |
460 | ||
461 | The global quota settings can be manipulated with the ``global quota`` | |
462 | counterparts of the ``quota set``, ``quota enable``, and ``quota disable`` | |
463 | commands. :: | |
464 | ||
465 | radosgw-admin global quota set --quota-scope bucket --max-objects 1024 | |
466 | radosgw-admin global quota enable --quota-scope bucket | |
467 | ||
468 | .. note:: In a multisite configuration, where there is a realm and period | |
469 | present, changes to the global quotas must be committed using ``period | |
470 | update --commit``. If there is no period present, the rados gateway(s) must | |
471 | be restarted for the changes to take effect. | |
472 | ||
473 | ||
474 | Usage | |
475 | ===== | |
476 | ||
477 | The Ceph Object Gateway logs usage for each user. You can track | |
478 | user usage within date ranges too. | |
479 | ||
480 | - Add ``rgw enable usage log = true`` in [client.rgw] section of ceph.conf and restart the radosgw service. | |
481 | ||
482 | Options include: | |
483 | ||
484 | - **Start Date:** The ``--start-date`` option allows you to filter usage | |
485 | stats from a particular start date (**format:** ``yyyy-mm-dd[HH:MM:SS]``). | |
486 | ||
487 | - **End Date:** The ``--end-date`` option allows you to filter usage up | |
488 | to a particular date (**format:** ``yyyy-mm-dd[HH:MM:SS]``). | |
489 | ||
490 | - **Log Entries:** The ``--show-log-entries`` option allows you to specify | |
491 | whether or not to include log entries with the usage stats | |
492 | (options: ``true`` | ``false``). | |
493 | ||
494 | .. note:: You may specify time with minutes and seconds, but it is stored | |
495 | with 1 hour resolution. | |
496 | ||
497 | ||
498 | Show Usage | |
499 | ---------- | |
500 | ||
501 | To show usage statistics, specify the ``usage show``. To show usage for a | |
502 | particular user, you must specify a user ID. You may also specify a start date, | |
503 | end date, and whether or not to show log entries.:: | |
504 | ||
505 | radosgw-admin usage show --uid=johndoe --start-date=2012-03-01 --end-date=2012-04-01 | |
506 | ||
507 | You may also show a summary of usage information for all users by omitting a user ID. :: | |
508 | ||
509 | radosgw-admin usage show --show-log-entries=false | |
510 | ||
511 | ||
512 | Trim Usage | |
513 | ---------- | |
514 | ||
515 | With heavy use, usage logs can begin to take up storage space. You can trim | |
516 | usage logs for all users and for specific users. You may also specify date | |
517 | ranges for trim operations. :: | |
518 | ||
519 | radosgw-admin usage trim --start-date=2010-01-01 --end-date=2010-12-31 | |
520 | radosgw-admin usage trim --uid=johndoe | |
521 | radosgw-admin usage trim --uid=johndoe --end-date=2013-12-31 | |
522 | ||
523 | ||
524 | .. _radosgw-admin: ../../man/8/radosgw-admin/ | |
525 | .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/ | |
526 | .. _Ceph Object Gateway Config Reference: ../config-ref/ |