ceph/doc/radosgw/adminops.rst

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