]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | ================== |
2 | Admin Operations | |
3 | ================== | |
4 | ||
5 | An admin API request will be done on a URI that starts with the configurable 'admin' | |
6 | resource entry point. Authorization for the admin API duplicates the S3 authorization | |
7 | mechanism. Some operations require that the user holds special administrative capabilities. | |
8 | The response entity type (XML or JSON) may be specified as the 'format' option in the | |
9 | request and defaults to JSON if not specified. | |
10 | ||
11 | Get Usage | |
12 | ========= | |
13 | ||
14 | Request bandwidth usage information. | |
15 | ||
16 | Note: this feature is disabled by default, can be enabled by setting ``rgw | |
17 | enable usage log = true`` in the appropriate section of ceph.conf. For changes | |
18 | in ceph.conf to take effect, radosgw process restart is needed. | |
19 | ||
20 | :caps: usage=read | |
21 | ||
22 | Syntax | |
23 | ~~~~~~ | |
24 | ||
25 | :: | |
26 | ||
27 | GET /{admin}/usage?format=json HTTP/1.1 | |
28 | Host: {fqdn} | |
29 | ||
30 | ||
31 | ||
32 | Request Parameters | |
33 | ~~~~~~~~~~~~~~~~~~ | |
34 | ||
35 | ``uid`` | |
36 | ||
37 | :Description: The user for which the information is requested. If not specified will apply to all users. | |
38 | :Type: String | |
39 | :Example: ``foo_user`` | |
40 | :Required: No | |
41 | ||
42 | ``start`` | |
43 | ||
44 | :Description: Date and (optional) time that specifies the start time of the requested data. | |
45 | :Type: String | |
46 | :Example: ``2012-09-25 16:00:00`` | |
47 | :Required: No | |
48 | ||
49 | ``end`` | |
50 | ||
51 | :Description: Date and (optional) time that specifies the end time of the requested data (non-inclusive). | |
52 | :Type: String | |
53 | :Example: ``2012-09-25 16:00:00`` | |
54 | :Required: No | |
55 | ||
56 | ||
57 | ``show-entries`` | |
58 | ||
59 | :Description: Specifies whether data entries should be returned. | |
60 | :Type: Boolean | |
61 | :Example: True [True] | |
62 | :Required: No | |
63 | ||
64 | ||
65 | ``show-summary`` | |
66 | ||
67 | :Description: Specifies whether data summary should be returned. | |
68 | :Type: Boolean | |
69 | :Example: True [True] | |
70 | :Required: No | |
71 | ||
72 | ||
73 | ||
74 | Response Entities | |
75 | ~~~~~~~~~~~~~~~~~ | |
76 | ||
77 | If successful, the response contains the requested information. | |
78 | ||
79 | ``usage`` | |
80 | ||
81 | :Description: A container for the usage information. | |
82 | :Type: Container | |
83 | ||
84 | ``entries`` | |
85 | ||
86 | :Description: A container for the usage entries information. | |
87 | :Type: Container | |
88 | ||
89 | ``user`` | |
90 | ||
91 | :Description: A container for the user data information. | |
92 | :Type: Container | |
93 | ||
94 | ``owner`` | |
95 | ||
96 | :Description: The name of the user that owns the buckets. | |
97 | :Type: String | |
98 | ||
99 | ``bucket`` | |
100 | ||
101 | :Description: The bucket name. | |
102 | :Type: String | |
103 | ||
104 | ``time`` | |
105 | ||
106 | :Description: Time lower bound for which data is being specified (rounded to the beginning of the first relevant hour). | |
107 | :Type: String | |
108 | ||
109 | ``epoch`` | |
110 | ||
111 | :Description: The time specified in seconds since 1/1/1970. | |
112 | :Type: String | |
113 | ||
114 | ``categories`` | |
115 | ||
116 | :Description: A container for stats categories. | |
117 | :Type: Container | |
118 | ||
119 | ``entry`` | |
120 | ||
121 | :Description: A container for stats entry. | |
122 | :Type: Container | |
123 | ||
124 | ``category`` | |
125 | ||
126 | :Description: Name of request category for which the stats are provided. | |
127 | :Type: String | |
128 | ||
129 | ``bytes_sent`` | |
130 | ||
131 | :Description: Number of bytes sent by the RADOS Gateway. | |
132 | :Type: Integer | |
133 | ||
134 | ``bytes_received`` | |
135 | ||
136 | :Description: Number of bytes received by the RADOS Gateway. | |
137 | :Type: Integer | |
138 | ||
139 | ``ops`` | |
140 | ||
141 | :Description: Number of operations. | |
142 | :Type: Integer | |
143 | ||
144 | ``successful_ops`` | |
145 | ||
146 | :Description: Number of successful operations. | |
147 | :Type: Integer | |
148 | ||
149 | ``summary`` | |
150 | ||
151 | :Description: A container for stats summary. | |
152 | :Type: Container | |
153 | ||
154 | ``total`` | |
155 | ||
156 | :Description: A container for stats summary aggregated total. | |
157 | :Type: Container | |
158 | ||
159 | Special Error Responses | |
160 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
161 | ||
162 | TBD. | |
163 | ||
164 | Trim Usage | |
165 | ========== | |
166 | ||
167 | Remove usage information. With no dates specified, removes all usage | |
168 | information. | |
169 | ||
170 | Note: this feature is disabled by default, can be enabled by setting ``rgw | |
171 | enable usage log = true`` in the appropriate section of ceph.conf. For changes | |
172 | in ceph.conf to take effect, radosgw process restart is needed. | |
173 | ||
174 | :caps: usage=write | |
175 | ||
176 | Syntax | |
177 | ~~~~~~ | |
178 | ||
179 | :: | |
180 | ||
181 | DELETE /{admin}/usage?format=json HTTP/1.1 | |
182 | Host: {fqdn} | |
183 | ||
184 | ||
185 | ||
186 | Request Parameters | |
187 | ~~~~~~~~~~~~~~~~~~ | |
188 | ||
189 | ``uid`` | |
190 | ||
191 | :Description: The user for which the information is requested. If not specified will apply to all users. | |
192 | :Type: String | |
193 | :Example: ``foo_user`` | |
194 | :Required: No | |
195 | ||
196 | ``start`` | |
197 | ||
198 | :Description: Date and (optional) time that specifies the start time of the requested data. | |
199 | :Type: String | |
200 | :Example: ``2012-09-25 16:00:00`` | |
201 | :Required: No | |
202 | ||
203 | ``end`` | |
204 | ||
205 | :Description: Date and (optional) time that specifies the end time of the requested data (none inclusive). | |
206 | :Type: String | |
207 | :Example: ``2012-09-25 16:00:00`` | |
208 | :Required: No | |
209 | ||
210 | ||
211 | ``remove-all`` | |
212 | ||
213 | :Description: Required when uid is not specified, in order to acknowledge multi user data removal. | |
214 | :Type: Boolean | |
215 | :Example: True [False] | |
216 | :Required: No | |
217 | ||
218 | Special Error Responses | |
219 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
220 | ||
221 | TBD. | |
222 | ||
223 | Get User Info | |
224 | ============= | |
225 | ||
226 | Get user information. | |
227 | ||
228 | :caps: users=read | |
229 | ||
230 | ||
231 | Syntax | |
232 | ~~~~~~ | |
233 | ||
234 | :: | |
235 | ||
236 | GET /{admin}/user?format=json HTTP/1.1 | |
237 | Host: {fqdn} | |
238 | ||
239 | ||
240 | Request Parameters | |
241 | ~~~~~~~~~~~~~~~~~~ | |
242 | ||
243 | ``uid`` | |
244 | ||
245 | :Description: The user for which the information is requested. | |
246 | :Type: String | |
247 | :Example: ``foo_user`` | |
248 | :Required: Yes | |
249 | ||
250 | ||
251 | Response Entities | |
252 | ~~~~~~~~~~~~~~~~~ | |
253 | ||
254 | If successful, the response contains the user information. | |
255 | ||
256 | ``user`` | |
257 | ||
258 | :Description: A container for the user data information. | |
259 | :Type: Container | |
260 | ||
261 | ``user_id`` | |
262 | ||
263 | :Description: The user id. | |
264 | :Type: String | |
265 | :Parent: ``user`` | |
266 | ||
267 | ``display_name`` | |
268 | ||
269 | :Description: Display name for the user. | |
270 | :Type: String | |
271 | :Parent: ``user`` | |
272 | ||
273 | ``suspended`` | |
274 | ||
275 | :Description: True if the user is suspended. | |
276 | :Type: Boolean | |
277 | :Parent: ``user`` | |
278 | ||
279 | ``max_buckets`` | |
280 | ||
281 | :Description: The maximum number of buckets to be owned by the user. | |
282 | :Type: Integer | |
283 | :Parent: ``user`` | |
284 | ||
285 | ``subusers`` | |
286 | ||
287 | :Description: Subusers associated with this user account. | |
288 | :Type: Container | |
289 | :Parent: ``user`` | |
290 | ||
291 | ``keys`` | |
292 | ||
293 | :Description: S3 keys associated with this user account. | |
294 | :Type: Container | |
295 | :Parent: ``user`` | |
296 | ||
297 | ``swift_keys`` | |
298 | ||
299 | :Description: Swift keys associated with this user account. | |
300 | :Type: Container | |
301 | :Parent: ``user`` | |
302 | ||
303 | ``caps`` | |
304 | ||
305 | :Description: User capabilities. | |
306 | :Type: Container | |
307 | :Parent: ``user`` | |
308 | ||
309 | Special Error Responses | |
310 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
311 | ||
312 | None. | |
313 | ||
314 | Create User | |
315 | =========== | |
316 | ||
317 | Create a new user. By default, a S3 key pair will be created automatically | |
318 | and returned in the response. If only one of ``access-key`` or ``secret-key`` | |
319 | is provided, the omitted key will be automatically generated. By default, a | |
320 | generated key is added to the keyring without replacing an existing key pair. | |
321 | If ``access-key`` is specified and refers to an existing key owned by the user | |
322 | then it will be modified. | |
323 | ||
d2e6a577 FG |
324 | .. versionadded:: Luminous |
325 | ||
326 | A ``tenant`` may either be specified as a part of uid or as an additional | |
327 | request param. | |
328 | ||
7c673cae FG |
329 | :caps: users=write |
330 | ||
331 | Syntax | |
332 | ~~~~~~ | |
333 | ||
334 | :: | |
335 | ||
336 | PUT /{admin}/user?format=json HTTP/1.1 | |
337 | Host: {fqdn} | |
338 | ||
339 | ||
340 | ||
341 | Request Parameters | |
342 | ~~~~~~~~~~~~~~~~~~ | |
343 | ||
344 | ``uid`` | |
345 | ||
346 | :Description: The user ID to be created. | |
347 | :Type: String | |
348 | :Example: ``foo_user`` | |
349 | :Required: Yes | |
11fdf7f2 TL |
350 | |
351 | A tenant name may also specified as a part of ``uid``, by following the syntax | |
352 | ``tenant$user``, refer to :ref:`Multitenancy <rgw-multitenancy>` for more details. | |
7c673cae FG |
353 | |
354 | ``display-name`` | |
355 | ||
356 | :Description: The display name of the user to be created. | |
357 | :Type: String | |
358 | :Example: ``foo user`` | |
359 | :Required: Yes | |
360 | ||
361 | ||
362 | ``email`` | |
363 | ||
364 | :Description: The email address associated with the user. | |
365 | :Type: String | |
366 | :Example: ``foo@bar.com`` | |
367 | :Required: No | |
368 | ||
369 | ``key-type`` | |
370 | ||
371 | :Description: Key type to be generated, options are: swift, s3 (default). | |
372 | :Type: String | |
373 | :Example: ``s3`` [``s3``] | |
374 | :Required: No | |
375 | ||
376 | ``access-key`` | |
377 | ||
378 | :Description: Specify access key. | |
379 | :Type: String | |
380 | :Example: ``ABCD0EF12GHIJ2K34LMN`` | |
381 | :Required: No | |
382 | ||
383 | ||
384 | ``secret-key`` | |
385 | ||
386 | :Description: Specify secret key. | |
387 | :Type: String | |
388 | :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8`` | |
389 | :Required: No | |
390 | ||
391 | ``user-caps`` | |
392 | ||
393 | :Description: User capabilities. | |
394 | :Type: String | |
395 | :Example: ``usage=read, write; users=read`` | |
396 | :Required: No | |
397 | ||
398 | ``generate-key`` | |
399 | ||
400 | :Description: Generate a new key pair and add to the existing keyring. | |
401 | :Type: Boolean | |
402 | :Example: True [True] | |
403 | :Required: No | |
404 | ||
405 | ``max-buckets`` | |
406 | ||
407 | :Description: Specify the maximum number of buckets the user can own. | |
408 | :Type: Integer | |
409 | :Example: 500 [1000] | |
410 | :Required: No | |
411 | ||
412 | ``suspended`` | |
413 | ||
414 | :Description: Specify whether the user should be suspended. | |
415 | :Type: Boolean | |
416 | :Example: False [False] | |
417 | :Required: No | |
418 | ||
d2e6a577 | 419 | .. versionadded:: Jewel |
11fdf7f2 | 420 | |
d2e6a577 FG |
421 | ``tenant`` |
422 | ||
423 | :Description: the Tenant under which a user is a part of. | |
424 | :Type: string | |
425 | :Example: tenant1 | |
426 | :Required: No | |
427 | ||
7c673cae FG |
428 | Response Entities |
429 | ~~~~~~~~~~~~~~~~~ | |
430 | ||
431 | If successful, the response contains the user information. | |
432 | ||
433 | ``user`` | |
434 | ||
435 | :Description: A container for the user data information. | |
436 | :Type: Container | |
437 | ||
d2e6a577 | 438 | ``tenant`` |
11fdf7f2 TL |
439 | |
440 | :Description: The tenant which user is a part of. | |
d2e6a577 FG |
441 | :Type: String |
442 | :Parent: ``user`` | |
443 | ||
7c673cae FG |
444 | ``user_id`` |
445 | ||
446 | :Description: The user id. | |
447 | :Type: String | |
448 | :Parent: ``user`` | |
449 | ||
450 | ``display_name`` | |
451 | ||
452 | :Description: Display name for the user. | |
453 | :Type: String | |
454 | :Parent: ``user`` | |
455 | ||
456 | ``suspended`` | |
457 | ||
458 | :Description: True if the user is suspended. | |
459 | :Type: Boolean | |
460 | :Parent: ``user`` | |
461 | ||
462 | ``max_buckets`` | |
463 | ||
464 | :Description: The maximum number of buckets to be owned by the user. | |
465 | :Type: Integer | |
466 | :Parent: ``user`` | |
467 | ||
468 | ``subusers`` | |
469 | ||
470 | :Description: Subusers associated with this user account. | |
471 | :Type: Container | |
472 | :Parent: ``user`` | |
473 | ||
474 | ``keys`` | |
475 | ||
476 | :Description: S3 keys associated with this user account. | |
477 | :Type: Container | |
478 | :Parent: ``user`` | |
479 | ||
480 | ``swift_keys`` | |
481 | ||
482 | :Description: Swift keys associated with this user account. | |
483 | :Type: Container | |
484 | :Parent: ``user`` | |
485 | ||
486 | ``caps`` | |
487 | ||
488 | :Description: User capabilities. | |
489 | :Type: Container | |
490 | :Parent: ``user`` | |
491 | ||
492 | Special Error Responses | |
493 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
494 | ||
495 | ``UserExists`` | |
496 | ||
497 | :Description: Attempt to create existing user. | |
498 | :Code: 409 Conflict | |
499 | ||
500 | ``InvalidAccessKey`` | |
501 | ||
502 | :Description: Invalid access key specified. | |
503 | :Code: 400 Bad Request | |
504 | ||
505 | ``InvalidKeyType`` | |
506 | ||
507 | :Description: Invalid key type specified. | |
508 | :Code: 400 Bad Request | |
509 | ||
510 | ``InvalidSecretKey`` | |
511 | ||
512 | :Description: Invalid secret key specified. | |
513 | :Code: 400 Bad Request | |
514 | ||
515 | ``InvalidKeyType`` | |
516 | ||
517 | :Description: Invalid key type specified. | |
518 | :Code: 400 Bad Request | |
519 | ||
520 | ``KeyExists`` | |
521 | ||
522 | :Description: Provided access key exists and belongs to another user. | |
523 | :Code: 409 Conflict | |
524 | ||
525 | ``EmailExists`` | |
526 | ||
527 | :Description: Provided email address exists. | |
528 | :Code: 409 Conflict | |
529 | ||
530 | ``InvalidCapability`` | |
531 | ||
532 | :Description: Attempt to grant invalid admin capability. | |
533 | :Code: 400 Bad Request | |
534 | ||
535 | ||
536 | Modify User | |
537 | =========== | |
538 | ||
539 | Modify a user. | |
540 | ||
541 | :caps: users=write | |
542 | ||
543 | Syntax | |
544 | ~~~~~~ | |
545 | ||
546 | :: | |
547 | ||
548 | POST /{admin}/user?format=json HTTP/1.1 | |
549 | Host: {fqdn} | |
550 | ||
551 | ||
552 | Request Parameters | |
553 | ~~~~~~~~~~~~~~~~~~ | |
554 | ||
555 | ``uid`` | |
556 | ||
557 | :Description: The user ID to be modified. | |
558 | :Type: String | |
559 | :Example: ``foo_user`` | |
560 | :Required: Yes | |
561 | ||
562 | ``display-name`` | |
563 | ||
564 | :Description: The display name of the user to be modified. | |
565 | :Type: String | |
566 | :Example: ``foo user`` | |
567 | :Required: No | |
568 | ||
569 | ``email`` | |
570 | ||
571 | :Description: The email address to be associated with the user. | |
572 | :Type: String | |
573 | :Example: ``foo@bar.com`` | |
574 | :Required: No | |
575 | ||
576 | ``generate-key`` | |
577 | ||
578 | :Description: Generate a new key pair and add to the existing keyring. | |
579 | :Type: Boolean | |
580 | :Example: True [False] | |
581 | :Required: No | |
582 | ||
583 | ``access-key`` | |
584 | ||
585 | :Description: Specify access key. | |
586 | :Type: String | |
587 | :Example: ``ABCD0EF12GHIJ2K34LMN`` | |
588 | :Required: No | |
589 | ||
590 | ``secret-key`` | |
591 | ||
592 | :Description: Specify secret key. | |
593 | :Type: String | |
594 | :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8`` | |
595 | :Required: No | |
596 | ||
597 | ``key-type`` | |
598 | ||
599 | :Description: Key type to be generated, options are: swift, s3 (default). | |
600 | :Type: String | |
601 | :Example: ``s3`` | |
602 | :Required: No | |
603 | ||
604 | ``user-caps`` | |
605 | ||
606 | :Description: User capabilities. | |
607 | :Type: String | |
608 | :Example: ``usage=read, write; users=read`` | |
609 | :Required: No | |
610 | ||
611 | ``max-buckets`` | |
612 | ||
613 | :Description: Specify the maximum number of buckets the user can own. | |
614 | :Type: Integer | |
615 | :Example: 500 [1000] | |
616 | :Required: No | |
617 | ||
618 | ``suspended`` | |
619 | ||
620 | :Description: Specify whether the user should be suspended. | |
621 | :Type: Boolean | |
622 | :Example: False [False] | |
623 | :Required: No | |
624 | ||
625 | Response Entities | |
626 | ~~~~~~~~~~~~~~~~~ | |
627 | ||
628 | If successful, the response contains the user information. | |
629 | ||
630 | ``user`` | |
631 | ||
632 | :Description: A container for the user data information. | |
633 | :Type: Container | |
634 | ||
635 | ``user_id`` | |
636 | ||
637 | :Description: The user id. | |
638 | :Type: String | |
639 | :Parent: ``user`` | |
640 | ||
641 | ``display_name`` | |
642 | ||
643 | :Description: Display name for the user. | |
644 | :Type: String | |
645 | :Parent: ``user`` | |
646 | ||
647 | ||
648 | ``suspended`` | |
649 | ||
650 | :Description: True if the user is suspended. | |
651 | :Type: Boolean | |
652 | :Parent: ``user`` | |
653 | ||
654 | ||
655 | ``max_buckets`` | |
656 | ||
657 | :Description: The maximum number of buckets to be owned by the user. | |
658 | :Type: Integer | |
659 | :Parent: ``user`` | |
660 | ||
661 | ||
662 | ``subusers`` | |
663 | ||
664 | :Description: Subusers associated with this user account. | |
665 | :Type: Container | |
666 | :Parent: ``user`` | |
667 | ||
668 | ||
669 | ``keys`` | |
670 | ||
671 | :Description: S3 keys associated with this user account. | |
672 | :Type: Container | |
673 | :Parent: ``user`` | |
674 | ||
675 | ||
676 | ``swift_keys`` | |
677 | ||
678 | :Description: Swift keys associated with this user account. | |
679 | :Type: Container | |
680 | :Parent: ``user`` | |
681 | ||
682 | ||
683 | ``caps`` | |
684 | ||
685 | :Description: User capabilities. | |
686 | :Type: Container | |
687 | :Parent: ``user`` | |
688 | ||
689 | ||
690 | Special Error Responses | |
691 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
692 | ||
693 | ``InvalidAccessKey`` | |
694 | ||
695 | :Description: Invalid access key specified. | |
696 | :Code: 400 Bad Request | |
697 | ||
698 | ``InvalidKeyType`` | |
699 | ||
700 | :Description: Invalid key type specified. | |
701 | :Code: 400 Bad Request | |
702 | ||
703 | ``InvalidSecretKey`` | |
704 | ||
705 | :Description: Invalid secret key specified. | |
706 | :Code: 400 Bad Request | |
707 | ||
708 | ``KeyExists`` | |
709 | ||
710 | :Description: Provided access key exists and belongs to another user. | |
711 | :Code: 409 Conflict | |
712 | ||
713 | ``EmailExists`` | |
714 | ||
715 | :Description: Provided email address exists. | |
716 | :Code: 409 Conflict | |
717 | ||
718 | ``InvalidCapability`` | |
719 | ||
720 | :Description: Attempt to grant invalid admin capability. | |
721 | :Code: 400 Bad Request | |
722 | ||
723 | Remove User | |
724 | =========== | |
725 | ||
726 | Remove an existing user. | |
727 | ||
728 | :caps: users=write | |
729 | ||
730 | Syntax | |
731 | ~~~~~~ | |
732 | ||
733 | :: | |
734 | ||
735 | DELETE /{admin}/user?format=json HTTP/1.1 | |
736 | Host: {fqdn} | |
737 | ||
738 | ||
739 | Request Parameters | |
740 | ~~~~~~~~~~~~~~~~~~ | |
741 | ||
742 | ``uid`` | |
743 | ||
744 | :Description: The user ID to be removed. | |
745 | :Type: String | |
746 | :Example: ``foo_user`` | |
747 | :Required: Yes. | |
748 | ||
749 | ``purge-data`` | |
750 | ||
751 | :Description: When specified the buckets and objects belonging | |
752 | to the user will also be removed. | |
753 | :Type: Boolean | |
754 | :Example: True | |
755 | :Required: No | |
756 | ||
757 | Response Entities | |
758 | ~~~~~~~~~~~~~~~~~ | |
759 | ||
760 | None | |
761 | ||
762 | Special Error Responses | |
763 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
764 | ||
765 | None. | |
766 | ||
767 | Create Subuser | |
768 | ============== | |
769 | ||
770 | Create a new subuser (primarily useful for clients using the Swift API). | |
11fdf7f2 | 771 | Note that in general for a subuser to be useful, it must be granted |
7c673cae FG |
772 | permissions by specifying ``access``. As with user creation if |
773 | ``subuser`` is specified without ``secret``, then a secret key will | |
774 | be automatically generated. | |
775 | ||
776 | :caps: users=write | |
777 | ||
778 | Syntax | |
779 | ~~~~~~ | |
780 | ||
781 | :: | |
782 | ||
783 | PUT /{admin}/user?subuser&format=json HTTP/1.1 | |
784 | Host {fqdn} | |
785 | ||
786 | ||
787 | Request Parameters | |
788 | ~~~~~~~~~~~~~~~~~~ | |
789 | ||
790 | ``uid`` | |
791 | ||
792 | :Description: The user ID under which a subuser is to be created. | |
793 | :Type: String | |
794 | :Example: ``foo_user`` | |
795 | :Required: Yes | |
796 | ||
797 | ||
798 | ``subuser`` | |
799 | ||
800 | :Description: Specify the subuser ID to be created. | |
801 | :Type: String | |
802 | :Example: ``sub_foo`` | |
803 | :Required: Yes | |
804 | ||
805 | ``secret-key`` | |
806 | ||
807 | :Description: Specify secret key. | |
808 | :Type: String | |
809 | :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8`` | |
810 | :Required: No | |
811 | ||
812 | ``key-type`` | |
813 | ||
814 | :Description: Key type to be generated, options are: swift (default), s3. | |
815 | :Type: String | |
816 | :Example: ``swift`` [``swift``] | |
817 | :Required: No | |
818 | ||
819 | ``access`` | |
820 | ||
821 | :Description: Set access permissions for sub-user, should be one | |
822 | of ``read, write, readwrite, full``. | |
823 | :Type: String | |
824 | :Example: ``read`` | |
825 | :Required: No | |
826 | ||
827 | ``generate-secret`` | |
828 | ||
829 | :Description: Generate the secret key. | |
830 | :Type: Boolean | |
831 | :Example: True [False] | |
832 | :Required: No | |
833 | ||
834 | Response Entities | |
835 | ~~~~~~~~~~~~~~~~~ | |
836 | ||
837 | If successful, the response contains the subuser information. | |
838 | ||
839 | ||
840 | ``subusers`` | |
841 | ||
842 | :Description: Subusers associated with the user account. | |
843 | :Type: Container | |
844 | ||
845 | ``id`` | |
846 | ||
847 | :Description: Subuser id. | |
848 | :Type: String | |
849 | :Parent: ``subusers`` | |
850 | ||
851 | ``permissions`` | |
852 | ||
853 | :Description: Subuser access to user account. | |
854 | :Type: String | |
855 | :Parent: ``subusers`` | |
856 | ||
857 | Special Error Responses | |
858 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
859 | ||
860 | ``SubuserExists`` | |
861 | ||
862 | :Description: Specified subuser exists. | |
863 | :Code: 409 Conflict | |
864 | ||
865 | ``InvalidKeyType`` | |
866 | ||
867 | :Description: Invalid key type specified. | |
868 | :Code: 400 Bad Request | |
869 | ||
870 | ``InvalidSecretKey`` | |
871 | ||
872 | :Description: Invalid secret key specified. | |
873 | :Code: 400 Bad Request | |
874 | ||
875 | ``InvalidAccess`` | |
876 | ||
877 | :Description: Invalid subuser access specified. | |
878 | :Code: 400 Bad Request | |
879 | ||
880 | Modify Subuser | |
881 | ============== | |
882 | ||
883 | Modify an existing subuser | |
884 | ||
885 | :caps: users=write | |
886 | ||
887 | Syntax | |
888 | ~~~~~~ | |
889 | ||
890 | :: | |
891 | ||
892 | POST /{admin}/user?subuser&format=json HTTP/1.1 | |
893 | Host {fqdn} | |
894 | ||
895 | ||
896 | Request Parameters | |
897 | ~~~~~~~~~~~~~~~~~~ | |
898 | ||
899 | ``uid`` | |
900 | ||
901 | :Description: The user ID under which the subuser is to be modified. | |
902 | :Type: String | |
903 | :Example: ``foo_user`` | |
904 | :Required: Yes | |
905 | ||
906 | ``subuser`` | |
907 | ||
908 | :Description: The subuser ID to be modified. | |
909 | :Type: String | |
910 | :Example: ``sub_foo`` | |
911 | :Required: Yes | |
912 | ||
913 | ``generate-secret`` | |
914 | ||
915 | :Description: Generate a new secret key for the subuser, | |
916 | replacing the existing key. | |
917 | :Type: Boolean | |
918 | :Example: True [False] | |
919 | :Required: No | |
920 | ||
921 | ``secret`` | |
922 | ||
923 | :Description: Specify secret key. | |
924 | :Type: String | |
925 | :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8`` | |
926 | :Required: No | |
927 | ||
928 | ``key-type`` | |
929 | ||
930 | :Description: Key type to be generated, options are: swift (default), s3 . | |
931 | :Type: String | |
932 | :Example: ``swift`` [``swift``] | |
933 | :Required: No | |
934 | ||
935 | ``access`` | |
936 | ||
937 | :Description: Set access permissions for sub-user, should be one | |
938 | of ``read, write, readwrite, full``. | |
939 | :Type: String | |
940 | :Example: ``read`` | |
941 | :Required: No | |
942 | ||
943 | ||
944 | Response Entities | |
945 | ~~~~~~~~~~~~~~~~~ | |
946 | ||
947 | If successful, the response contains the subuser information. | |
948 | ||
949 | ||
950 | ``subusers`` | |
951 | ||
952 | :Description: Subusers associated with the user account. | |
953 | :Type: Container | |
954 | ||
955 | ``id`` | |
956 | ||
957 | :Description: Subuser id. | |
958 | :Type: String | |
959 | :Parent: ``subusers`` | |
960 | ||
961 | ``permissions`` | |
962 | ||
963 | :Description: Subuser access to user account. | |
964 | :Type: String | |
965 | :Parent: ``subusers`` | |
966 | ||
967 | Special Error Responses | |
968 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
969 | ||
970 | ``InvalidKeyType`` | |
971 | ||
972 | :Description: Invalid key type specified. | |
973 | :Code: 400 Bad Request | |
974 | ||
975 | ``InvalidSecretKey`` | |
976 | ||
977 | :Description: Invalid secret key specified. | |
978 | :Code: 400 Bad Request | |
979 | ||
980 | ``InvalidAccess`` | |
981 | ||
982 | :Description: Invalid subuser access specified. | |
983 | :Code: 400 Bad Request | |
984 | ||
985 | Remove Subuser | |
986 | ============== | |
987 | ||
988 | Remove an existing subuser | |
989 | ||
990 | :caps: users=write | |
991 | ||
992 | Syntax | |
993 | ~~~~~~ | |
994 | ||
995 | :: | |
996 | ||
997 | DELETE /{admin}/user?subuser&format=json HTTP/1.1 | |
998 | Host {fqdn} | |
999 | ||
1000 | ||
1001 | Request Parameters | |
1002 | ~~~~~~~~~~~~~~~~~~ | |
1003 | ||
1004 | ``uid`` | |
1005 | ||
1006 | :Description: The user ID under which the subuser is to be removed. | |
1007 | :Type: String | |
1008 | :Example: ``foo_user`` | |
1009 | :Required: Yes | |
1010 | ||
1011 | ||
1012 | ``subuser`` | |
1013 | ||
1014 | :Description: The subuser ID to be removed. | |
1015 | :Type: String | |
1016 | :Example: ``sub_foo`` | |
1017 | :Required: Yes | |
1018 | ||
1019 | ``purge-keys`` | |
1020 | ||
1021 | :Description: Remove keys belonging to the subuser. | |
1022 | :Type: Boolean | |
1023 | :Example: True [True] | |
1024 | :Required: No | |
1025 | ||
1026 | Response Entities | |
1027 | ~~~~~~~~~~~~~~~~~ | |
1028 | ||
1029 | None. | |
1030 | ||
1031 | Special Error Responses | |
1032 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1033 | None. | |
1034 | ||
1035 | Create Key | |
1036 | ========== | |
1037 | ||
1038 | Create a new key. If a ``subuser`` is specified then by default created keys | |
1039 | will be swift type. If only one of ``access-key`` or ``secret-key`` is provided the | |
1040 | committed key will be automatically generated, that is if only ``secret-key`` is | |
1041 | specified then ``access-key`` will be automatically generated. By default, a | |
1042 | generated key is added to the keyring without replacing an existing key pair. | |
1043 | If ``access-key`` is specified and refers to an existing key owned by the user | |
1044 | then it will be modified. The response is a container listing all keys of the same | |
1045 | type as the key created. Note that when creating a swift key, specifying the option | |
1046 | ``access-key`` will have no effect. Additionally, only one swift key may be held by | |
1047 | each user or subuser. | |
1048 | ||
1049 | :caps: users=write | |
1050 | ||
1051 | ||
1052 | Syntax | |
1053 | ~~~~~~ | |
1054 | ||
1055 | :: | |
1056 | ||
1057 | PUT /{admin}/user?key&format=json HTTP/1.1 | |
1058 | Host {fqdn} | |
1059 | ||
1060 | ||
1061 | Request Parameters | |
1062 | ~~~~~~~~~~~~~~~~~~ | |
1063 | ||
1064 | ``uid`` | |
1065 | ||
1066 | :Description: The user ID to receive the new key. | |
1067 | :Type: String | |
1068 | :Example: ``foo_user`` | |
1069 | :Required: Yes | |
1070 | ||
1071 | ``subuser`` | |
1072 | ||
1073 | :Description: The subuser ID to receive the new key. | |
1074 | :Type: String | |
1075 | :Example: ``sub_foo`` | |
1076 | :Required: No | |
1077 | ||
1078 | ``key-type`` | |
1079 | ||
1080 | :Description: Key type to be generated, options are: swift, s3 (default). | |
1081 | :Type: String | |
1082 | :Example: ``s3`` [``s3``] | |
1083 | :Required: No | |
1084 | ||
1085 | ``access-key`` | |
1086 | ||
1087 | :Description: Specify the access key. | |
1088 | :Type: String | |
1089 | :Example: ``AB01C2D3EF45G6H7IJ8K`` | |
1090 | :Required: No | |
1091 | ||
1092 | ``secret-key`` | |
1093 | ||
1094 | :Description: Specify the secret key. | |
1095 | :Type: String | |
1096 | :Example: ``0ab/CdeFGhij1klmnopqRSTUv1WxyZabcDEFgHij`` | |
1097 | :Required: No | |
1098 | ||
1099 | ``generate-key`` | |
1100 | ||
1101 | :Description: Generate a new key pair and add to the existing keyring. | |
1102 | :Type: Boolean | |
1103 | :Example: True [``True``] | |
1104 | :Required: No | |
1105 | ||
1106 | ||
1107 | Response Entities | |
1108 | ~~~~~~~~~~~~~~~~~ | |
1109 | ||
1110 | ``keys`` | |
1111 | ||
1112 | :Description: Keys of type created associated with this user account. | |
1113 | :Type: Container | |
1114 | ||
1115 | ``user`` | |
1116 | ||
1117 | :Description: The user account associated with the key. | |
1118 | :Type: String | |
1119 | :Parent: ``keys`` | |
1120 | ||
1121 | ``access-key`` | |
1122 | ||
1123 | :Description: The access key. | |
1124 | :Type: String | |
1125 | :Parent: ``keys`` | |
1126 | ||
1127 | ``secret-key`` | |
1128 | ||
1129 | :Description: The secret key | |
1130 | :Type: String | |
1131 | :Parent: ``keys`` | |
1132 | ||
1133 | ||
1134 | Special Error Responses | |
1135 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1136 | ||
1137 | ``InvalidAccessKey`` | |
1138 | ||
1139 | :Description: Invalid access key specified. | |
1140 | :Code: 400 Bad Request | |
1141 | ||
1142 | ``InvalidKeyType`` | |
1143 | ||
1144 | :Description: Invalid key type specified. | |
1145 | :Code: 400 Bad Request | |
1146 | ||
1147 | ``InvalidSecretKey`` | |
1148 | ||
1149 | :Description: Invalid secret key specified. | |
1150 | :Code: 400 Bad Request | |
1151 | ||
1152 | ``InvalidKeyType`` | |
1153 | ||
1154 | :Description: Invalid key type specified. | |
1155 | :Code: 400 Bad Request | |
1156 | ||
1157 | ``KeyExists`` | |
1158 | ||
1159 | :Description: Provided access key exists and belongs to another user. | |
1160 | :Code: 409 Conflict | |
1161 | ||
1162 | Remove Key | |
1163 | ========== | |
1164 | ||
1165 | Remove an existing key. | |
1166 | ||
1167 | :caps: users=write | |
1168 | ||
1169 | Syntax | |
1170 | ~~~~~~ | |
1171 | ||
1172 | :: | |
1173 | ||
1174 | DELETE /{admin}/user?key&format=json HTTP/1.1 | |
1175 | Host {fqdn} | |
1176 | ||
1177 | ||
1178 | Request Parameters | |
1179 | ~~~~~~~~~~~~~~~~~~ | |
1180 | ||
1181 | ``access-key`` | |
1182 | ||
1183 | :Description: The S3 access key belonging to the S3 key pair to remove. | |
1184 | :Type: String | |
1185 | :Example: ``AB01C2D3EF45G6H7IJ8K`` | |
1186 | :Required: Yes | |
1187 | ||
1188 | ``uid`` | |
1189 | ||
1190 | :Description: The user to remove the key from. | |
1191 | :Type: String | |
1192 | :Example: ``foo_user`` | |
1193 | :Required: No | |
1194 | ||
1195 | ``subuser`` | |
1196 | ||
1197 | :Description: The subuser to remove the key from. | |
1198 | :Type: String | |
1199 | :Example: ``sub_foo`` | |
1200 | :Required: No | |
1201 | ||
1202 | ``key-type`` | |
1203 | ||
1204 | :Description: Key type to be removed, options are: swift, s3. | |
1205 | NOTE: Required to remove swift key. | |
1206 | :Type: String | |
1207 | :Example: ``swift`` | |
1208 | :Required: No | |
1209 | ||
1210 | Special Error Responses | |
1211 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1212 | ||
1213 | None. | |
1214 | ||
1215 | Response Entities | |
1216 | ~~~~~~~~~~~~~~~~~ | |
1217 | ||
1218 | None. | |
1219 | ||
1220 | Get Bucket Info | |
1221 | =============== | |
1222 | ||
1223 | Get information about a subset of the existing buckets. If ``uid`` is specified | |
11fdf7f2 | 1224 | without ``bucket`` then all buckets belonging to the user will be returned. If |
7c673cae FG |
1225 | ``bucket`` alone is specified, information for that particular bucket will be |
1226 | retrieved. | |
1227 | ||
1228 | :caps: buckets=read | |
1229 | ||
1230 | Syntax | |
1231 | ~~~~~~ | |
1232 | ||
1233 | :: | |
1234 | ||
1235 | GET /{admin}/bucket?format=json HTTP/1.1 | |
1236 | Host {fqdn} | |
1237 | ||
1238 | ||
1239 | Request Parameters | |
1240 | ~~~~~~~~~~~~~~~~~~ | |
1241 | ||
1242 | ``bucket`` | |
1243 | ||
1244 | :Description: The bucket to return info on. | |
1245 | :Type: String | |
1246 | :Example: ``foo_bucket`` | |
1247 | :Required: No | |
1248 | ||
1249 | ``uid`` | |
1250 | ||
1251 | :Description: The user to retrieve bucket information for. | |
1252 | :Type: String | |
1253 | :Example: ``foo_user`` | |
1254 | :Required: No | |
1255 | ||
1256 | ``stats`` | |
1257 | ||
1258 | :Description: Return bucket statistics. | |
1259 | :Type: Boolean | |
1260 | :Example: True [False] | |
1261 | :Required: No | |
1262 | ||
1263 | Response Entities | |
1264 | ~~~~~~~~~~~~~~~~~ | |
1265 | ||
1266 | If successful the request returns a buckets container containing | |
1267 | the desired bucket information. | |
1268 | ||
1269 | ``stats`` | |
1270 | ||
1271 | :Description: Per bucket information. | |
1272 | :Type: Container | |
1273 | ||
1274 | ``buckets`` | |
1275 | ||
1276 | :Description: Contains a list of one or more bucket containers. | |
1277 | :Type: Container | |
1278 | ||
1279 | ``bucket`` | |
1280 | ||
1281 | :Description: Container for single bucket information. | |
1282 | :Type: Container | |
1283 | :Parent: ``buckets`` | |
1284 | ||
1285 | ``name`` | |
1286 | ||
1287 | :Description: The name of the bucket. | |
1288 | :Type: String | |
1289 | :Parent: ``bucket`` | |
1290 | ||
1291 | ``pool`` | |
1292 | ||
1293 | :Description: The pool the bucket is stored in. | |
1294 | :Type: String | |
1295 | :Parent: ``bucket`` | |
1296 | ||
1297 | ``id`` | |
1298 | ||
1299 | :Description: The unique bucket id. | |
1300 | :Type: String | |
1301 | :Parent: ``bucket`` | |
1302 | ||
1303 | ``marker`` | |
1304 | ||
1305 | :Description: Internal bucket tag. | |
1306 | :Type: String | |
1307 | :Parent: ``bucket`` | |
1308 | ||
1309 | ``owner`` | |
1310 | ||
1311 | :Description: The user id of the bucket owner. | |
1312 | :Type: String | |
1313 | :Parent: ``bucket`` | |
1314 | ||
1315 | ``usage`` | |
1316 | ||
1317 | :Description: Storage usage information. | |
1318 | :Type: Container | |
1319 | :Parent: ``bucket`` | |
1320 | ||
1321 | ``index`` | |
1322 | ||
1323 | :Description: Status of bucket index. | |
1324 | :Type: String | |
1325 | :Parent: ``bucket`` | |
1326 | ||
1327 | Special Error Responses | |
1328 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1329 | ||
1330 | ``IndexRepairFailed`` | |
1331 | ||
1332 | :Description: Bucket index repair failed. | |
1333 | :Code: 409 Conflict | |
1334 | ||
1335 | Check Bucket Index | |
1336 | ================== | |
1337 | ||
1338 | Check the index of an existing bucket. NOTE: to check multipart object | |
1339 | accounting with ``check-objects``, ``fix`` must be set to True. | |
1340 | ||
1341 | :caps: buckets=write | |
1342 | ||
1343 | Syntax | |
1344 | ~~~~~~ | |
1345 | ||
1346 | :: | |
1347 | ||
1348 | GET /{admin}/bucket?index&format=json HTTP/1.1 | |
1349 | Host {fqdn} | |
1350 | ||
1351 | ||
1352 | Request Parameters | |
1353 | ~~~~~~~~~~~~~~~~~~ | |
1354 | ||
1355 | ``bucket`` | |
1356 | ||
1357 | :Description: The bucket to return info on. | |
1358 | :Type: String | |
1359 | :Example: ``foo_bucket`` | |
1360 | :Required: Yes | |
1361 | ||
1362 | ``check-objects`` | |
1363 | ||
1364 | :Description: Check multipart object accounting. | |
1365 | :Type: Boolean | |
1366 | :Example: True [False] | |
1367 | :Required: No | |
1368 | ||
1369 | ``fix`` | |
1370 | ||
1371 | :Description: Also fix the bucket index when checking. | |
1372 | :Type: Boolean | |
1373 | :Example: False [False] | |
1374 | :Required: No | |
1375 | ||
1376 | Response Entities | |
1377 | ~~~~~~~~~~~~~~~~~ | |
1378 | ||
1379 | ``index`` | |
1380 | ||
1381 | :Description: Status of bucket index. | |
1382 | :Type: String | |
1383 | ||
1384 | Special Error Responses | |
1385 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1386 | ||
1387 | ``IndexRepairFailed`` | |
1388 | ||
1389 | :Description: Bucket index repair failed. | |
1390 | :Code: 409 Conflict | |
1391 | ||
1392 | Remove Bucket | |
1393 | ============= | |
1394 | ||
1395 | Delete an existing bucket. | |
1396 | ||
1397 | :caps: buckets=write | |
1398 | ||
1399 | Syntax | |
1400 | ~~~~~~ | |
1401 | ||
1402 | :: | |
1403 | ||
1404 | DELETE /{admin}/bucket?format=json HTTP/1.1 | |
1405 | Host {fqdn} | |
1406 | ||
1407 | ||
1408 | ||
1409 | Request Parameters | |
1410 | ~~~~~~~~~~~~~~~~~~ | |
1411 | ||
1412 | ``bucket`` | |
1413 | ||
1414 | :Description: The bucket to remove. | |
1415 | :Type: String | |
1416 | :Example: ``foo_bucket`` | |
1417 | :Required: Yes | |
1418 | ||
1419 | ``purge-objects`` | |
1420 | ||
1421 | :Description: Remove a buckets objects before deletion. | |
1422 | :Type: Boolean | |
1423 | :Example: True [False] | |
1424 | :Required: No | |
1425 | ||
1426 | Response Entities | |
1427 | ~~~~~~~~~~~~~~~~~ | |
1428 | ||
1429 | None. | |
1430 | ||
1431 | Special Error Responses | |
1432 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1433 | ||
1434 | ``BucketNotEmpty`` | |
1435 | ||
1436 | :Description: Attempted to delete non-empty bucket. | |
1437 | :Code: 409 Conflict | |
1438 | ||
1439 | ``ObjectRemovalFailed`` | |
1440 | ||
1441 | :Description: Unable to remove objects. | |
1442 | :Code: 409 Conflict | |
1443 | ||
1444 | Unlink Bucket | |
1445 | ============= | |
1446 | ||
1447 | Unlink a bucket from a specified user. Primarily useful for changing | |
1448 | bucket ownership. | |
1449 | ||
1450 | :caps: buckets=write | |
1451 | ||
1452 | Syntax | |
1453 | ~~~~~~ | |
1454 | ||
1455 | :: | |
1456 | ||
1457 | POST /{admin}/bucket?format=json HTTP/1.1 | |
1458 | Host {fqdn} | |
1459 | ||
1460 | ||
1461 | Request Parameters | |
1462 | ~~~~~~~~~~~~~~~~~~ | |
1463 | ||
1464 | ``bucket`` | |
1465 | ||
1466 | :Description: The bucket to unlink. | |
1467 | :Type: String | |
1468 | :Example: ``foo_bucket`` | |
1469 | :Required: Yes | |
1470 | ||
1471 | ``uid`` | |
1472 | ||
1473 | :Description: The user ID to unlink the bucket from. | |
1474 | :Type: String | |
1475 | :Example: ``foo_user`` | |
1476 | :Required: Yes | |
1477 | ||
1478 | Response Entities | |
1479 | ~~~~~~~~~~~~~~~~~ | |
1480 | ||
1481 | None. | |
1482 | ||
1483 | Special Error Responses | |
1484 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1485 | ||
1486 | ``BucketUnlinkFailed`` | |
1487 | ||
1488 | :Description: Unable to unlink bucket from specified user. | |
1489 | :Code: 409 Conflict | |
1490 | ||
1491 | Link Bucket | |
1492 | =========== | |
1493 | ||
1494 | Link a bucket to a specified user, unlinking the bucket from | |
1495 | any previous user. | |
1496 | ||
1497 | :caps: buckets=write | |
1498 | ||
1499 | Syntax | |
1500 | ~~~~~~ | |
1501 | ||
1502 | :: | |
1503 | ||
1504 | PUT /{admin}/bucket?format=json HTTP/1.1 | |
1505 | Host {fqdn} | |
1506 | ||
1507 | ||
1508 | Request Parameters | |
1509 | ~~~~~~~~~~~~~~~~~~ | |
1510 | ||
1511 | ``bucket`` | |
1512 | ||
1513 | :Description: The bucket name to unlink. | |
1514 | :Type: String | |
1515 | :Example: ``foo_bucket`` | |
1516 | :Required: Yes | |
1517 | ||
1518 | ``bucket-id`` | |
1519 | ||
1520 | :Description: The bucket id to unlink. | |
1521 | :Type: String | |
1522 | :Example: ``dev.6607669.420`` | |
1523 | :Required: Yes | |
1524 | ||
1525 | ``uid`` | |
1526 | ||
1527 | :Description: The user ID to link the bucket to. | |
1528 | :Type: String | |
1529 | :Example: ``foo_user`` | |
1530 | :Required: Yes | |
1531 | ||
1532 | Response Entities | |
1533 | ~~~~~~~~~~~~~~~~~ | |
1534 | ||
1535 | ``bucket`` | |
1536 | ||
1537 | :Description: Container for single bucket information. | |
1538 | :Type: Container | |
1539 | ||
1540 | ``name`` | |
1541 | ||
1542 | :Description: The name of the bucket. | |
1543 | :Type: String | |
1544 | :Parent: ``bucket`` | |
1545 | ||
1546 | ``pool`` | |
1547 | ||
1548 | :Description: The pool the bucket is stored in. | |
1549 | :Type: String | |
1550 | :Parent: ``bucket`` | |
1551 | ||
1552 | ``id`` | |
1553 | ||
1554 | :Description: The unique bucket id. | |
1555 | :Type: String | |
1556 | :Parent: ``bucket`` | |
1557 | ||
1558 | ``marker`` | |
1559 | ||
1560 | :Description: Internal bucket tag. | |
1561 | :Type: String | |
1562 | :Parent: ``bucket`` | |
1563 | ||
1564 | ``owner`` | |
1565 | ||
1566 | :Description: The user id of the bucket owner. | |
1567 | :Type: String | |
1568 | :Parent: ``bucket`` | |
1569 | ||
1570 | ``usage`` | |
1571 | ||
1572 | :Description: Storage usage information. | |
1573 | :Type: Container | |
1574 | :Parent: ``bucket`` | |
1575 | ||
1576 | ``index`` | |
1577 | ||
1578 | :Description: Status of bucket index. | |
1579 | :Type: String | |
1580 | :Parent: ``bucket`` | |
1581 | ||
1582 | Special Error Responses | |
1583 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1584 | ||
1585 | ``BucketUnlinkFailed`` | |
1586 | ||
1587 | :Description: Unable to unlink bucket from specified user. | |
1588 | :Code: 409 Conflict | |
1589 | ||
1590 | ``BucketLinkFailed`` | |
1591 | ||
1592 | :Description: Unable to link bucket to specified user. | |
1593 | :Code: 409 Conflict | |
1594 | ||
1595 | Remove Object | |
1596 | ============= | |
1597 | ||
1598 | Remove an existing object. NOTE: Does not require owner to be non-suspended. | |
1599 | ||
1600 | :caps: buckets=write | |
1601 | ||
1602 | Syntax | |
1603 | ~~~~~~ | |
1604 | ||
1605 | :: | |
1606 | ||
1607 | DELETE /{admin}/bucket?object&format=json HTTP/1.1 | |
1608 | Host {fqdn} | |
1609 | ||
1610 | Request Parameters | |
1611 | ~~~~~~~~~~~~~~~~~~ | |
1612 | ||
1613 | ``bucket`` | |
1614 | ||
1615 | :Description: The bucket containing the object to be removed. | |
1616 | :Type: String | |
1617 | :Example: ``foo_bucket`` | |
1618 | :Required: Yes | |
1619 | ||
1620 | ``object`` | |
1621 | ||
1622 | :Description: The object to remove. | |
1623 | :Type: String | |
1624 | :Example: ``foo.txt`` | |
1625 | :Required: Yes | |
1626 | ||
1627 | Response Entities | |
1628 | ~~~~~~~~~~~~~~~~~ | |
1629 | ||
1630 | None. | |
1631 | ||
1632 | Special Error Responses | |
1633 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1634 | ||
1635 | ``NoSuchObject`` | |
1636 | ||
1637 | :Description: Specified object does not exist. | |
1638 | :Code: 404 Not Found | |
1639 | ||
1640 | ``ObjectRemovalFailed`` | |
1641 | ||
1642 | :Description: Unable to remove objects. | |
1643 | :Code: 409 Conflict | |
1644 | ||
1645 | ||
1646 | ||
1647 | Get Bucket or Object Policy | |
1648 | =========================== | |
1649 | ||
1650 | Read the policy of an object or bucket. | |
1651 | ||
1652 | :caps: buckets=read | |
1653 | ||
1654 | Syntax | |
1655 | ~~~~~~ | |
1656 | ||
1657 | :: | |
1658 | ||
1659 | GET /{admin}/bucket?policy&format=json HTTP/1.1 | |
1660 | Host {fqdn} | |
1661 | ||
1662 | ||
1663 | Request Parameters | |
1664 | ~~~~~~~~~~~~~~~~~~ | |
1665 | ||
1666 | ``bucket`` | |
1667 | ||
1668 | :Description: The bucket to read the policy from. | |
1669 | :Type: String | |
1670 | :Example: ``foo_bucket`` | |
1671 | :Required: Yes | |
1672 | ||
1673 | ``object`` | |
1674 | ||
1675 | :Description: The object to read the policy from. | |
1676 | :Type: String | |
1677 | :Example: ``foo.txt`` | |
1678 | :Required: No | |
1679 | ||
1680 | Response Entities | |
1681 | ~~~~~~~~~~~~~~~~~ | |
1682 | ||
1683 | If successful, returns the object or bucket policy | |
1684 | ||
1685 | ``policy`` | |
1686 | ||
1687 | :Description: Access control policy. | |
1688 | :Type: Container | |
1689 | ||
1690 | Special Error Responses | |
1691 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1692 | ||
1693 | ``IncompleteBody`` | |
1694 | ||
1695 | :Description: Either bucket was not specified for a bucket policy request or bucket | |
1696 | and object were not specified for an object policy request. | |
1697 | :Code: 400 Bad Request | |
1698 | ||
1699 | Add A User Capability | |
1700 | ===================== | |
1701 | ||
1702 | Add an administrative capability to a specified user. | |
1703 | ||
1704 | :caps: users=write | |
1705 | ||
1706 | Syntax | |
1707 | ~~~~~~ | |
1708 | ||
1709 | :: | |
1710 | ||
1711 | PUT /{admin}/user?caps&format=json HTTP/1.1 | |
1712 | Host {fqdn} | |
1713 | ||
1714 | Request Parameters | |
1715 | ~~~~~~~~~~~~~~~~~~ | |
1716 | ||
1717 | ``uid`` | |
1718 | ||
1719 | :Description: The user ID to add an administrative capability to. | |
1720 | :Type: String | |
1721 | :Example: ``foo_user`` | |
1722 | :Required: Yes | |
1723 | ||
1724 | ``user-caps`` | |
1725 | ||
1726 | :Description: The administrative capability to add to the user. | |
1727 | :Type: String | |
1728 | :Example: ``usage=read,write;user=write`` | |
1729 | :Required: Yes | |
1730 | ||
1731 | Response Entities | |
1732 | ~~~~~~~~~~~~~~~~~ | |
1733 | ||
1734 | If successful, the response contains the user's capabilities. | |
1735 | ||
1736 | ``user`` | |
1737 | ||
1738 | :Description: A container for the user data information. | |
1739 | :Type: Container | |
1740 | :Parent: ``user`` | |
1741 | ||
1742 | ``user_id`` | |
1743 | ||
1744 | :Description: The user id. | |
1745 | :Type: String | |
1746 | :Parent: ``user`` | |
1747 | ||
1748 | ``caps`` | |
1749 | ||
1750 | :Description: User capabilities. | |
1751 | :Type: Container | |
1752 | :Parent: ``user`` | |
1753 | ||
1754 | ||
1755 | Special Error Responses | |
1756 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1757 | ||
1758 | ``InvalidCapability`` | |
1759 | ||
1760 | :Description: Attempt to grant invalid admin capability. | |
1761 | :Code: 400 Bad Request | |
1762 | ||
1763 | Example Request | |
1764 | ~~~~~~~~~~~~~~~ | |
1765 | ||
1766 | :: | |
1767 | ||
1768 | PUT /{admin}/user?caps&user-caps=usage=read,write;user=write&format=json HTTP/1.1 | |
1769 | Host: {fqdn} | |
1770 | Content-Type: text/plain | |
1771 | Authorization: {your-authorization-token} | |
1772 | ||
1773 | ||
1774 | ||
1775 | Remove A User Capability | |
1776 | ======================== | |
1777 | ||
1778 | Remove an administrative capability from a specified user. | |
1779 | ||
1780 | :caps: users=write | |
1781 | ||
1782 | Syntax | |
1783 | ~~~~~~ | |
1784 | ||
1785 | :: | |
1786 | ||
1787 | DELETE /{admin}/user?caps&format=json HTTP/1.1 | |
1788 | Host {fqdn} | |
1789 | ||
1790 | Request Parameters | |
1791 | ~~~~~~~~~~~~~~~~~~ | |
1792 | ||
1793 | ``uid`` | |
1794 | ||
1795 | :Description: The user ID to remove an administrative capability from. | |
1796 | :Type: String | |
1797 | :Example: ``foo_user`` | |
1798 | :Required: Yes | |
1799 | ||
1800 | ``user-caps`` | |
1801 | ||
1802 | :Description: The administrative capabilities to remove from the user. | |
1803 | :Type: String | |
1804 | :Example: ``usage=read, write`` | |
1805 | :Required: Yes | |
1806 | ||
1807 | Response Entities | |
1808 | ~~~~~~~~~~~~~~~~~ | |
1809 | ||
1810 | If successful, the response contains the user's capabilities. | |
1811 | ||
1812 | ``user`` | |
1813 | ||
1814 | :Description: A container for the user data information. | |
1815 | :Type: Container | |
1816 | :Parent: ``user`` | |
1817 | ||
1818 | ``user_id`` | |
1819 | ||
1820 | :Description: The user id. | |
1821 | :Type: String | |
1822 | :Parent: ``user`` | |
1823 | ||
1824 | ``caps`` | |
1825 | ||
1826 | :Description: User capabilities. | |
1827 | :Type: Container | |
1828 | :Parent: ``user`` | |
1829 | ||
1830 | ||
1831 | Special Error Responses | |
1832 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1833 | ||
1834 | ``InvalidCapability`` | |
1835 | ||
1836 | :Description: Attempt to remove an invalid admin capability. | |
1837 | :Code: 400 Bad Request | |
1838 | ||
1839 | ``NoSuchCap`` | |
1840 | ||
1841 | :Description: User does not possess specified capability. | |
1842 | :Code: 404 Not Found | |
1843 | ||
7c673cae FG |
1844 | |
1845 | Quotas | |
1846 | ====== | |
1847 | ||
1848 | The Admin Operations API enables you to set quotas on users and on bucket owned | |
1849 | by users. See `Quota Management`_ for additional details. Quotas include the | |
1850 | maximum number of objects in a bucket and the maximum storage size in megabytes. | |
1851 | ||
1852 | To view quotas, the user must have a ``users=read`` capability. To set, | |
1853 | modify or disable a quota, the user must have ``users=write`` capability. | |
1854 | See the `Admin Guide`_ for details. | |
1855 | ||
1856 | Valid parameters for quotas include: | |
1857 | ||
1858 | - **Bucket:** The ``bucket`` option allows you to specify a quota for | |
1859 | buckets owned by a user. | |
1860 | ||
1861 | - **Maximum Objects:** The ``max-objects`` setting allows you to specify | |
1862 | the maximum number of objects. A negative value disables this setting. | |
11fdf7f2 | 1863 | |
7c673cae | 1864 | - **Maximum Size:** The ``max-size`` option allows you to specify a quota |
f64942e4 AA |
1865 | for the maximum number of bytes. The ``max-size-kb`` option allows you |
1866 | to specify it in KiB. A negative value disables this setting. | |
1867 | ||
7c673cae FG |
1868 | - **Quota Type:** The ``quota-type`` option sets the scope for the quota. |
1869 | The options are ``bucket`` and ``user``. | |
1870 | ||
1871 | - **Enable/Disable Quota:** The ``enabled`` option specifies whether the | |
1872 | quota should be enabled. The value should be either 'True' or 'False'. | |
1873 | ||
1874 | Get User Quota | |
1875 | ~~~~~~~~~~~~~~ | |
1876 | ||
11fdf7f2 | 1877 | To get a quota, the user must have ``users`` capability set with ``read`` |
7c673cae FG |
1878 | permission. :: |
1879 | ||
1880 | GET /admin/user?quota&uid=<uid>"a-type=user | |
1881 | ||
1882 | ||
1883 | Set User Quota | |
1884 | ~~~~~~~~~~~~~~ | |
1885 | ||
11fdf7f2 | 1886 | To set a quota, the user must have ``users`` capability set with ``write`` |
7c673cae FG |
1887 | permission. :: |
1888 | ||
1889 | PUT /admin/user?quota&uid=<uid>"a-type=user | |
1890 | ||
1891 | ||
1892 | The content must include a JSON representation of the quota settings | |
1893 | as encoded in the corresponding read operation. | |
1894 | ||
1895 | ||
1896 | Get Bucket Quota | |
1897 | ~~~~~~~~~~~~~~~~ | |
1898 | ||
11fdf7f2 | 1899 | To get a quota, the user must have ``users`` capability set with ``read`` |
7c673cae FG |
1900 | permission. :: |
1901 | ||
1902 | GET /admin/user?quota&uid=<uid>"a-type=bucket | |
1903 | ||
1904 | ||
1905 | Set Bucket Quota | |
1906 | ~~~~~~~~~~~~~~~~ | |
1907 | ||
11fdf7f2 | 1908 | To set a quota, the user must have ``users`` capability set with ``write`` |
7c673cae FG |
1909 | permission. :: |
1910 | ||
1911 | PUT /admin/user?quota&uid=<uid>"a-type=bucket | |
1912 | ||
1913 | The content must include a JSON representation of the quota settings | |
1914 | as encoded in the corresponding read operation. | |
1915 | ||
1916 | ||
94b18763 FG |
1917 | Set Quota for an Individual Bucket |
1918 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
1919 | ||
1920 | To set a quota, the user must have ``buckets`` capability set with ``write`` | |
1921 | permission. :: | |
1922 | ||
1923 | PUT /admin/bucket?quota&uid=<uid>&bucket=<bucket-name>"a | |
1924 | ||
1925 | The content must include a JSON representation of the quota settings | |
1926 | as mentioned in Set Bucket Quota section above. | |
1927 | ||
7c673cae FG |
1928 | |
1929 | ||
1930 | Standard Error Responses | |
1931 | ======================== | |
1932 | ||
1933 | ``AccessDenied`` | |
1934 | ||
1935 | :Description: Access denied. | |
1936 | :Code: 403 Forbidden | |
1937 | ||
1938 | ``InternalError`` | |
1939 | ||
1940 | :Description: Internal server error. | |
1941 | :Code: 500 Internal Server Error | |
1942 | ||
1943 | ``NoSuchUser`` | |
1944 | ||
1945 | :Description: User does not exist. | |
1946 | :Code: 404 Not Found | |
1947 | ||
1948 | ``NoSuchBucket`` | |
1949 | ||
1950 | :Description: Bucket does not exist. | |
1951 | :Code: 404 Not Found | |
1952 | ||
1953 | ``NoSuchKey`` | |
1954 | ||
1955 | :Description: No such access key. | |
1956 | :Code: 404 Not Found | |
1957 | ||
1958 | ||
1959 | ||
11fdf7f2 TL |
1960 | |
1961 | Binding libraries | |
1962 | ======================== | |
1963 | ||
1964 | ``Golang`` | |
1965 | ||
1966 | - `IrekFasikhov/go-rgwadmin`_ | |
1967 | - `QuentinPerez/go-radosgw`_ | |
1968 | ||
1969 | ``Java`` | |
1970 | ||
1971 | - `twonote/radosgw-admin4j`_ | |
1972 | ||
1973 | ``Python`` | |
1974 | ||
1975 | - `UMIACS/rgwadmin`_ | |
1976 | - `valerytschopp/python-radosgw-admin`_ | |
1977 | ||
1978 | ||
1979 | ||
7c673cae FG |
1980 | .. _Admin Guide: ../admin |
1981 | .. _Quota Management: ../admin#quota-management | |
11fdf7f2 TL |
1982 | .. _IrekFasikhov/go-rgwadmin: https://github.com/IrekFasikhov/go-rgwadmin |
1983 | .. _QuentinPerez/go-radosgw: https://github.com/QuentinPerez/go-radosgw | |
1984 | .. _twonote/radosgw-admin4j: https://github.com/twonote/radosgw-admin4j | |
1985 | .. _UMIACS/rgwadmin: https://github.com/UMIACS/rgwadmin | |
1986 | .. _valerytschopp/python-radosgw-admin: https://github.com/valerytschopp/python-radosgw-admin | |
1987 |