ceph/doc/man/8/radosgw-admin.rst

   1 :orphan:
   2
   3 =================================================================
   4  radosgw-admin -- rados REST gateway user administration utility
   5 =================================================================
   6
   7 .. program:: radosgw-admin
   8
   9 Synopsis
  10 ========
  11
  12 | **radosgw-admin** *command* [ *options* *...* ]
  13
  14
  15 Description
  16 ===========
  17
  18 :program:`radosgw-admin` is a RADOS gateway user administration utility. It
  19 allows creating and modifying users.
  20
  21
  22 Commands
  23 ========
  24
  25 :program:`radosgw-admin` utility uses many commands for administration purpose
  26 which are as follows:
  27
  28 :command:`user create`
  29   Create a new user.
  30
  31 :command:`user modify`
  32   Modify a user.
  33
  34 :command:`user info`
  35   Display information of a user, and any potentially available
  36   subusers and keys.
  37
  38 :command:`user rm`
  39   Remove a user.
  40
  41 :command:`user suspend`
  42   Suspend a user.
  43
  44 :command:`user enable`
  45   Re-enable user after suspension.
  46
  47 :command:`user check`
  48   Check user info.
  49
  50 :command:`user stats`
  51   Show user stats as accounted by quota subsystem.
  52
  53 :command:`user list`
  54   List all users.
  55
  56 :command:`caps add`
  57   Add user capabilities.
  58
  59 :command:`caps rm`
  60   Remove user capabilities.
  61
  62 :command:`subuser create`
  63   Create a new subuser (primarily useful for clients using the Swift API).
  64
  65 :command:`subuser modify`
  66   Modify a subuser.
  67
  68 :command:`subuser rm`
  69   Remove a subuser.
  70
  71 :command:`key create`
  72   Create access key.
  73
  74 :command:`key rm`
  75   Remove access key.
  76
  77 :command:`bucket list`
  78   List buckets, or, if bucket specified with --bucket=<bucket>,
  79   list its objects. If bucket specified adding --allow-unordered
  80   removes ordering requirement, possibly generating results more
  81   quickly in buckets with large number of objects.
  82
  83 :command:`bucket limit check`
  84   Show bucket sharding stats.
  85
  86 :command:`bucket link`
  87   Link bucket to specified user.
  88
  89 :command:`bucket unlink`
  90   Unlink bucket from specified user.
  91
  92 :command:`bucket stats`
  93   Returns bucket statistics.
  94
  95 :command:`bucket rm`
  96   Remove a bucket.
  97
  98 :command:`bucket check`
  99   Check bucket index.
 100
 101 :command:`bucket rewrite`
 102   Rewrite all objects in the specified bucket.
 103
 104 :command:`bucket reshard`
 105   Reshard a bucket.
 106
 107 :command:`bucket sync disable`
 108   Disable bucket sync.
 109
 110 :command:`bucket sync enable`
 111   Enable bucket sync.
 112
 113 :command:`bi get`
 114   Retrieve bucket index object entries.
 115
 116 :command:`bi put`
 117   Store bucket index object entries.
 118
 119 :command:`bi list`
 120   List raw bucket index entries.
 121
 122 :command:`bi purge`
 123   Purge bucket index entries.
 124
 125 :command:`object rm`
 126   Remove an object.
 127
 128 :command:`object stat`
 129   Stat an object for its metadata.
 130
 131 :command:`object unlink`
 132   Unlink object from bucket index.
 133
 134 :command:`object rewrite`
 135   Rewrite the specified object.
 136
 137 :command:`objects expire`
 138   Run expired objects cleanup.
 139
 140 :command:`period rm`
 141   Remove a period.
 142
 143 :command:`period get`
 144   Get the period info.
 145
 146 :command:`period get-current`
 147   Get the current period info.
 148
 149 :command:`period pull`
 150   Pull a period.
 151
 152 :command:`period push`
 153   Push a period.
 154
 155 :command:`period list`
 156   List all periods.
 157
 158 :command:`period update`
 159   Update the staging period.
 160
 161 :command:`period commit`
 162   Commit the staging period.
 163
 164 :command:`quota set`
 165   Set quota params.
 166
 167 :command:`quota enable`
 168   Enable quota.
 169
 170 :command:`quota disable`
 171   Disable quota.
 172
 173 :command:`global quota get`
 174   View global quota parameters.
 175
 176 :command:`global quota set`
 177   Set global quota parameters.
 178
 179 :command:`global quota enable`
 180   Enable a global quota.
 181
 182 :command:`global quota disable`
 183   Disable a global quota.
 184
 185 :command:`realm create`
 186   Create a new realm.
 187
 188 :command:`realm rm`
 189   Remove a realm.
 190
 191 :command:`realm get`
 192   Show the realm info.
 193
 194 :command:`realm get-default`
 195   Get the default realm name.
 196
 197 :command:`realm list`
 198   List all realms.
 199
 200 :command:`realm list-periods`
 201   List all realm periods.
 202
 203 :command:`realm rename`
 204   Rename a realm.
 205
 206 :command:`realm set`
 207   Set the realm info (requires infile).
 208
 209 :command:`realm default`
 210   Set the realm as default.
 211
 212 :command:`realm pull`
 213   Pull a realm and its current period.
 214
 215 :command:`zonegroup add`
 216   Add a zone to a zonegroup.
 217
 218 :command:`zonegroup create`
 219   Create a new zone group info.
 220
 221 :command:`zonegroup default`
 222   Set the default zone group.
 223
 224 :command:`zonegroup rm`
 225   Remove a zone group info.
 226
 227 :command:`zonegroup get`
 228   Show the zone group info.
 229
 230 :command:`zonegroup modify`
 231   Modify an existing zonegroup.
 232
 233 :command:`zonegroup set`
 234   Set the zone group info (requires infile).
 235
 236 :command:`zonegroup remove`
 237   Remove a zone from a zonegroup.
 238
 239 :command:`zonegroup rename`
 240   Rename a zone group.
 241
 242 :command:`zonegroup list`
 243   List all zone groups set on this cluster.
 244
 245 :command:`zonegroup placement list`
 246   List zonegroup's placement targets.
 247
 248 :command:`zonegroup placement add`
 249   Add a placement target id to a zonegroup.
 250
 251 :command:`zonegroup placement modify`
 252   Modify a placement target of a specific zonegroup.
 253
 254 :command:`zonegroup placement rm`
 255   Remove a placement target from a zonegroup.
 256
 257 :command:`zonegroup placement default`
 258   Set a zonegroup's default placement target.
 259
 260 :command:`zone create`
 261   Create a new zone.
 262
 263 :command:`zone rm`
 264   Remove a zone.
 265
 266 :command:`zone get`
 267   Show zone cluster params.
 268
 269 :command:`zone set`
 270   Set zone cluster params (requires infile).
 271
 272 :command:`zone modify`
 273   Modify an existing zone.
 274
 275 :command:`zone list`
 276   List all zones set on this cluster.
 277
 278 :command:`metadata sync status`
 279   Get metadata sync status.
 280
 281 :command:`metadata sync init`
 282   Init metadata sync.
 283
 284 :command:`metadata sync run`
 285   Run metadata sync.
 286
 287 :command:`data sync status`
 288   Get data sync status of the specified source zone.
 289
 290 :command:`data sync init`
 291   Init data sync for the specified source zone.
 292
 293 :command:`data sync run`
 294   Run data sync for the specified source zone.
 295
 296 :command:`sync error list`
 297   list sync error.
 298
 299 :command:`sync error trim`
 300   trim sync error.
 301
 302 :command:`zone rename`
 303   Rename a zone.
 304
 305 :command:`zone placement list`
 306   List zone's placement targets.
 307
 308 :command:`zone placement add`
 309   Add a zone placement target.
 310
 311 :command:`zone placement modify`
 312   Modify a zone placement target.
 313
 314 :command:`zone placement rm`
 315   Remove a zone placement target.
 316
 317 :command:`pool add`
 318   Add an existing pool for data placement.
 319
 320 :command:`pool rm`
 321   Remove an existing pool from data placement set.
 322
 323 :command:`pools list`
 324   List placement active set.
 325
 326 :command:`policy`
 327   Display bucket/object policy.
 328
 329 :command:`log list`
 330   List log objects.
 331
 332 :command:`log show`
 333   Dump a log from specific object or (bucket + date + bucket-id).
 334   (NOTE: required to specify formatting of date to "YYYY-MM-DD-hh")
 335
 336 :command:`log rm`
 337   Remove log object.
 338
 339 :command:`usage show`
 340   Show the usage information (with optional user and date range).
 341
 342 :command:`usage trim`
 343   Trim usage information (with optional user and date range).
 344
 345 :command:`gc list`
 346   Dump expired garbage collection objects (specify --include-all to list all
 347   entries, including unexpired).
 348
 349 :command:`gc process`
 350   Manually process garbage.
 351
 352 :command:`lc list`
 353   List all bucket lifecycle progress.
 354
 355 :command:`lc process`
 356   Manually process lifecycle.
 357
 358 :command:`metadata get`
 359   Get metadata info.
 360
 361 :command:`metadata put`
 362   Put metadata info.
 363
 364 :command:`metadata rm`
 365   Remove metadata info.
 366
 367 :command:`metadata list`
 368   List metadata info.
 369
 370 :command:`mdlog list`
 371   List metadata log.
 372
 373 :command:`mdlog trim`
 374   Trim metadata log.
 375
 376 :command:`mdlog status`
 377   Read metadata log status.
 378
 379 :command:`bilog list`
 380   List bucket index log.
 381
 382 :command:`bilog trim`
 383   Trim bucket index log (use start-marker, end-marker).
 384
 385 :command:`datalog list`
 386   List data log.
 387
 388 :command:`datalog trim`
 389   Trim data log.
 390
 391 :command:`datalog status`
 392   Read data log status.
 393
 394 :command:`orphans find`
 395   Init and run search for leaked rados objects
 396
 397 :command:`orphans finish`
 398   Clean up search for leaked rados objects
 399
 400 :command:`orphans list-jobs`
 401   List the current job-ids for the orphans search.
 402
 403 :command:`role create`
 404   create a new AWS role for use with STS.
 405
 406 :command:`role rm`
 407   Remove a role.
 408
 409 :command:`role get`
 410   Get a role.
 411
 412 :command:`role list`
 413   List the roles with specified path prefix.
 414
 415 :command:`role modify`
 416   Modify the assume role policy of an existing role.
 417
 418 :command:`role-policy put`
 419   Add/update permission policy to role.
 420
 421 :command:`role-policy list`
 422   List the policies attached to a role.
 423
 424 :command:`role-policy get`
 425   Get the specified inline policy document embedded with the given role.
 426
 427 :command:`role-policy rm`
 428   Remove the policy attached to a role
 429
 430 :command:`reshard add`
 431   Schedule a resharding of a bucket
 432
 433 :command:`reshard list`
 434   List all bucket resharding or scheduled to be resharded
 435
 436 :command:`reshard process`
 437   Process of scheduled reshard jobs
 438
 439 :command:`reshard status`
 440   Resharding status of a bucket
 441
 442 :command:`reshard cancel`
 443   Cancel resharding a bucket
 444
 445 Options
 446 =======
 447
 448 .. option:: -c ceph.conf, --conf=ceph.conf
 449
 450    Use ``ceph.conf`` configuration file instead of the default
 451    ``/etc/ceph/ceph.conf`` to determine monitor addresses during
 452    startup.
 453
 454 .. option:: -m monaddress[:port]
 455
 456    Connect to specified monitor (instead of looking through ceph.conf).
 457
 458 .. option:: --tenant=<tenant>
 459
 460    Name of the tenant.
 461
 462 .. option:: --uid=uid
 463
 464    The radosgw user ID.
 465
 466 .. option:: --subuser=<name>
 467
 468         Name of the subuser.
 469
 470 .. option:: --access-key=<key>
 471
 472         S3 access key.
 473
 474 .. option:: --email=email
 475
 476    The e-mail address of the user.
 477
 478 .. option:: --secret/--secret-key=<key>
 479
 480    The secret key.
 481
 482 .. option:: --gen-access-key
 483
 484         Generate random access key (for S3).
 485
 486 .. option:: --gen-secret
 487
 488         Generate random secret key.
 489
 490 .. option:: --key-type=<type>
 491
 492         key type, options are: swift, s3.
 493
 494 .. option:: --temp-url-key[-2]=<key>
 495
 496         Temporary url key.
 497
 498 .. option:: --max-buckets
 499
 500         max number of buckets for a user (0 for no limit, negative value to disable bucket creation).
 501         Default is 1000.
 502
 503 .. option:: --access=<access>
 504
 505    Set the access permissions for the sub-user.
 506    Available access permissions are read, write, readwrite and full.
 507
 508 .. option:: --display-name=<name>
 509
 510    The display name of the user.
 511
 512 .. option:: --admin
 513
 514    Set the admin flag on the user.
 515
 516 .. option:: --system
 517
 518    Set the system flag on the user.
 519
 520 .. option:: --bucket=bucket
 521
 522    Specify the bucket name.
 523
 524 .. option:: --pool=<pool>
 525
 526    Specify the pool name.
 527    Also used with `orphans find` as data pool to scan for leaked rados objects.
 528
 529 .. option:: --object=object
 530
 531    Specify the object name.
 532
 533 .. option:: --date=yyyy-mm-dd
 534
 535    The date in the format yyyy-mm-dd.
 536
 537 .. option:: --start-date=yyyy-mm-dd
 538
 539    The start date in the format yyyy-mm-dd.
 540
 541 .. option:: --end-date=yyyy-mm-dd
 542
 543    The end date in the format yyyy-mm-dd.
 544
 545 .. option:: --bucket-id=<bucket-id>
 546
 547    Specify the bucket id.
 548
 549 .. option:: --shard-id=<shard-id>
 550
 551         Optional for mdlog list, data sync status. Required for ``mdlog trim``.
 552
 553 .. option:: --max-entries=<entries>
 554
 555         Optional for listing operations to specify the max entires
 556
 557 .. option:: --purge-data
 558
 559    When specified, user removal will also purge all the user data.
 560
 561 .. option:: --purge-keys
 562
 563         When specified, subuser removal will also purge all the subuser keys.
 564
 565 .. option:: --purge-objects
 566
 567    When specified, the bucket removal will also purge all objects in it.
 568
 569 .. option:: --metadata-key=<key>
 570
 571         Key to retrieve metadata from with ``metadata get``.
 572
 573 .. option:: --remote=<remote>
 574
 575    Zone or zonegroup id of remote gateway.
 576
 577 .. option:: --period=<id>
 578
 579    Period id.
 580
 581 .. option:: --url=<url>
 582
 583    url for pushing/pulling period or realm.
 584
 585 .. option:: --epoch=<number>
 586
 587    Period epoch.
 588
 589 .. option:: --commit
 590
 591    Commit the period during 'period update'.
 592
 593 .. option:: --staging
 594
 595    Get the staging period info.
 596
 597 .. option:: --master
 598
 599    Set as master.
 600
 601 .. option:: --master-zone=<id>
 602
 603    Master zone id.
 604
 605 .. option:: --rgw-realm=<name>
 606
 607    The realm name.
 608
 609 .. option:: --realm-id=<id>
 610
 611    The realm id.
 612
 613 .. option:: --realm-new-name=<name>
 614
 615    New name of realm.
 616
 617 .. option:: --rgw-zonegroup=<name>
 618
 619    The zonegroup name.
 620
 621 .. option:: --zonegroup-id=<id>
 622
 623    The zonegroup id.
 624
 625 .. option:: --zonegroup-new-name=<name>
 626
 627    The new name of the zonegroup.
 628
 629 .. option:: --rgw-zone=<zone>
 630
 631         Zone in which radosgw is running.
 632
 633 .. option:: --zone-id=<id>
 634
 635    The zone id.
 636
 637 .. option:: --zone-new-name=<name>
 638
 639    The new name of the zone.
 640
 641 .. option:: --source-zone
 642
 643    The source zone for data sync.
 644
 645 .. option:: --default
 646
 647    Set the entity (realm, zonegroup, zone) as default.
 648
 649 .. option:: --read-only
 650
 651    Set the zone as read-only when adding to the zonegroup.
 652
 653 .. option:: --placement-id
 654
 655    Placement id for the zonegroup placement commands.
 656
 657 .. option:: --tags=<list>
 658
 659    The list of tags for zonegroup placement add and modify commands.
 660
 661 .. option:: --tags-add=<list>
 662
 663    The list of tags to add for zonegroup placement modify command.
 664
 665 .. option:: --tags-rm=<list>
 666
 667    The list of tags to remove for zonegroup placement modify command.
 668
 669 .. option:: --endpoints=<list>
 670
 671    The zone endpoints.
 672
 673 .. option:: --index-pool=<pool>
 674
 675    The placement target index pool.
 676
 677 .. option:: --data-pool=<pool>
 678
 679    The placement target data pool.
 680
 681 .. option:: --data-extra-pool=<pool>
 682
 683    The placement target data extra (non-ec) pool.
 684
 685 .. option:: --placement-index-type=<type>
 686
 687    The placement target index type (normal, indexless, or #id).
 688
 689 .. option:: --tier-type=<type>
 690
 691    The zone tier type.
 692
 693 .. option:: --tier-config=<k>=<v>[,...]
 694
 695    Set zone tier config keys, values.
 696
 697 .. option:: --tier-config-rm=<k>[,...]
 698
 699    Unset zone tier config keys.
 700
 701 .. option:: --sync-from-all[=false]
 702
 703    Set/reset whether zone syncs from all zonegroup peers.
 704
 705 .. option:: --sync-from=[zone-name][,...]
 706
 707    Set the list of zones to sync from.
 708
 709 .. option:: --sync-from-rm=[zone-name][,...]
 710
 711    Remove the zones from list of zones to sync from.
 712
 713 .. option:: --fix
 714
 715         Besides checking bucket index, will also fix it.
 716
 717 .. option:: --check-objects
 718
 719         bucket check: Rebuilds bucket index according to actual objects state.
 720
 721 .. option:: --format=<format>
 722
 723         Specify output format for certain operations. Supported formats: xml, json.
 724
 725 .. option:: --sync-stats
 726
 727         Option for 'user stats' command. When specified, it will update user stats with
 728         the current stats reported by user's buckets indexes.
 729
 730 .. option:: --show-log-entries=<flag>
 731
 732         Enable/disable dump of log entries on log show.
 733
 734 .. option:: --show-log-sum=<flag>
 735
 736         Enable/disable dump of log summation on log show.
 737
 738 .. option:: --skip-zero-entries
 739
 740         Log show only dumps entries that don't have zero value in one of the numeric
 741         field.
 742
 743 .. option:: --infile
 744
 745         Specify a file to read in when setting data.
 746
 747 .. option:: --categories=<list>
 748
 749         Comma separated list of categories, used in usage show.
 750
 751 .. option:: --caps=<caps>
 752
 753         List of caps (e.g., "usage=read, write; user=read".
 754
 755 .. option:: --compression=<compression-algorithm>
 756
 757     Placement target compression algorithm (lz4|snappy|zlib|zstd)
 758
 759 .. option:: --yes-i-really-mean-it
 760
 761         Required for certain operations.
 762
 763 .. option:: --min-rewrite-size
 764
 765     Specify the min object size for bucket rewrite (default 4M).
 766
 767 .. option:: --max-rewrite-size
 768
 769     Specify the max object size for bucket rewrite (default ULLONG_MAX).
 770
 771 .. option:: --min-rewrite-stripe-size
 772
 773     Specify the min stripe size for object rewrite (default 0). If the value
 774     is set to 0, then the specified object will always be
 775     rewritten for restriping.
 776
 777 .. option:: --warnings-only
 778
 779    When specified with bucket limit check,
 780    list only buckets nearing or over the current max objects per shard value.
 781
 782 .. option:: --bypass-gc
 783
 784    When specified with bucket deletion,
 785    triggers object deletions by not involving GC.
 786
 787 .. option:: --inconsistent-index
 788
 789    When specified with bucket deletion and bypass-gc set to true,
 790    ignores bucket index consistency.
 791
 792 Quota Options
 793 =============
 794
 795 .. option:: --max-objects
 796
 797         Specify max objects (negative value to disable).
 798
 799 .. option:: --max-size
 800
 801         Specify max size (in B/K/M/G/T, negative value to disable).
 802
 803 .. option:: --quota-scope
 804
 805         The scope of quota (bucket, user).
 806
 807
 808 Orphans Search Options
 809 ======================
 810
 811 .. option:: --num-shards
 812
 813         Number of shards to use for keeping the temporary scan info
 814
 815 .. option:: --orphan-stale-secs
 816
 817         Number of seconds to wait before declaring an object to be an orphan.
 818         Default is 86400 (24 hours).
 819
 820 .. option:: --job-id
 821
 822         Set the job id (for orphans find)
 823
 824 .. option:: --max-concurrent-ios
 825
 826         Maximum concurrent ios for orphans find.
 827         Default is 32.
 828
 829
 830 Orphans list-jobs options
 831 =========================
 832
 833 .. option:: --extra-info
 834
 835    Provide extra info in the job list.
 836
 837
 838 Role Options
 839 ============
 840
 841 .. option:: --role-name
 842
 843    The name of the role to create.
 844
 845 .. option:: --path
 846
 847    The path to the role.
 848
 849 .. option:: --assume-role-policy-doc
 850
 851    The trust relationship policy document that grants an entity permission to
 852    assume the role.
 853
 854 .. option:: --policy-name
 855
 856    The name of the policy document.
 857
 858 .. option:: --policy-doc
 859
 860    The permission policy document.
 861
 862 .. option:: --path-prefix
 863
 864    The path prefix for filtering the roles.
 865
 866 Examples
 867 ========
 868
 869 Generate a new user::
 870
 871         $ radosgw-admin user create --display-name="johnny rotten" --uid=johnny
 872         { "user_id": "johnny",
 873           "rados_uid": 0,
 874           "display_name": "johnny rotten",
 875           "email": "",
 876           "suspended": 0,
 877           "subusers": [],
 878           "keys": [
 879                 { "user": "johnny",
 880                   "access_key": "TCICW53D9BQ2VGC46I44",
 881                   "secret_key": "tfm9aHMI8X76L3UdgE+ZQaJag1vJQmE6HDb5Lbrz"}],
 882           "swift_keys": []}
 883
 884 Remove a user::
 885
 886         $ radosgw-admin user rm --uid=johnny
 887
 888 Remove a user and all associated buckets with their contents::
 889
 890         $ radosgw-admin user rm --uid=johnny --purge-data
 891
 892 Remove a bucket::
 893
 894         $ radosgw-admin bucket rm --bucket=foo
 895
 896 Link bucket to specified user::
 897
 898         $ radosgw-admin bucket link --bucket=foo --bucket_id=<bucket id> --uid=johnny
 899
 900 Unlink bucket from specified user::
 901
 902         $ radosgw-admin bucket unlink --bucket=foo --uid=johnny
 903
 904 Show the logs of a bucket from April 1st, 2012::
 905
 906         $ radosgw-admin log show --bucket=foo --date=2012-04-01-01 --bucket-id=default.14193.1
 907
 908 Show usage information for user from March 1st to (but not including) April 1st, 2012::
 909
 910         $ radosgw-admin usage show --uid=johnny \
 911                         --start-date=2012-03-01 --end-date=2012-04-01
 912
 913 Show only summary of usage information for all users::
 914
 915         $ radosgw-admin usage show --show-log-entries=false
 916
 917 Trim usage information for user until March 1st, 2012::
 918
 919         $ radosgw-admin usage trim --uid=johnny --end-date=2012-04-01
 920
 921
 922 Availability
 923 ============
 924
 925 :program:`radosgw-admin` is part of Ceph, a massively scalable, open-source,
 926 distributed storage system.  Please refer to the Ceph documentation at
 927 http://ceph.com/docs for more information.
 928
 929
 930 See also
 931 ========
 932
 933 :doc:`ceph <ceph>`\(8)
 934 :doc:`radosgw <radosgw>`\(8)