]>
Commit | Line | Data |
---|---|---|
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, | |
59 | "auid": 0, | |
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, | |
112 | "auid": 0, | |
113 | "subusers": [ | |
114 | { "id": "johndoe:swift", | |
115 | "permissions": "full-control"}], | |
116 | "keys": [ | |
117 | { "user": "johndoe", | |
118 | "access_key": "11BS02LGFB6AL6H1ADMW", | |
119 | "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}], | |
120 | "swift_keys": [], | |
121 | "caps": [], | |
122 | "op_mask": "read, write, delete", | |
123 | "default_placement": "", | |
124 | "placement_tags": [], | |
125 | "bucket_quota": { "enabled": false, | |
126 | "max_size_kb": -1, | |
127 | "max_objects": -1}, | |
128 | "user_quota": { "enabled": false, | |
129 | "max_size_kb": -1, | |
130 | "max_objects": -1}, | |
131 | "temp_url_keys": []} | |
132 | ||
133 | ||
134 | Get User Info | |
135 | ------------- | |
136 | ||
137 | To get information about a user, you must specify ``user info`` and the user ID | |
138 | (``--uid={username}``) . :: | |
139 | ||
140 | radosgw-admin user info --uid=johndoe | |
141 | ||
142 | ||
143 | ||
144 | Modify User Info | |
145 | ---------------- | |
146 | ||
147 | To modify information about a user, you must specify the user ID (``--uid={username}``) | |
148 | and the attributes you want to modify. Typical modifications are to keys and secrets, | |
149 | email addresses, display names and access levels. For example:: | |
150 | ||
151 | radosgw-admin user modify --uid=johndoe --display-name="John E. Doe" | |
152 | ||
153 | To modify subuser values, specify ``subuser modify`` and the subuser ID. For example:: | |
154 | ||
155 | radosgw-admin subuser modify --uid=johndoe:swift --access=full | |
156 | ||
157 | ||
158 | User Enable/Suspend | |
159 | ------------------- | |
160 | ||
161 | When you create a user, the user is enabled by default. However, you may suspend | |
162 | user privileges and re-enable them at a later time. To suspend a user, specify | |
163 | ``user suspend`` and the user ID. :: | |
164 | ||
165 | radosgw-admin user suspend --uid=johndoe | |
166 | ||
167 | To re-enable a suspended user, specify ``user enable`` and the user ID. :: | |
168 | ||
169 | radosgw-admin user enable --uid=johndoe | |
170 | ||
171 | .. note:: Disabling the user disables the subuser. | |
172 | ||
173 | ||
174 | Remove a User | |
175 | ------------- | |
176 | ||
177 | When you remove a user, the user and subuser are removed from the system. | |
178 | However, you may remove just the subuser if you wish. To remove a user (and | |
179 | subuser), specify ``user rm`` and the user ID. :: | |
180 | ||
181 | radosgw-admin user rm --uid=johndoe | |
182 | ||
183 | To remove the subuser only, specify ``subuser rm`` and the subuser ID. :: | |
184 | ||
185 | radosgw-admin subuser rm --subuser=johndoe:swift | |
186 | ||
187 | ||
188 | Options include: | |
189 | ||
190 | - **Purge Data:** The ``--purge-data`` option purges all data associated | |
191 | to the UID. | |
192 | ||
193 | - **Purge Keys:** The ``--purge-keys`` option purges all keys associated | |
194 | to the UID. | |
195 | ||
196 | ||
197 | Remove a Subuser | |
198 | ---------------- | |
199 | ||
200 | When you remove a sub user, you are removing access to the Swift interface. | |
201 | The user will remain in the system. To remove the subuser, specify | |
202 | ``subuser rm`` and the subuser ID. :: | |
203 | ||
204 | radosgw-admin subuser rm --subuser=johndoe:swift | |
205 | ||
206 | ||
207 | ||
208 | Options include: | |
209 | ||
210 | - **Purge Keys:** The ``--purge-keys`` option purges all keys associated | |
211 | to the UID. | |
212 | ||
213 | ||
214 | Add / Remove a Key | |
215 | ------------------------ | |
216 | ||
217 | Both users and subusers require the key to access the S3 or Swift interface. To | |
218 | use S3, the user needs a key pair which is composed of an access key and a | |
219 | secret key. On the other hand, to use Swift, the user typically needs a secret | |
220 | key (password), and use it together with the associated user ID. You may create | |
221 | a key and either specify or generate the access key and/or secret key. You may | |
222 | also remove a key. Options include: | |
223 | ||
224 | - ``--key-type=<type>`` specifies the key type. The options are: s3, swift | |
225 | - ``--access-key=<key>`` manually specifies an S3 access key. | |
226 | - ``--secret-key=<key>`` manually specifies a S3 secret key or a Swift secret key. | |
227 | - ``--gen-access-key`` automatically generates a S3 key. | |
228 | - ``--gen-secret`` automatically generates a S3 secret key or a Swift secret key. | |
229 | ||
230 | An example how to add a specified S3 key pair for a user. :: | |
231 | ||
232 | radosgw-admin key create --uid=foo --key-type=s3 --access-key fooAccessKey --secret-key fooSecretKey | |
233 | ||
234 | .. code-block:: javascript | |
235 | ||
236 | { "user_id": "foo", | |
237 | "rados_uid": 0, | |
238 | "display_name": "foo", | |
239 | "email": "foo@example.com", | |
240 | "suspended": 0, | |
241 | "keys": [ | |
242 | { "user": "foo", | |
243 | "access_key": "fooAccessKey", | |
244 | "secret_key": "fooSecretKey"}], | |
245 | } | |
246 | ||
247 | Note that you may create multiple S3 key pairs for a user. | |
248 | ||
249 | To attach a specified swift secret key for a subuser. :: | |
250 | ||
251 | radosgw-admin key create --subuser=foo:bar --key-type=swift --secret-key barSecret | |
252 | ||
253 | .. code-block:: javascript | |
254 | ||
255 | { "user_id": "foo", | |
256 | "rados_uid": 0, | |
257 | "display_name": "foo", | |
258 | "email": "foo@example.com", | |
259 | "suspended": 0, | |
260 | "subusers": [ | |
261 | { "id": "foo:bar", | |
262 | "permissions": "full-control"}], | |
263 | "swift_keys": [ | |
264 | { "user": "foo:bar", | |
265 | "secret_key": "asfghjghghmgm"}]} | |
266 | ||
267 | Note that a subuser can have only one swift secret key. | |
268 | ||
269 | Subusers can also be used with S3 APIs if the subuser is associated with a S3 key pair. :: | |
270 | ||
271 | radosgw-admin key create --subuser=foo:bar --key-type=s3 --access-key barAccessKey --secret-key barSecretKey | |
272 | ||
273 | .. code-block:: javascript | |
274 | ||
275 | { "user_id": "foo", | |
276 | "rados_uid": 0, | |
277 | "display_name": "foo", | |
278 | "email": "foo@example.com", | |
279 | "suspended": 0, | |
280 | "subusers": [ | |
281 | { "id": "foo:bar", | |
282 | "permissions": "full-control"}], | |
283 | "keys": [ | |
284 | { "user": "foo:bar", | |
285 | "access_key": "barAccessKey", | |
286 | "secret_key": "barSecretKey"}], | |
287 | } | |
288 | ||
289 | ||
290 | To remove a S3 key pair, specify the access key. :: | |
291 | ||
292 | radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey | |
293 | ||
294 | To remove the swift secret key. :: | |
295 | ||
296 | radosgw-admin key rm -subuser=foo:bar --key-type=swift | |
297 | ||
298 | ||
299 | Add / Remove Admin Capabilities | |
300 | ------------------------------- | |
301 | ||
302 | The Ceph Storage Cluster provides an administrative API that enables users to | |
303 | execute administrative functions via the REST API. By default, users do NOT have | |
304 | access to this API. To enable a user to exercise administrative functionality, | |
305 | provide the user with administrative capabilities. | |
306 | ||
307 | To add administrative capabilities to a user, execute the following:: | |
308 | ||
309 | radosgw-admin caps add --uid={uid} --caps={caps} | |
310 | ||
311 | ||
312 | You can add read, write or all capabilities to users, buckets, metadata and | |
313 | usage (utilization). For example:: | |
314 | ||
315 | --caps="[users|buckets|metadata|usage|zone]=[*|read|write|read, write]" | |
316 | ||
317 | For example:: | |
318 | ||
319 | radosgw-admin caps add --uid=johndoe --caps="users=*;buckets=*" | |
320 | ||
321 | ||
322 | To remove administrative capabilities from a user, execute the following:: | |
323 | ||
324 | radosgw-admin caps rm --uid=johndoe --caps={caps} | |
325 | ||
326 | ||
327 | Quota Management | |
328 | ================ | |
329 | ||
330 | The Ceph Object Gateway enables you to set quotas on users and buckets owned by | |
331 | users. Quotas include the maximum number of objects in a bucket and the maximum | |
332 | storage size a bucket can hold. | |
333 | ||
334 | - **Bucket:** The ``--bucket`` option allows you to specify a quota for | |
335 | buckets the user owns. | |
336 | ||
337 | - **Maximum Objects:** The ``--max-objects`` setting allows you to specify | |
338 | the maximum number of objects. A negative value disables this setting. | |
339 | ||
340 | - **Maximum Size:** The ``--max-size`` option allows you to specify a quota | |
341 | size in B/K/M/G/T, where B is the default. A negative value disables this setting. | |
342 | ||
343 | - **Quota Scope:** The ``--quota-scope`` option sets the scope for the quota. | |
344 | The options are ``bucket`` and ``user``. Bucket quotas apply to buckets a | |
345 | user owns. User quotas apply to a user. | |
346 | ||
347 | ||
348 | Set User Quota | |
349 | -------------- | |
350 | ||
351 | Before you enable a quota, you must first set the quota parameters. | |
352 | For example:: | |
353 | ||
354 | radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>] | |
355 | ||
356 | For example:: | |
357 | ||
358 | radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024B | |
359 | ||
360 | ||
361 | A negative value for num objects and / or max size means that the | |
362 | specific quota attribute check is disabled. | |
363 | ||
364 | ||
365 | Enable/Disable User Quota | |
366 | ------------------------- | |
367 | ||
368 | Once you set a user quota, you may enable it. For example:: | |
369 | ||
370 | radosgw-admin quota enable --quota-scope=user --uid=<uid> | |
371 | ||
372 | You may disable an enabled user quota. For example:: | |
373 | ||
374 | radosgw-admin quota disable --quota-scope=user --uid=<uid> | |
375 | ||
376 | ||
377 | Set Bucket Quota | |
378 | ---------------- | |
379 | ||
380 | Bucket quotas apply to the buckets owned by the specified ``uid``. They are | |
381 | independent of the user. :: | |
382 | ||
383 | radosgw-admin quota set --uid=<uid> --quota-scope=bucket [--max-objects=<num objects>] [--max-size=<max size] | |
384 | ||
385 | A negative value for num objects and / or max size means that the | |
386 | specific quota attribute check is disabled. | |
387 | ||
388 | ||
389 | Enable/Disable Bucket Quota | |
390 | --------------------------- | |
391 | ||
392 | Once you set a bucket quota, you may enable it. For example:: | |
393 | ||
394 | radosgw-admin quota enable --quota-scope=bucket --uid=<uid> | |
395 | ||
396 | You may disable an enabled bucket quota. For example:: | |
397 | ||
398 | radosgw-admin quota disable --quota-scope=bucket --uid=<uid> | |
399 | ||
400 | ||
401 | Get Quota Settings | |
402 | ------------------ | |
403 | ||
404 | You may access each user's quota settings via the user information | |
405 | API. To read user quota setting information with the CLI interface, | |
406 | execute the following:: | |
407 | ||
408 | radosgw-admin user info --uid=<uid> | |
409 | ||
410 | ||
411 | Update Quota Stats | |
412 | ------------------ | |
413 | ||
414 | Quota stats get updated asynchronously. You can update quota | |
415 | statistics for all users and all buckets manually to retrieve | |
416 | the latest quota stats. :: | |
417 | ||
418 | radosgw-admin user stats --uid=<uid> --sync-stats | |
419 | ||
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 | ||
441 | Reading / Writing Global Quotas | |
442 | ------------------------------- | |
443 | ||
444 | You can read and write global quota settings in the period configuration. To | |
445 | view the global quota settings:: | |
446 | ||
447 | radosgw-admin global quota get | |
448 | ||
449 | The global quota settings can be manipulated with the ``global quota`` | |
450 | counterparts of the ``quota set``, ``quota enable``, and ``quota disable`` | |
451 | commands. :: | |
452 | ||
453 | radosgw-admin global quota set --quota-scope bucket --max-objects 1024 | |
454 | radosgw-admin global quota enable --quota-scope bucket | |
455 | ||
456 | .. note:: In a multisite configuration, where there is a realm and period | |
457 | present, changes to the global quotas must be committed using ``period | |
458 | update --commit``. If there is no period present, the rados gateway(s) must | |
459 | be restarted for the changes to take effect. | |
460 | ||
461 | ||
462 | Usage | |
463 | ===== | |
464 | ||
465 | The Ceph Object Gateway logs usage for each user. You can track | |
466 | user usage within date ranges too. | |
467 | ||
468 | - Add ``rgw enable usage log = true`` in [client.rgw] section of ceph.conf and restart the radosgw service. | |
469 | ||
470 | Options include: | |
471 | ||
472 | - **Start Date:** The ``--start-date`` option allows you to filter usage | |
473 | stats from a particular start date (**format:** ``yyyy-mm-dd[HH:MM:SS]``). | |
474 | ||
475 | - **End Date:** The ``--end-date`` option allows you to filter usage up | |
476 | to a particular date (**format:** ``yyyy-mm-dd[HH:MM:SS]``). | |
477 | ||
478 | - **Log Entries:** The ``--show-log-entries`` option allows you to specify | |
479 | whether or not to include log entries with the usage stats | |
480 | (options: ``true`` | ``false``). | |
481 | ||
482 | .. note:: You may specify time with minutes and seconds, but it is stored | |
483 | with 1 hour resolution. | |
484 | ||
485 | ||
486 | Show Usage | |
487 | ---------- | |
488 | ||
489 | To show usage statistics, specify the ``usage show``. To show usage for a | |
490 | particular user, you must specify a user ID. You may also specify a start date, | |
491 | end date, and whether or not to show log entries.:: | |
492 | ||
493 | radosgw-admin usage show --uid=johndoe --start-date=2012-03-01 --end-date=2012-04-01 | |
494 | ||
495 | You may also show a summary of usage information for all users by omitting a user ID. :: | |
496 | ||
497 | radosgw-admin usage show --show-log-entries=false | |
498 | ||
499 | ||
500 | Trim Usage | |
501 | ---------- | |
502 | ||
503 | With heavy use, usage logs can begin to take up storage space. You can trim | |
504 | usage logs for all users and for specific users. You may also specify date | |
505 | ranges for trim operations. :: | |
506 | ||
507 | radosgw-admin usage trim --start-date=2010-01-01 --end-date=2010-12-31 | |
508 | radosgw-admin usage trim --uid=johndoe | |
509 | radosgw-admin usage trim --uid=johndoe --end-date=2013-12-31 | |
510 | ||
511 | ||
512 | .. _radosgw-admin: ../../man/8/radosgw-admin/ | |
513 | .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/ | |
514 | .. _Ceph Object Gateway Config Reference: ../config-ref/ |