src/ceph/doc/radosgw/adminops.rst

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