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