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