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