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:`caps add`
  54   Add user capabilities.
  55
  56 :command:`caps rm`
  57   Remove user capabilities.
  58
  59 :command:`subuser create`
  60   Create a new subuser (primarily useful for clients using the Swift API).
  61
  62 :command:`subuser modify`
  63   Modify a subuser.
  64
  65 :command:`subuser rm`
  66   Remove a subuser.
  67
  68 :command:`key create`
  69   Create access key.
  70
  71 :command:`key rm`
  72   Remove access key.
  73
  74 :command:`bucket list`
  75   List all buckets.
  76
  77 :command:`bucket link`
  78   Link bucket to specified user.
  79
  80 :command:`bucket unlink`
  81   Unlink bucket from specified user.
  82
  83 :command:`bucket stats`
  84   Returns bucket statistics.
  85
  86 :command:`bucket rm`
  87   Remove a bucket.
  88
  89 :command:`bucket check`
  90   Check bucket index.
  91
  92 :command:`object rm`
  93   Remove an object.
  94
  95 :command:`object unlink`
  96   Unlink object from bucket index.
  97
  98 :command:`quota set`
  99   Set quota params.
 100
 101 :command:`quota enable`
 102   Enable quota.
 103
 104 :command:`quota disable`
 105   Disable quota.
 106
 107 :command:`region get`
 108   Show region info.
 109
 110 :command:`region list`
 111   List all regions set on this cluster.
 112
 113 :command:`region set`
 114   Set region info (requires infile).
 115
 116 :command:`region default`
 117   Set default region.
 118
 119 :command:`region-map get`
 120   Show region-map.
 121
 122 :command:`region-map set`
 123   Set region-map (requires infile).
 124
 125 :command:`zone get`
 126   Show zone cluster params.
 127
 128 :command:`zone set`
 129   Set zone cluster params (requires infile).
 130
 131 :command:`zone list`
 132   List all zones set on this cluster.
 133
 134 :command:`sync error list`
 135   list sync error.
 136
 137 :command:`sync error trim`
 138   trim sync error.
 139
 140 :command:`pool add`
 141   Add an existing pool for data placement.
 142
 143 :command:`pool rm`
 144   Remove an existing pool from data placement set.
 145
 146 :command:`pools list`
 147   List placement active set.
 148
 149 :command:`policy`
 150   Display bucket/object policy.
 151
 152 :command:`log list`
 153   List log objects.
 154
 155 :command:`log show`
 156   Dump a log from specific object or (bucket + date + bucket-id).
 157   (NOTE: required to specify formatting of date to "YYYY-MM-DD-hh")
 158
 159 :command:`log rm`
 160   Remove log object.
 161
 162 :command:`usage show`
 163   Show the usage information (with optional user and date range).
 164
 165 :command:`usage trim`
 166   Trim usage information (with optional user and date range).
 167
 168 :command:`gc list`
 169   Dump expired garbage collection objects (specify --include-all to list all
 170   entries, including unexpired).
 171
 172 :command:`gc process`
 173   Manually process garbage.
 174
 175 :command:`metadata get`
 176   Get metadata info.
 177
 178 :command:`metadata put`
 179   Put metadata info.
 180
 181 :command:`metadata rm`
 182   Remove metadata info.
 183
 184 :command:`metadata list`
 185   List metadata info.
 186
 187 :command:`mdlog list`
 188   List metadata log.
 189
 190 :command:`mdlog trim`
 191   Trim metadata log.
 192
 193 :command:`bilog list`
 194   List bucket index log.
 195
 196 :command:`bilog trim`
 197   Trim bucket index log (use start-marker, end-marker).
 198
 199 :command:`datalog list`
 200   List data log.
 201
 202 :command:`datalog trim`
 203   Trim data log.
 204
 205 :command:`opstate list`
 206   List stateful operations entries (use client_id, op_id, object).
 207
 208 :command:`opstate set`
 209   Set state on an entry (use client_id, op_id, object, state).
 210
 211 :command:`opstate renew`
 212   Renew state on an entry (use client_id, op_id, object).
 213
 214 :command:`opstate rm`
 215   Remove entry (use client_id, op_id, object).
 216
 217 :command:`replicalog get`
 218   Get replica metadata log entry.
 219
 220 :command:`replicalog delete`
 221   Delete replica metadata log entry.
 222
 223 :command:`orphans find`
 224   Init and run search for leaked rados objects
 225
 226 :command:`orphans finish`
 227   Clean up search for leaked rados objects
 228
 229
 230 Options
 231 =======
 232
 233 .. option:: -c ceph.conf, --conf=ceph.conf
 234
 235    Use ``ceph.conf`` configuration file instead of the default
 236    ``/etc/ceph/ceph.conf`` to determine monitor addresses during
 237    startup.
 238
 239 .. option:: -m monaddress[:port]
 240
 241    Connect to specified monitor (instead of looking through ceph.conf).
 242
 243 .. option:: --uid=uid
 244
 245    The radosgw user ID.
 246
 247 .. option:: --subuser=<name>
 248
 249         Name of the subuser.
 250
 251 .. option:: --email=email
 252
 253    The e-mail address of the user.
 254
 255 .. option:: --display-name=name
 256
 257    Configure the display name of the user.
 258
 259 .. option:: --access-key=<key>
 260
 261         S3 access key.
 262
 263 .. option:: --gen-access-key
 264
 265         Generate random access key (for S3).
 266
 267 .. option:: --secret=secret
 268
 269    The secret associated with a given key.
 270
 271 .. option:: --gen-secret
 272
 273         Generate random secret key.
 274
 275 .. option:: --key-type=<type>
 276
 277         key type, options are: swift, s3.
 278
 279 .. option:: --temp-url-key[-2]=<key>
 280
 281         Temporary url key.
 282
 283 .. option:: --system
 284
 285         Set the system flag on the user.
 286
 287 .. option:: --bucket=bucket
 288
 289    Specify the bucket name.
 290
 291 .. option:: --object=object
 292
 293    Specify the object name.
 294
 295 .. option:: --date=yyyy-mm-dd
 296
 297    The date needed for some commands.
 298
 299 .. option:: --start-date=yyyy-mm-dd
 300
 301    The start date needed for some commands.
 302
 303 .. option:: --end-date=yyyy-mm-dd
 304
 305    The end date needed for some commands.
 306
 307 .. option:: --shard-id=<shard-id>
 308
 309         Optional for mdlog list, data sync status. Required for ``mdlog trim``,
 310         ``replica mdlog get/delete``, ``replica datalog get/delete``.
 311
 312 .. option:: --max-entries=<entries>
 313
 314         Optional for listing operations to specify the max entires
 315
 316 .. option:: --auth-uid=auid
 317
 318    The librados auid.
 319
 320 .. option:: --purge-data
 321
 322    Remove user data before user removal.
 323
 324 .. option:: --purge-keys
 325
 326         When specified, subuser removal will also purge all the subuser keys.
 327
 328 .. option:: --purge-objects
 329
 330    Remove all objects before bucket removal.
 331
 332 .. option:: --metadata-key=<key>
 333
 334         Key to retrieve metadata from with ``metadata get``.
 335
 336 .. option:: --rgw-region=<region>
 337
 338         Region in which radosgw is running.
 339
 340 .. option:: --rgw-zone=<zone>
 341
 342         Zone in which radosgw is running.
 343
 344 .. option:: --fix
 345
 346         Besides checking bucket index, will also fix it.
 347
 348 .. option:: --check-objects
 349
 350         bucket check: Rebuilds bucket index according to actual objects state.
 351
 352 .. option:: --format=<format>
 353
 354         Specify output format for certain operations: xml, json.
 355
 356 .. option:: --sync-stats
 357
 358         Option to 'user stats', update user stats with current stats reported by
 359         user's buckets indexes.
 360
 361 .. option:: --show-log-entries=<flag>
 362
 363         Enable/disable dump of log entries on log show.
 364
 365 .. option:: --show-log-sum=<flag>
 366
 367         Enable/disable dump of log summation on log show.
 368
 369 .. option:: --skip-zero-entries
 370
 371         Log show only dumps entries that don't have zero value in one of the numeric
 372         field.
 373
 374 .. option:: --infile
 375
 376         Specify a file to read in when setting data.
 377
 378 .. option:: --state=<state string>
 379
 380         Specify a state for the opstate set command.
 381
 382 .. option:: --replica-log-type
 383
 384         Replica log type (metadata, data, bucket), required for replica log
 385         operations.
 386
 387 .. option:: --categories=<list>
 388
 389         Comma separated list of categories, used in usage show.
 390
 391 .. option:: --caps=<caps>
 392
 393         List of caps (e.g., "usage=read, write; user=read".
 394
 395 .. option:: --compression=<compression-algorithm>
 396
 397     Placement target compression algorithm (lz4|snappy|zlib|zstd)
 398
 399 .. option:: --yes-i-really-mean-it
 400
 401         Required for certain operations.
 402
 403
 404 Quota Options
 405 =============
 406
 407 .. option:: --max-objects
 408
 409         Specify max objects (negative value to disable).
 410
 411 .. option:: --max-size
 412
 413         Specify max size (in bytes, negative value to disable).
 414
 415 .. option:: --quota-scope
 416
 417         Scope of quota (bucket, user).
 418
 419
 420 Orphans Search Options
 421 ======================
 422
 423 .. option:: --pool
 424
 425         Data pool to scan for leaked rados objects
 426
 427 .. option:: --num-shards
 428
 429         Number of shards to use for keeping the temporary scan info
 430
 431 .. option:: --orphan-stale-secs
 432
 433         Number of seconds to wait before declaring an object to be an orphan.
 434         Default is 86400 (24 hours).
 435
 436 .. option:: --job-id
 437
 438         Set the job id (for orphans find)
 439
 440 .. option:: --max-concurrent-ios
 441
 442         Maximum concurrent ios for orphans find.
 443         Default is 32.
 444
 445
 446 Examples
 447 ========
 448
 449 Generate a new user::
 450
 451         $ radosgw-admin user create --display-name="johnny rotten" --uid=johnny
 452         { "user_id": "johnny",
 453           "rados_uid": 0,
 454           "display_name": "johnny rotten",
 455           "email": "",
 456           "suspended": 0,
 457           "subusers": [],
 458           "keys": [
 459                 { "user": "johnny",
 460                   "access_key": "TCICW53D9BQ2VGC46I44",
 461                   "secret_key": "tfm9aHMI8X76L3UdgE+ZQaJag1vJQmE6HDb5Lbrz"}],
 462           "swift_keys": []}
 463
 464 Remove a user::
 465
 466         $ radosgw-admin user rm --uid=johnny
 467
 468 Remove a user and all associated buckets with their contents::
 469
 470         $ radosgw-admin user rm --uid=johnny --purge-data
 471
 472 Remove a bucket::
 473
 474         $ radosgw-admin bucket rm --bucket=foo
 475
 476 Link bucket to specified user::
 477
 478         $ radosgw-admin bucket link --bucket=foo --bucket_id=<bucket id> --uid=johnny
 479
 480 Unlink bucket from specified user::
 481
 482         $ radosgw-admin bucket unlink --bucket=foo --uid=johnny
 483
 484 Show the logs of a bucket from April 1st, 2012::
 485
 486         $ radosgw-admin log show --bucket=foo --date=2012-04-01-01 --bucket-id=default.14193.1
 487
 488 Show usage information for user from March 1st to (but not including) April 1st, 2012::
 489
 490         $ radosgw-admin usage show --uid=johnny \
 491                         --start-date=2012-03-01 --end-date=2012-04-01
 492
 493 Show only summary of usage information for all users::
 494
 495         $ radosgw-admin usage show --show-log-entries=false
 496
 497 Trim usage information for user until March 1st, 2012::
 498
 499         $ radosgw-admin usage trim --uid=johnny --end-date=2012-04-01
 500
 501
 502 Availability
 503 ============
 504
 505 :program:`radosgw-admin` is part of Ceph, a massively scalable, open-source,
 506 distributed storage system.  Please refer to the Ceph documentation at
 507 http://ceph.com/docs for more information.
 508
 509
 510 See also
 511 ========
 512
 513 :doc:`ceph <ceph>`\(8)
 514 :doc:`radosgw <radosgw>`\(8)