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