]>
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 | |
d2e6a577 | 350 | A tenant name may also specified as a part of ``uid``, by following the syntax ``tenant$user``, refer to `Multitenancy`_ for more details. |
7c673cae FG |
351 | |
352 | ``display-name`` | |
353 | ||
354 | :Description: The display name of the user to be created. | |
355 | :Type: String | |
356 | :Example: ``foo user`` | |
357 | :Required: Yes | |
358 | ||
359 | ||
360 | ``email`` | |
361 | ||
362 | :Description: The email address associated with the user. | |
363 | :Type: String | |
364 | :Example: ``foo@bar.com`` | |
365 | :Required: No | |
366 | ||
367 | ``key-type`` | |
368 | ||
369 | :Description: Key type to be generated, options are: swift, s3 (default). | |
370 | :Type: String | |
371 | :Example: ``s3`` [``s3``] | |
372 | :Required: No | |
373 | ||
374 | ``access-key`` | |
375 | ||
376 | :Description: Specify access key. | |
377 | :Type: String | |
378 | :Example: ``ABCD0EF12GHIJ2K34LMN`` | |
379 | :Required: No | |
380 | ||
381 | ||
382 | ``secret-key`` | |
383 | ||
384 | :Description: Specify secret key. | |
385 | :Type: String | |
386 | :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8`` | |
387 | :Required: No | |
388 | ||
389 | ``user-caps`` | |
390 | ||
391 | :Description: User capabilities. | |
392 | :Type: String | |
393 | :Example: ``usage=read, write; users=read`` | |
394 | :Required: No | |
395 | ||
396 | ``generate-key`` | |
397 | ||
398 | :Description: Generate a new key pair and add to the existing keyring. | |
399 | :Type: Boolean | |
400 | :Example: True [True] | |
401 | :Required: No | |
402 | ||
403 | ``max-buckets`` | |
404 | ||
405 | :Description: Specify the maximum number of buckets the user can own. | |
406 | :Type: Integer | |
407 | :Example: 500 [1000] | |
408 | :Required: No | |
409 | ||
410 | ``suspended`` | |
411 | ||
412 | :Description: Specify whether the user should be suspended. | |
413 | :Type: Boolean | |
414 | :Example: False [False] | |
415 | :Required: No | |
416 | ||
d2e6a577 FG |
417 | .. versionadded:: Jewel |
418 | ``tenant`` | |
419 | ||
420 | :Description: the Tenant under which a user is a part of. | |
421 | :Type: string | |
422 | :Example: tenant1 | |
423 | :Required: No | |
424 | ||
7c673cae FG |
425 | Response Entities |
426 | ~~~~~~~~~~~~~~~~~ | |
427 | ||
428 | If successful, the response contains the user information. | |
429 | ||
430 | ``user`` | |
431 | ||
432 | :Description: A container for the user data information. | |
433 | :Type: Container | |
434 | ||
d2e6a577 FG |
435 | ``tenant`` |
436 | :Description: The tenant which user is a part of | |
437 | :Type: String | |
438 | :Parent: ``user`` | |
439 | ||
7c673cae FG |
440 | ``user_id`` |
441 | ||
442 | :Description: The user id. | |
443 | :Type: String | |
444 | :Parent: ``user`` | |
445 | ||
446 | ``display_name`` | |
447 | ||
448 | :Description: Display name for the user. | |
449 | :Type: String | |
450 | :Parent: ``user`` | |
451 | ||
452 | ``suspended`` | |
453 | ||
454 | :Description: True if the user is suspended. | |
455 | :Type: Boolean | |
456 | :Parent: ``user`` | |
457 | ||
458 | ``max_buckets`` | |
459 | ||
460 | :Description: The maximum number of buckets to be owned by the user. | |
461 | :Type: Integer | |
462 | :Parent: ``user`` | |
463 | ||
464 | ``subusers`` | |
465 | ||
466 | :Description: Subusers associated with this user account. | |
467 | :Type: Container | |
468 | :Parent: ``user`` | |
469 | ||
470 | ``keys`` | |
471 | ||
472 | :Description: S3 keys associated with this user account. | |
473 | :Type: Container | |
474 | :Parent: ``user`` | |
475 | ||
476 | ``swift_keys`` | |
477 | ||
478 | :Description: Swift keys associated with this user account. | |
479 | :Type: Container | |
480 | :Parent: ``user`` | |
481 | ||
482 | ``caps`` | |
483 | ||
484 | :Description: User capabilities. | |
485 | :Type: Container | |
486 | :Parent: ``user`` | |
487 | ||
488 | Special Error Responses | |
489 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
490 | ||
491 | ``UserExists`` | |
492 | ||
493 | :Description: Attempt to create existing user. | |
494 | :Code: 409 Conflict | |
495 | ||
496 | ``InvalidAccessKey`` | |
497 | ||
498 | :Description: Invalid access key specified. | |
499 | :Code: 400 Bad Request | |
500 | ||
501 | ``InvalidKeyType`` | |
502 | ||
503 | :Description: Invalid key type specified. | |
504 | :Code: 400 Bad Request | |
505 | ||
506 | ``InvalidSecretKey`` | |
507 | ||
508 | :Description: Invalid secret key specified. | |
509 | :Code: 400 Bad Request | |
510 | ||
511 | ``InvalidKeyType`` | |
512 | ||
513 | :Description: Invalid key type specified. | |
514 | :Code: 400 Bad Request | |
515 | ||
516 | ``KeyExists`` | |
517 | ||
518 | :Description: Provided access key exists and belongs to another user. | |
519 | :Code: 409 Conflict | |
520 | ||
521 | ``EmailExists`` | |
522 | ||
523 | :Description: Provided email address exists. | |
524 | :Code: 409 Conflict | |
525 | ||
526 | ``InvalidCapability`` | |
527 | ||
528 | :Description: Attempt to grant invalid admin capability. | |
529 | :Code: 400 Bad Request | |
530 | ||
531 | ||
532 | Modify User | |
533 | =========== | |
534 | ||
535 | Modify a user. | |
536 | ||
537 | :caps: users=write | |
538 | ||
539 | Syntax | |
540 | ~~~~~~ | |
541 | ||
542 | :: | |
543 | ||
544 | POST /{admin}/user?format=json HTTP/1.1 | |
545 | Host: {fqdn} | |
546 | ||
547 | ||
548 | Request Parameters | |
549 | ~~~~~~~~~~~~~~~~~~ | |
550 | ||
551 | ``uid`` | |
552 | ||
553 | :Description: The user ID to be modified. | |
554 | :Type: String | |
555 | :Example: ``foo_user`` | |
556 | :Required: Yes | |
557 | ||
558 | ``display-name`` | |
559 | ||
560 | :Description: The display name of the user to be modified. | |
561 | :Type: String | |
562 | :Example: ``foo user`` | |
563 | :Required: No | |
564 | ||
565 | ``email`` | |
566 | ||
567 | :Description: The email address to be associated with the user. | |
568 | :Type: String | |
569 | :Example: ``foo@bar.com`` | |
570 | :Required: No | |
571 | ||
572 | ``generate-key`` | |
573 | ||
574 | :Description: Generate a new key pair and add to the existing keyring. | |
575 | :Type: Boolean | |
576 | :Example: True [False] | |
577 | :Required: No | |
578 | ||
579 | ``access-key`` | |
580 | ||
581 | :Description: Specify access key. | |
582 | :Type: String | |
583 | :Example: ``ABCD0EF12GHIJ2K34LMN`` | |
584 | :Required: No | |
585 | ||
586 | ``secret-key`` | |
587 | ||
588 | :Description: Specify secret key. | |
589 | :Type: String | |
590 | :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8`` | |
591 | :Required: No | |
592 | ||
593 | ``key-type`` | |
594 | ||
595 | :Description: Key type to be generated, options are: swift, s3 (default). | |
596 | :Type: String | |
597 | :Example: ``s3`` | |
598 | :Required: No | |
599 | ||
600 | ``user-caps`` | |
601 | ||
602 | :Description: User capabilities. | |
603 | :Type: String | |
604 | :Example: ``usage=read, write; users=read`` | |
605 | :Required: No | |
606 | ||
607 | ``max-buckets`` | |
608 | ||
609 | :Description: Specify the maximum number of buckets the user can own. | |
610 | :Type: Integer | |
611 | :Example: 500 [1000] | |
612 | :Required: No | |
613 | ||
614 | ``suspended`` | |
615 | ||
616 | :Description: Specify whether the user should be suspended. | |
617 | :Type: Boolean | |
618 | :Example: False [False] | |
619 | :Required: No | |
620 | ||
621 | Response Entities | |
622 | ~~~~~~~~~~~~~~~~~ | |
623 | ||
624 | If successful, the response contains the user information. | |
625 | ||
626 | ``user`` | |
627 | ||
628 | :Description: A container for the user data information. | |
629 | :Type: Container | |
630 | ||
631 | ``user_id`` | |
632 | ||
633 | :Description: The user id. | |
634 | :Type: String | |
635 | :Parent: ``user`` | |
636 | ||
637 | ``display_name`` | |
638 | ||
639 | :Description: Display name for the user. | |
640 | :Type: String | |
641 | :Parent: ``user`` | |
642 | ||
643 | ||
644 | ``suspended`` | |
645 | ||
646 | :Description: True if the user is suspended. | |
647 | :Type: Boolean | |
648 | :Parent: ``user`` | |
649 | ||
650 | ||
651 | ``max_buckets`` | |
652 | ||
653 | :Description: The maximum number of buckets to be owned by the user. | |
654 | :Type: Integer | |
655 | :Parent: ``user`` | |
656 | ||
657 | ||
658 | ``subusers`` | |
659 | ||
660 | :Description: Subusers associated with this user account. | |
661 | :Type: Container | |
662 | :Parent: ``user`` | |
663 | ||
664 | ||
665 | ``keys`` | |
666 | ||
667 | :Description: S3 keys associated with this user account. | |
668 | :Type: Container | |
669 | :Parent: ``user`` | |
670 | ||
671 | ||
672 | ``swift_keys`` | |
673 | ||
674 | :Description: Swift keys associated with this user account. | |
675 | :Type: Container | |
676 | :Parent: ``user`` | |
677 | ||
678 | ||
679 | ``caps`` | |
680 | ||
681 | :Description: User capabilities. | |
682 | :Type: Container | |
683 | :Parent: ``user`` | |
684 | ||
685 | ||
686 | Special Error Responses | |
687 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
688 | ||
689 | ``InvalidAccessKey`` | |
690 | ||
691 | :Description: Invalid access key specified. | |
692 | :Code: 400 Bad Request | |
693 | ||
694 | ``InvalidKeyType`` | |
695 | ||
696 | :Description: Invalid key type specified. | |
697 | :Code: 400 Bad Request | |
698 | ||
699 | ``InvalidSecretKey`` | |
700 | ||
701 | :Description: Invalid secret key specified. | |
702 | :Code: 400 Bad Request | |
703 | ||
704 | ``KeyExists`` | |
705 | ||
706 | :Description: Provided access key exists and belongs to another user. | |
707 | :Code: 409 Conflict | |
708 | ||
709 | ``EmailExists`` | |
710 | ||
711 | :Description: Provided email address exists. | |
712 | :Code: 409 Conflict | |
713 | ||
714 | ``InvalidCapability`` | |
715 | ||
716 | :Description: Attempt to grant invalid admin capability. | |
717 | :Code: 400 Bad Request | |
718 | ||
719 | Remove User | |
720 | =========== | |
721 | ||
722 | Remove an existing user. | |
723 | ||
724 | :caps: users=write | |
725 | ||
726 | Syntax | |
727 | ~~~~~~ | |
728 | ||
729 | :: | |
730 | ||
731 | DELETE /{admin}/user?format=json HTTP/1.1 | |
732 | Host: {fqdn} | |
733 | ||
734 | ||
735 | Request Parameters | |
736 | ~~~~~~~~~~~~~~~~~~ | |
737 | ||
738 | ``uid`` | |
739 | ||
740 | :Description: The user ID to be removed. | |
741 | :Type: String | |
742 | :Example: ``foo_user`` | |
743 | :Required: Yes. | |
744 | ||
745 | ``purge-data`` | |
746 | ||
747 | :Description: When specified the buckets and objects belonging | |
748 | to the user will also be removed. | |
749 | :Type: Boolean | |
750 | :Example: True | |
751 | :Required: No | |
752 | ||
753 | Response Entities | |
754 | ~~~~~~~~~~~~~~~~~ | |
755 | ||
756 | None | |
757 | ||
758 | Special Error Responses | |
759 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
760 | ||
761 | None. | |
762 | ||
763 | Create Subuser | |
764 | ============== | |
765 | ||
766 | Create a new subuser (primarily useful for clients using the Swift API). | |
767 | Note that in general for a subuser to be useful, it must be granted | |
768 | permissions by specifying ``access``. As with user creation if | |
769 | ``subuser`` is specified without ``secret``, then a secret key will | |
770 | be automatically generated. | |
771 | ||
772 | :caps: users=write | |
773 | ||
774 | Syntax | |
775 | ~~~~~~ | |
776 | ||
777 | :: | |
778 | ||
779 | PUT /{admin}/user?subuser&format=json HTTP/1.1 | |
780 | Host {fqdn} | |
781 | ||
782 | ||
783 | Request Parameters | |
784 | ~~~~~~~~~~~~~~~~~~ | |
785 | ||
786 | ``uid`` | |
787 | ||
788 | :Description: The user ID under which a subuser is to be created. | |
789 | :Type: String | |
790 | :Example: ``foo_user`` | |
791 | :Required: Yes | |
792 | ||
793 | ||
794 | ``subuser`` | |
795 | ||
796 | :Description: Specify the subuser ID to be created. | |
797 | :Type: String | |
798 | :Example: ``sub_foo`` | |
799 | :Required: Yes | |
800 | ||
801 | ``secret-key`` | |
802 | ||
803 | :Description: Specify secret key. | |
804 | :Type: String | |
805 | :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8`` | |
806 | :Required: No | |
807 | ||
808 | ``key-type`` | |
809 | ||
810 | :Description: Key type to be generated, options are: swift (default), s3. | |
811 | :Type: String | |
812 | :Example: ``swift`` [``swift``] | |
813 | :Required: No | |
814 | ||
815 | ``access`` | |
816 | ||
817 | :Description: Set access permissions for sub-user, should be one | |
818 | of ``read, write, readwrite, full``. | |
819 | :Type: String | |
820 | :Example: ``read`` | |
821 | :Required: No | |
822 | ||
823 | ``generate-secret`` | |
824 | ||
825 | :Description: Generate the secret key. | |
826 | :Type: Boolean | |
827 | :Example: True [False] | |
828 | :Required: No | |
829 | ||
830 | Response Entities | |
831 | ~~~~~~~~~~~~~~~~~ | |
832 | ||
833 | If successful, the response contains the subuser information. | |
834 | ||
835 | ||
836 | ``subusers`` | |
837 | ||
838 | :Description: Subusers associated with the user account. | |
839 | :Type: Container | |
840 | ||
841 | ``id`` | |
842 | ||
843 | :Description: Subuser id. | |
844 | :Type: String | |
845 | :Parent: ``subusers`` | |
846 | ||
847 | ``permissions`` | |
848 | ||
849 | :Description: Subuser access to user account. | |
850 | :Type: String | |
851 | :Parent: ``subusers`` | |
852 | ||
853 | Special Error Responses | |
854 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
855 | ||
856 | ``SubuserExists`` | |
857 | ||
858 | :Description: Specified subuser exists. | |
859 | :Code: 409 Conflict | |
860 | ||
861 | ``InvalidKeyType`` | |
862 | ||
863 | :Description: Invalid key type specified. | |
864 | :Code: 400 Bad Request | |
865 | ||
866 | ``InvalidSecretKey`` | |
867 | ||
868 | :Description: Invalid secret key specified. | |
869 | :Code: 400 Bad Request | |
870 | ||
871 | ``InvalidAccess`` | |
872 | ||
873 | :Description: Invalid subuser access specified. | |
874 | :Code: 400 Bad Request | |
875 | ||
876 | Modify Subuser | |
877 | ============== | |
878 | ||
879 | Modify an existing subuser | |
880 | ||
881 | :caps: users=write | |
882 | ||
883 | Syntax | |
884 | ~~~~~~ | |
885 | ||
886 | :: | |
887 | ||
888 | POST /{admin}/user?subuser&format=json HTTP/1.1 | |
889 | Host {fqdn} | |
890 | ||
891 | ||
892 | Request Parameters | |
893 | ~~~~~~~~~~~~~~~~~~ | |
894 | ||
895 | ``uid`` | |
896 | ||
897 | :Description: The user ID under which the subuser is to be modified. | |
898 | :Type: String | |
899 | :Example: ``foo_user`` | |
900 | :Required: Yes | |
901 | ||
902 | ``subuser`` | |
903 | ||
904 | :Description: The subuser ID to be modified. | |
905 | :Type: String | |
906 | :Example: ``sub_foo`` | |
907 | :Required: Yes | |
908 | ||
909 | ``generate-secret`` | |
910 | ||
911 | :Description: Generate a new secret key for the subuser, | |
912 | replacing the existing key. | |
913 | :Type: Boolean | |
914 | :Example: True [False] | |
915 | :Required: No | |
916 | ||
917 | ``secret`` | |
918 | ||
919 | :Description: Specify secret key. | |
920 | :Type: String | |
921 | :Example: ``0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8`` | |
922 | :Required: No | |
923 | ||
924 | ``key-type`` | |
925 | ||
926 | :Description: Key type to be generated, options are: swift (default), s3 . | |
927 | :Type: String | |
928 | :Example: ``swift`` [``swift``] | |
929 | :Required: No | |
930 | ||
931 | ``access`` | |
932 | ||
933 | :Description: Set access permissions for sub-user, should be one | |
934 | of ``read, write, readwrite, full``. | |
935 | :Type: String | |
936 | :Example: ``read`` | |
937 | :Required: No | |
938 | ||
939 | ||
940 | Response Entities | |
941 | ~~~~~~~~~~~~~~~~~ | |
942 | ||
943 | If successful, the response contains the subuser information. | |
944 | ||
945 | ||
946 | ``subusers`` | |
947 | ||
948 | :Description: Subusers associated with the user account. | |
949 | :Type: Container | |
950 | ||
951 | ``id`` | |
952 | ||
953 | :Description: Subuser id. | |
954 | :Type: String | |
955 | :Parent: ``subusers`` | |
956 | ||
957 | ``permissions`` | |
958 | ||
959 | :Description: Subuser access to user account. | |
960 | :Type: String | |
961 | :Parent: ``subusers`` | |
962 | ||
963 | Special Error Responses | |
964 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
965 | ||
966 | ``InvalidKeyType`` | |
967 | ||
968 | :Description: Invalid key type specified. | |
969 | :Code: 400 Bad Request | |
970 | ||
971 | ``InvalidSecretKey`` | |
972 | ||
973 | :Description: Invalid secret key specified. | |
974 | :Code: 400 Bad Request | |
975 | ||
976 | ``InvalidAccess`` | |
977 | ||
978 | :Description: Invalid subuser access specified. | |
979 | :Code: 400 Bad Request | |
980 | ||
981 | Remove Subuser | |
982 | ============== | |
983 | ||
984 | Remove an existing subuser | |
985 | ||
986 | :caps: users=write | |
987 | ||
988 | Syntax | |
989 | ~~~~~~ | |
990 | ||
991 | :: | |
992 | ||
993 | DELETE /{admin}/user?subuser&format=json HTTP/1.1 | |
994 | Host {fqdn} | |
995 | ||
996 | ||
997 | Request Parameters | |
998 | ~~~~~~~~~~~~~~~~~~ | |
999 | ||
1000 | ``uid`` | |
1001 | ||
1002 | :Description: The user ID under which the subuser is to be removed. | |
1003 | :Type: String | |
1004 | :Example: ``foo_user`` | |
1005 | :Required: Yes | |
1006 | ||
1007 | ||
1008 | ``subuser`` | |
1009 | ||
1010 | :Description: The subuser ID to be removed. | |
1011 | :Type: String | |
1012 | :Example: ``sub_foo`` | |
1013 | :Required: Yes | |
1014 | ||
1015 | ``purge-keys`` | |
1016 | ||
1017 | :Description: Remove keys belonging to the subuser. | |
1018 | :Type: Boolean | |
1019 | :Example: True [True] | |
1020 | :Required: No | |
1021 | ||
1022 | Response Entities | |
1023 | ~~~~~~~~~~~~~~~~~ | |
1024 | ||
1025 | None. | |
1026 | ||
1027 | Special Error Responses | |
1028 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1029 | None. | |
1030 | ||
1031 | Create Key | |
1032 | ========== | |
1033 | ||
1034 | Create a new key. If a ``subuser`` is specified then by default created keys | |
1035 | will be swift type. If only one of ``access-key`` or ``secret-key`` is provided the | |
1036 | committed key will be automatically generated, that is if only ``secret-key`` is | |
1037 | specified then ``access-key`` will be automatically generated. By default, a | |
1038 | generated key is added to the keyring without replacing an existing key pair. | |
1039 | If ``access-key`` is specified and refers to an existing key owned by the user | |
1040 | then it will be modified. The response is a container listing all keys of the same | |
1041 | type as the key created. Note that when creating a swift key, specifying the option | |
1042 | ``access-key`` will have no effect. Additionally, only one swift key may be held by | |
1043 | each user or subuser. | |
1044 | ||
1045 | :caps: users=write | |
1046 | ||
1047 | ||
1048 | Syntax | |
1049 | ~~~~~~ | |
1050 | ||
1051 | :: | |
1052 | ||
1053 | PUT /{admin}/user?key&format=json HTTP/1.1 | |
1054 | Host {fqdn} | |
1055 | ||
1056 | ||
1057 | Request Parameters | |
1058 | ~~~~~~~~~~~~~~~~~~ | |
1059 | ||
1060 | ``uid`` | |
1061 | ||
1062 | :Description: The user ID to receive the new key. | |
1063 | :Type: String | |
1064 | :Example: ``foo_user`` | |
1065 | :Required: Yes | |
1066 | ||
1067 | ``subuser`` | |
1068 | ||
1069 | :Description: The subuser ID to receive the new key. | |
1070 | :Type: String | |
1071 | :Example: ``sub_foo`` | |
1072 | :Required: No | |
1073 | ||
1074 | ``key-type`` | |
1075 | ||
1076 | :Description: Key type to be generated, options are: swift, s3 (default). | |
1077 | :Type: String | |
1078 | :Example: ``s3`` [``s3``] | |
1079 | :Required: No | |
1080 | ||
1081 | ``access-key`` | |
1082 | ||
1083 | :Description: Specify the access key. | |
1084 | :Type: String | |
1085 | :Example: ``AB01C2D3EF45G6H7IJ8K`` | |
1086 | :Required: No | |
1087 | ||
1088 | ``secret-key`` | |
1089 | ||
1090 | :Description: Specify the secret key. | |
1091 | :Type: String | |
1092 | :Example: ``0ab/CdeFGhij1klmnopqRSTUv1WxyZabcDEFgHij`` | |
1093 | :Required: No | |
1094 | ||
1095 | ``generate-key`` | |
1096 | ||
1097 | :Description: Generate a new key pair and add to the existing keyring. | |
1098 | :Type: Boolean | |
1099 | :Example: True [``True``] | |
1100 | :Required: No | |
1101 | ||
1102 | ||
1103 | Response Entities | |
1104 | ~~~~~~~~~~~~~~~~~ | |
1105 | ||
1106 | ``keys`` | |
1107 | ||
1108 | :Description: Keys of type created associated with this user account. | |
1109 | :Type: Container | |
1110 | ||
1111 | ``user`` | |
1112 | ||
1113 | :Description: The user account associated with the key. | |
1114 | :Type: String | |
1115 | :Parent: ``keys`` | |
1116 | ||
1117 | ``access-key`` | |
1118 | ||
1119 | :Description: The access key. | |
1120 | :Type: String | |
1121 | :Parent: ``keys`` | |
1122 | ||
1123 | ``secret-key`` | |
1124 | ||
1125 | :Description: The secret key | |
1126 | :Type: String | |
1127 | :Parent: ``keys`` | |
1128 | ||
1129 | ||
1130 | Special Error Responses | |
1131 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1132 | ||
1133 | ``InvalidAccessKey`` | |
1134 | ||
1135 | :Description: Invalid access key specified. | |
1136 | :Code: 400 Bad Request | |
1137 | ||
1138 | ``InvalidKeyType`` | |
1139 | ||
1140 | :Description: Invalid key type specified. | |
1141 | :Code: 400 Bad Request | |
1142 | ||
1143 | ``InvalidSecretKey`` | |
1144 | ||
1145 | :Description: Invalid secret key specified. | |
1146 | :Code: 400 Bad Request | |
1147 | ||
1148 | ``InvalidKeyType`` | |
1149 | ||
1150 | :Description: Invalid key type specified. | |
1151 | :Code: 400 Bad Request | |
1152 | ||
1153 | ``KeyExists`` | |
1154 | ||
1155 | :Description: Provided access key exists and belongs to another user. | |
1156 | :Code: 409 Conflict | |
1157 | ||
1158 | Remove Key | |
1159 | ========== | |
1160 | ||
1161 | Remove an existing key. | |
1162 | ||
1163 | :caps: users=write | |
1164 | ||
1165 | Syntax | |
1166 | ~~~~~~ | |
1167 | ||
1168 | :: | |
1169 | ||
1170 | DELETE /{admin}/user?key&format=json HTTP/1.1 | |
1171 | Host {fqdn} | |
1172 | ||
1173 | ||
1174 | Request Parameters | |
1175 | ~~~~~~~~~~~~~~~~~~ | |
1176 | ||
1177 | ``access-key`` | |
1178 | ||
1179 | :Description: The S3 access key belonging to the S3 key pair to remove. | |
1180 | :Type: String | |
1181 | :Example: ``AB01C2D3EF45G6H7IJ8K`` | |
1182 | :Required: Yes | |
1183 | ||
1184 | ``uid`` | |
1185 | ||
1186 | :Description: The user to remove the key from. | |
1187 | :Type: String | |
1188 | :Example: ``foo_user`` | |
1189 | :Required: No | |
1190 | ||
1191 | ``subuser`` | |
1192 | ||
1193 | :Description: The subuser to remove the key from. | |
1194 | :Type: String | |
1195 | :Example: ``sub_foo`` | |
1196 | :Required: No | |
1197 | ||
1198 | ``key-type`` | |
1199 | ||
1200 | :Description: Key type to be removed, options are: swift, s3. | |
1201 | NOTE: Required to remove swift key. | |
1202 | :Type: String | |
1203 | :Example: ``swift`` | |
1204 | :Required: No | |
1205 | ||
1206 | Special Error Responses | |
1207 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1208 | ||
1209 | None. | |
1210 | ||
1211 | Response Entities | |
1212 | ~~~~~~~~~~~~~~~~~ | |
1213 | ||
1214 | None. | |
1215 | ||
1216 | Get Bucket Info | |
1217 | =============== | |
1218 | ||
1219 | Get information about a subset of the existing buckets. If ``uid`` is specified | |
1220 | without ``bucket`` then all buckets beloning to the user will be returned. If | |
1221 | ``bucket`` alone is specified, information for that particular bucket will be | |
1222 | retrieved. | |
1223 | ||
1224 | :caps: buckets=read | |
1225 | ||
1226 | Syntax | |
1227 | ~~~~~~ | |
1228 | ||
1229 | :: | |
1230 | ||
1231 | GET /{admin}/bucket?format=json HTTP/1.1 | |
1232 | Host {fqdn} | |
1233 | ||
1234 | ||
1235 | Request Parameters | |
1236 | ~~~~~~~~~~~~~~~~~~ | |
1237 | ||
1238 | ``bucket`` | |
1239 | ||
1240 | :Description: The bucket to return info on. | |
1241 | :Type: String | |
1242 | :Example: ``foo_bucket`` | |
1243 | :Required: No | |
1244 | ||
1245 | ``uid`` | |
1246 | ||
1247 | :Description: The user to retrieve bucket information for. | |
1248 | :Type: String | |
1249 | :Example: ``foo_user`` | |
1250 | :Required: No | |
1251 | ||
1252 | ``stats`` | |
1253 | ||
1254 | :Description: Return bucket statistics. | |
1255 | :Type: Boolean | |
1256 | :Example: True [False] | |
1257 | :Required: No | |
1258 | ||
1259 | Response Entities | |
1260 | ~~~~~~~~~~~~~~~~~ | |
1261 | ||
1262 | If successful the request returns a buckets container containing | |
1263 | the desired bucket information. | |
1264 | ||
1265 | ``stats`` | |
1266 | ||
1267 | :Description: Per bucket information. | |
1268 | :Type: Container | |
1269 | ||
1270 | ``buckets`` | |
1271 | ||
1272 | :Description: Contains a list of one or more bucket containers. | |
1273 | :Type: Container | |
1274 | ||
1275 | ``bucket`` | |
1276 | ||
1277 | :Description: Container for single bucket information. | |
1278 | :Type: Container | |
1279 | :Parent: ``buckets`` | |
1280 | ||
1281 | ``name`` | |
1282 | ||
1283 | :Description: The name of the bucket. | |
1284 | :Type: String | |
1285 | :Parent: ``bucket`` | |
1286 | ||
1287 | ``pool`` | |
1288 | ||
1289 | :Description: The pool the bucket is stored in. | |
1290 | :Type: String | |
1291 | :Parent: ``bucket`` | |
1292 | ||
1293 | ``id`` | |
1294 | ||
1295 | :Description: The unique bucket id. | |
1296 | :Type: String | |
1297 | :Parent: ``bucket`` | |
1298 | ||
1299 | ``marker`` | |
1300 | ||
1301 | :Description: Internal bucket tag. | |
1302 | :Type: String | |
1303 | :Parent: ``bucket`` | |
1304 | ||
1305 | ``owner`` | |
1306 | ||
1307 | :Description: The user id of the bucket owner. | |
1308 | :Type: String | |
1309 | :Parent: ``bucket`` | |
1310 | ||
1311 | ``usage`` | |
1312 | ||
1313 | :Description: Storage usage information. | |
1314 | :Type: Container | |
1315 | :Parent: ``bucket`` | |
1316 | ||
1317 | ``index`` | |
1318 | ||
1319 | :Description: Status of bucket index. | |
1320 | :Type: String | |
1321 | :Parent: ``bucket`` | |
1322 | ||
1323 | Special Error Responses | |
1324 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1325 | ||
1326 | ``IndexRepairFailed`` | |
1327 | ||
1328 | :Description: Bucket index repair failed. | |
1329 | :Code: 409 Conflict | |
1330 | ||
1331 | Check Bucket Index | |
1332 | ================== | |
1333 | ||
1334 | Check the index of an existing bucket. NOTE: to check multipart object | |
1335 | accounting with ``check-objects``, ``fix`` must be set to True. | |
1336 | ||
1337 | :caps: buckets=write | |
1338 | ||
1339 | Syntax | |
1340 | ~~~~~~ | |
1341 | ||
1342 | :: | |
1343 | ||
1344 | GET /{admin}/bucket?index&format=json HTTP/1.1 | |
1345 | Host {fqdn} | |
1346 | ||
1347 | ||
1348 | Request Parameters | |
1349 | ~~~~~~~~~~~~~~~~~~ | |
1350 | ||
1351 | ``bucket`` | |
1352 | ||
1353 | :Description: The bucket to return info on. | |
1354 | :Type: String | |
1355 | :Example: ``foo_bucket`` | |
1356 | :Required: Yes | |
1357 | ||
1358 | ``check-objects`` | |
1359 | ||
1360 | :Description: Check multipart object accounting. | |
1361 | :Type: Boolean | |
1362 | :Example: True [False] | |
1363 | :Required: No | |
1364 | ||
1365 | ``fix`` | |
1366 | ||
1367 | :Description: Also fix the bucket index when checking. | |
1368 | :Type: Boolean | |
1369 | :Example: False [False] | |
1370 | :Required: No | |
1371 | ||
1372 | Response Entities | |
1373 | ~~~~~~~~~~~~~~~~~ | |
1374 | ||
1375 | ``index`` | |
1376 | ||
1377 | :Description: Status of bucket index. | |
1378 | :Type: String | |
1379 | ||
1380 | Special Error Responses | |
1381 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1382 | ||
1383 | ``IndexRepairFailed`` | |
1384 | ||
1385 | :Description: Bucket index repair failed. | |
1386 | :Code: 409 Conflict | |
1387 | ||
1388 | Remove Bucket | |
1389 | ============= | |
1390 | ||
1391 | Delete an existing bucket. | |
1392 | ||
1393 | :caps: buckets=write | |
1394 | ||
1395 | Syntax | |
1396 | ~~~~~~ | |
1397 | ||
1398 | :: | |
1399 | ||
1400 | DELETE /{admin}/bucket?format=json HTTP/1.1 | |
1401 | Host {fqdn} | |
1402 | ||
1403 | ||
1404 | ||
1405 | Request Parameters | |
1406 | ~~~~~~~~~~~~~~~~~~ | |
1407 | ||
1408 | ``bucket`` | |
1409 | ||
1410 | :Description: The bucket to remove. | |
1411 | :Type: String | |
1412 | :Example: ``foo_bucket`` | |
1413 | :Required: Yes | |
1414 | ||
1415 | ``purge-objects`` | |
1416 | ||
1417 | :Description: Remove a buckets objects before deletion. | |
1418 | :Type: Boolean | |
1419 | :Example: True [False] | |
1420 | :Required: No | |
1421 | ||
1422 | Response Entities | |
1423 | ~~~~~~~~~~~~~~~~~ | |
1424 | ||
1425 | None. | |
1426 | ||
1427 | Special Error Responses | |
1428 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1429 | ||
1430 | ``BucketNotEmpty`` | |
1431 | ||
1432 | :Description: Attempted to delete non-empty bucket. | |
1433 | :Code: 409 Conflict | |
1434 | ||
1435 | ``ObjectRemovalFailed`` | |
1436 | ||
1437 | :Description: Unable to remove objects. | |
1438 | :Code: 409 Conflict | |
1439 | ||
1440 | Unlink Bucket | |
1441 | ============= | |
1442 | ||
1443 | Unlink a bucket from a specified user. Primarily useful for changing | |
1444 | bucket ownership. | |
1445 | ||
1446 | :caps: buckets=write | |
1447 | ||
1448 | Syntax | |
1449 | ~~~~~~ | |
1450 | ||
1451 | :: | |
1452 | ||
1453 | POST /{admin}/bucket?format=json HTTP/1.1 | |
1454 | Host {fqdn} | |
1455 | ||
1456 | ||
1457 | Request Parameters | |
1458 | ~~~~~~~~~~~~~~~~~~ | |
1459 | ||
1460 | ``bucket`` | |
1461 | ||
1462 | :Description: The bucket to unlink. | |
1463 | :Type: String | |
1464 | :Example: ``foo_bucket`` | |
1465 | :Required: Yes | |
1466 | ||
1467 | ``uid`` | |
1468 | ||
1469 | :Description: The user ID to unlink the bucket from. | |
1470 | :Type: String | |
1471 | :Example: ``foo_user`` | |
1472 | :Required: Yes | |
1473 | ||
1474 | Response Entities | |
1475 | ~~~~~~~~~~~~~~~~~ | |
1476 | ||
1477 | None. | |
1478 | ||
1479 | Special Error Responses | |
1480 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1481 | ||
1482 | ``BucketUnlinkFailed`` | |
1483 | ||
1484 | :Description: Unable to unlink bucket from specified user. | |
1485 | :Code: 409 Conflict | |
1486 | ||
1487 | Link Bucket | |
1488 | =========== | |
1489 | ||
1490 | Link a bucket to a specified user, unlinking the bucket from | |
1491 | any previous user. | |
1492 | ||
1493 | :caps: buckets=write | |
1494 | ||
1495 | Syntax | |
1496 | ~~~~~~ | |
1497 | ||
1498 | :: | |
1499 | ||
1500 | PUT /{admin}/bucket?format=json HTTP/1.1 | |
1501 | Host {fqdn} | |
1502 | ||
1503 | ||
1504 | Request Parameters | |
1505 | ~~~~~~~~~~~~~~~~~~ | |
1506 | ||
1507 | ``bucket`` | |
1508 | ||
1509 | :Description: The bucket name to unlink. | |
1510 | :Type: String | |
1511 | :Example: ``foo_bucket`` | |
1512 | :Required: Yes | |
1513 | ||
1514 | ``bucket-id`` | |
1515 | ||
1516 | :Description: The bucket id to unlink. | |
1517 | :Type: String | |
1518 | :Example: ``dev.6607669.420`` | |
1519 | :Required: Yes | |
1520 | ||
1521 | ``uid`` | |
1522 | ||
1523 | :Description: The user ID to link the bucket to. | |
1524 | :Type: String | |
1525 | :Example: ``foo_user`` | |
1526 | :Required: Yes | |
1527 | ||
1528 | Response Entities | |
1529 | ~~~~~~~~~~~~~~~~~ | |
1530 | ||
1531 | ``bucket`` | |
1532 | ||
1533 | :Description: Container for single bucket information. | |
1534 | :Type: Container | |
1535 | ||
1536 | ``name`` | |
1537 | ||
1538 | :Description: The name of the bucket. | |
1539 | :Type: String | |
1540 | :Parent: ``bucket`` | |
1541 | ||
1542 | ``pool`` | |
1543 | ||
1544 | :Description: The pool the bucket is stored in. | |
1545 | :Type: String | |
1546 | :Parent: ``bucket`` | |
1547 | ||
1548 | ``id`` | |
1549 | ||
1550 | :Description: The unique bucket id. | |
1551 | :Type: String | |
1552 | :Parent: ``bucket`` | |
1553 | ||
1554 | ``marker`` | |
1555 | ||
1556 | :Description: Internal bucket tag. | |
1557 | :Type: String | |
1558 | :Parent: ``bucket`` | |
1559 | ||
1560 | ``owner`` | |
1561 | ||
1562 | :Description: The user id of the bucket owner. | |
1563 | :Type: String | |
1564 | :Parent: ``bucket`` | |
1565 | ||
1566 | ``usage`` | |
1567 | ||
1568 | :Description: Storage usage information. | |
1569 | :Type: Container | |
1570 | :Parent: ``bucket`` | |
1571 | ||
1572 | ``index`` | |
1573 | ||
1574 | :Description: Status of bucket index. | |
1575 | :Type: String | |
1576 | :Parent: ``bucket`` | |
1577 | ||
1578 | Special Error Responses | |
1579 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1580 | ||
1581 | ``BucketUnlinkFailed`` | |
1582 | ||
1583 | :Description: Unable to unlink bucket from specified user. | |
1584 | :Code: 409 Conflict | |
1585 | ||
1586 | ``BucketLinkFailed`` | |
1587 | ||
1588 | :Description: Unable to link bucket to specified user. | |
1589 | :Code: 409 Conflict | |
1590 | ||
1591 | Remove Object | |
1592 | ============= | |
1593 | ||
1594 | Remove an existing object. NOTE: Does not require owner to be non-suspended. | |
1595 | ||
1596 | :caps: buckets=write | |
1597 | ||
1598 | Syntax | |
1599 | ~~~~~~ | |
1600 | ||
1601 | :: | |
1602 | ||
1603 | DELETE /{admin}/bucket?object&format=json HTTP/1.1 | |
1604 | Host {fqdn} | |
1605 | ||
1606 | Request Parameters | |
1607 | ~~~~~~~~~~~~~~~~~~ | |
1608 | ||
1609 | ``bucket`` | |
1610 | ||
1611 | :Description: The bucket containing the object to be removed. | |
1612 | :Type: String | |
1613 | :Example: ``foo_bucket`` | |
1614 | :Required: Yes | |
1615 | ||
1616 | ``object`` | |
1617 | ||
1618 | :Description: The object to remove. | |
1619 | :Type: String | |
1620 | :Example: ``foo.txt`` | |
1621 | :Required: Yes | |
1622 | ||
1623 | Response Entities | |
1624 | ~~~~~~~~~~~~~~~~~ | |
1625 | ||
1626 | None. | |
1627 | ||
1628 | Special Error Responses | |
1629 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1630 | ||
1631 | ``NoSuchObject`` | |
1632 | ||
1633 | :Description: Specified object does not exist. | |
1634 | :Code: 404 Not Found | |
1635 | ||
1636 | ``ObjectRemovalFailed`` | |
1637 | ||
1638 | :Description: Unable to remove objects. | |
1639 | :Code: 409 Conflict | |
1640 | ||
1641 | ||
1642 | ||
1643 | Get Bucket or Object Policy | |
1644 | =========================== | |
1645 | ||
1646 | Read the policy of an object or bucket. | |
1647 | ||
1648 | :caps: buckets=read | |
1649 | ||
1650 | Syntax | |
1651 | ~~~~~~ | |
1652 | ||
1653 | :: | |
1654 | ||
1655 | GET /{admin}/bucket?policy&format=json HTTP/1.1 | |
1656 | Host {fqdn} | |
1657 | ||
1658 | ||
1659 | Request Parameters | |
1660 | ~~~~~~~~~~~~~~~~~~ | |
1661 | ||
1662 | ``bucket`` | |
1663 | ||
1664 | :Description: The bucket to read the policy from. | |
1665 | :Type: String | |
1666 | :Example: ``foo_bucket`` | |
1667 | :Required: Yes | |
1668 | ||
1669 | ``object`` | |
1670 | ||
1671 | :Description: The object to read the policy from. | |
1672 | :Type: String | |
1673 | :Example: ``foo.txt`` | |
1674 | :Required: No | |
1675 | ||
1676 | Response Entities | |
1677 | ~~~~~~~~~~~~~~~~~ | |
1678 | ||
1679 | If successful, returns the object or bucket policy | |
1680 | ||
1681 | ``policy`` | |
1682 | ||
1683 | :Description: Access control policy. | |
1684 | :Type: Container | |
1685 | ||
1686 | Special Error Responses | |
1687 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1688 | ||
1689 | ``IncompleteBody`` | |
1690 | ||
1691 | :Description: Either bucket was not specified for a bucket policy request or bucket | |
1692 | and object were not specified for an object policy request. | |
1693 | :Code: 400 Bad Request | |
1694 | ||
1695 | Add A User Capability | |
1696 | ===================== | |
1697 | ||
1698 | Add an administrative capability to a specified user. | |
1699 | ||
1700 | :caps: users=write | |
1701 | ||
1702 | Syntax | |
1703 | ~~~~~~ | |
1704 | ||
1705 | :: | |
1706 | ||
1707 | PUT /{admin}/user?caps&format=json HTTP/1.1 | |
1708 | Host {fqdn} | |
1709 | ||
1710 | Request Parameters | |
1711 | ~~~~~~~~~~~~~~~~~~ | |
1712 | ||
1713 | ``uid`` | |
1714 | ||
1715 | :Description: The user ID to add an administrative capability to. | |
1716 | :Type: String | |
1717 | :Example: ``foo_user`` | |
1718 | :Required: Yes | |
1719 | ||
1720 | ``user-caps`` | |
1721 | ||
1722 | :Description: The administrative capability to add to the user. | |
1723 | :Type: String | |
1724 | :Example: ``usage=read,write;user=write`` | |
1725 | :Required: Yes | |
1726 | ||
1727 | Response Entities | |
1728 | ~~~~~~~~~~~~~~~~~ | |
1729 | ||
1730 | If successful, the response contains the user's capabilities. | |
1731 | ||
1732 | ``user`` | |
1733 | ||
1734 | :Description: A container for the user data information. | |
1735 | :Type: Container | |
1736 | :Parent: ``user`` | |
1737 | ||
1738 | ``user_id`` | |
1739 | ||
1740 | :Description: The user id. | |
1741 | :Type: String | |
1742 | :Parent: ``user`` | |
1743 | ||
1744 | ``caps`` | |
1745 | ||
1746 | :Description: User capabilities. | |
1747 | :Type: Container | |
1748 | :Parent: ``user`` | |
1749 | ||
1750 | ||
1751 | Special Error Responses | |
1752 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1753 | ||
1754 | ``InvalidCapability`` | |
1755 | ||
1756 | :Description: Attempt to grant invalid admin capability. | |
1757 | :Code: 400 Bad Request | |
1758 | ||
1759 | Example Request | |
1760 | ~~~~~~~~~~~~~~~ | |
1761 | ||
1762 | :: | |
1763 | ||
1764 | PUT /{admin}/user?caps&user-caps=usage=read,write;user=write&format=json HTTP/1.1 | |
1765 | Host: {fqdn} | |
1766 | Content-Type: text/plain | |
1767 | Authorization: {your-authorization-token} | |
1768 | ||
1769 | ||
1770 | ||
1771 | Remove A User Capability | |
1772 | ======================== | |
1773 | ||
1774 | Remove an administrative capability from a specified user. | |
1775 | ||
1776 | :caps: users=write | |
1777 | ||
1778 | Syntax | |
1779 | ~~~~~~ | |
1780 | ||
1781 | :: | |
1782 | ||
1783 | DELETE /{admin}/user?caps&format=json HTTP/1.1 | |
1784 | Host {fqdn} | |
1785 | ||
1786 | Request Parameters | |
1787 | ~~~~~~~~~~~~~~~~~~ | |
1788 | ||
1789 | ``uid`` | |
1790 | ||
1791 | :Description: The user ID to remove an administrative capability from. | |
1792 | :Type: String | |
1793 | :Example: ``foo_user`` | |
1794 | :Required: Yes | |
1795 | ||
1796 | ``user-caps`` | |
1797 | ||
1798 | :Description: The administrative capabilities to remove from the user. | |
1799 | :Type: String | |
1800 | :Example: ``usage=read, write`` | |
1801 | :Required: Yes | |
1802 | ||
1803 | Response Entities | |
1804 | ~~~~~~~~~~~~~~~~~ | |
1805 | ||
1806 | If successful, the response contains the user's capabilities. | |
1807 | ||
1808 | ``user`` | |
1809 | ||
1810 | :Description: A container for the user data information. | |
1811 | :Type: Container | |
1812 | :Parent: ``user`` | |
1813 | ||
1814 | ``user_id`` | |
1815 | ||
1816 | :Description: The user id. | |
1817 | :Type: String | |
1818 | :Parent: ``user`` | |
1819 | ||
1820 | ``caps`` | |
1821 | ||
1822 | :Description: User capabilities. | |
1823 | :Type: Container | |
1824 | :Parent: ``user`` | |
1825 | ||
1826 | ||
1827 | Special Error Responses | |
1828 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
1829 | ||
1830 | ``InvalidCapability`` | |
1831 | ||
1832 | :Description: Attempt to remove an invalid admin capability. | |
1833 | :Code: 400 Bad Request | |
1834 | ||
1835 | ``NoSuchCap`` | |
1836 | ||
1837 | :Description: User does not possess specified capability. | |
1838 | :Code: 404 Not Found | |
1839 | ||
7c673cae FG |
1840 | |
1841 | Quotas | |
1842 | ====== | |
1843 | ||
1844 | The Admin Operations API enables you to set quotas on users and on bucket owned | |
1845 | by users. See `Quota Management`_ for additional details. Quotas include the | |
1846 | maximum number of objects in a bucket and the maximum storage size in megabytes. | |
1847 | ||
1848 | To view quotas, the user must have a ``users=read`` capability. To set, | |
1849 | modify or disable a quota, the user must have ``users=write`` capability. | |
1850 | See the `Admin Guide`_ for details. | |
1851 | ||
1852 | Valid parameters for quotas include: | |
1853 | ||
1854 | - **Bucket:** The ``bucket`` option allows you to specify a quota for | |
1855 | buckets owned by a user. | |
1856 | ||
1857 | - **Maximum Objects:** The ``max-objects`` setting allows you to specify | |
1858 | the maximum number of objects. A negative value disables this setting. | |
1859 | ||
1860 | - **Maximum Size:** The ``max-size`` option allows you to specify a quota | |
1861 | for the maximum number of bytes. A negative value disables this setting. | |
1862 | ||
1863 | - **Quota Type:** The ``quota-type`` option sets the scope for the quota. | |
1864 | The options are ``bucket`` and ``user``. | |
1865 | ||
1866 | - **Enable/Disable Quota:** The ``enabled`` option specifies whether the | |
1867 | quota should be enabled. The value should be either 'True' or 'False'. | |
1868 | ||
1869 | Get User Quota | |
1870 | ~~~~~~~~~~~~~~ | |
1871 | ||
1872 | To get a quota, the user must have ``users`` capability set with ``read`` | |
1873 | permission. :: | |
1874 | ||
1875 | GET /admin/user?quota&uid=<uid>"a-type=user | |
1876 | ||
1877 | ||
1878 | Set User Quota | |
1879 | ~~~~~~~~~~~~~~ | |
1880 | ||
1881 | To set a quota, the user must have ``users`` capability set with ``write`` | |
1882 | permission. :: | |
1883 | ||
1884 | PUT /admin/user?quota&uid=<uid>"a-type=user | |
1885 | ||
1886 | ||
1887 | The content must include a JSON representation of the quota settings | |
1888 | as encoded in the corresponding read operation. | |
1889 | ||
1890 | ||
1891 | Get Bucket Quota | |
1892 | ~~~~~~~~~~~~~~~~ | |
1893 | ||
1894 | To get a quota, the user must have ``users`` capability set with ``read`` | |
1895 | permission. :: | |
1896 | ||
1897 | GET /admin/user?quota&uid=<uid>"a-type=bucket | |
1898 | ||
1899 | ||
1900 | Set Bucket Quota | |
1901 | ~~~~~~~~~~~~~~~~ | |
1902 | ||
1903 | To set a quota, the user must have ``users`` capability set with ``write`` | |
1904 | permission. :: | |
1905 | ||
1906 | PUT /admin/user?quota&uid=<uid>"a-type=bucket | |
1907 | ||
1908 | The content must include a JSON representation of the quota settings | |
1909 | as encoded in the corresponding read operation. | |
1910 | ||
1911 | ||
1912 | ||
1913 | ||
1914 | Standard Error Responses | |
1915 | ======================== | |
1916 | ||
1917 | ``AccessDenied`` | |
1918 | ||
1919 | :Description: Access denied. | |
1920 | :Code: 403 Forbidden | |
1921 | ||
1922 | ``InternalError`` | |
1923 | ||
1924 | :Description: Internal server error. | |
1925 | :Code: 500 Internal Server Error | |
1926 | ||
1927 | ``NoSuchUser`` | |
1928 | ||
1929 | :Description: User does not exist. | |
1930 | :Code: 404 Not Found | |
1931 | ||
1932 | ``NoSuchBucket`` | |
1933 | ||
1934 | :Description: Bucket does not exist. | |
1935 | :Code: 404 Not Found | |
1936 | ||
1937 | ``NoSuchKey`` | |
1938 | ||
1939 | :Description: No such access key. | |
1940 | :Code: 404 Not Found | |
1941 | ||
1942 | ||
1943 | ||
1944 | .. _Admin Guide: ../admin | |
1945 | .. _Quota Management: ../admin#quota-management | |
d2e6a577 | 1946 | .. _Multitenancy: ./multitenancy |