src/ceph/doc/dev/radosgw/admin/adminops_nonimplemented.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 Object
  12 ==========
  13
  14 Get an existing object. NOTE: Does not require owner to be non-suspended.
  15
  16 Syntax
  17 ~~~~~~
  18
  19 ::
  20
  21         GET /{admin}/bucket?object&format=json HTTP/1.1
  22         Host {fqdn}
  23
  24 Request Parameters
  25 ~~~~~~~~~~~~~~~~~~
  26
  27 ``bucket``
  28
  29 :Description: The bucket containing the object to be retrieved.
  30 :Type: String
  31 :Example: ``foo_bucket``
  32 :Required: Yes
  33
  34 ``object``
  35
  36 :Description: The object to be retrieved.
  37 :Type: String
  38 :Example: ``foo.txt``
  39 :Required: Yes
  40
  41 Response Entities
  42 ~~~~~~~~~~~~~~~~~
  43
  44 If successful, returns the desired object.
  45
  46 ``object``
  47
  48 :Description: The desired object.
  49 :Type: Object
  50
  51 Special Error Responses
  52 ~~~~~~~~~~~~~~~~~~~~~~~
  53
  54 ``NoSuchObject``
  55
  56 :Description: Specified object does not exist.
  57 :Code: 404 Not Found
  58
  59 Head Object
  60 ===========
  61
  62 Verify the existence of an object. If the object exists,
  63 metadata headers for the object will be returned.
  64
  65 Syntax
  66 ~~~~~~
  67
  68 ::
  69
  70         HEAD /{admin}/bucket?object HTTP/1.1
  71         Host {fqdn}
  72
  73 Request Parameters
  74 ~~~~~~~~~~~~~~~~~~
  75
  76 ``bucket``
  77
  78 :Description: The bucket containing the object to be retrieved.
  79 :Type: String
  80 :Example: ``foo_bucket``
  81 :Required: Yes
  82
  83 ``object``
  84
  85 :Description: The object to be retrieved.
  86 :Type: String
  87 :Example: ``foo.txt``
  88 :Required: Yes
  89
  90 Response Entities
  91 ~~~~~~~~~~~~~~~~~
  92
  93 None.
  94
  95 Special Error Responses
  96 ~~~~~~~~~~~~~~~~~~~~~~~
  97
  98 ``NoSuchObject``
  99
 100 :Description: Specified object does not exist.
 101 :Code: 404 Not Found
 102
 103 Get Zone Info
 104 =============
 105
 106 Get cluster information.
 107
 108 Syntax
 109 ~~~~~~
 110
 111 ::
 112
 113         GET /{admin}/zone&format=json HTTP/1.1
 114         Host {fqdn}
 115
 116
 117 Response Entities
 118 ~~~~~~~~~~~~~~~~~
 119
 120 If successful, returns cluster pool configuration.
 121
 122 ``zone``
 123
 124 :Description: Contains current cluster pool configuration.
 125 :Type: Container
 126
 127 ``domain_root``
 128
 129 :Description: root of all buckets.
 130 :Type: String
 131 :Parent: ``cluster``
 132
 133 ``control_pool``
 134
 135 :Description:
 136 :Type: String
 137 :Parent: ``cluster``
 138
 139 ``gc_pool``
 140
 141 :Description: Garbage collection pool.
 142 :Type: String
 143 :Parent: ``cluster``
 144
 145 ``log_pool``
 146
 147 :Description: Log pool.
 148 :Type: String
 149 :Parent: ``cluster``
 150
 151 ``intent_log_pool``
 152
 153 :Description: Intent log pool.
 154 :Type: String
 155 :Parent: ``cluster``
 156
 157 ``usage_log_pool``
 158
 159 :Description: Usage log pool.
 160 :Type: String
 161 :Parent: ``cluster``
 162
 163 ``user_keys_pool``
 164
 165 :Description: User key pool.
 166 :Type: String
 167 :Parent: ``cluster``
 168
 169 ``user_email_pool``
 170
 171 :Description: User email pool.
 172 :Type: String
 173 :Parent: ``cluster``
 174
 175 ``user_swift_pool``
 176
 177 :Description: Pool of swift users.
 178 :Type: String
 179 :Parent: ``cluster``
 180
 181 Special Error Responses
 182 ~~~~~~~~~~~~~~~~~~~~~~~
 183
 184 None.
 185
 186 Example Response
 187 ~~~~~~~~~~~~~~~~
 188
 189 ::
 190
 191         HTTP/1.1 200
 192         Content-Type: application/json
 193
 194         {
 195           "domain_root": ".rgw",
 196           "control_pool": ".rgw.control",
 197           "gc_pool": ".rgw.gc",
 198           "log_pool": ".log",
 199           "intent_log_pool": ".intent-log",
 200           "usage_log_pool": ".usage",
 201           "user_keys_pool": ".users",
 202           "user_email_pool": ".users.email",
 203           "user_swift_pool": ".users.swift",
 204           "user_uid_pool ": ".users.uid"
 205         }
 206
 207
 208
 209 Add Placement Pool
 210 ==================
 211
 212 Make a pool available for data placement.
 213
 214 Syntax
 215 ~~~~~~
 216
 217 ::
 218
 219         PUT /{admin}/pool?format=json HTTP/1.1
 220         Host {fqdn}
 221
 222
 223 Request Parameters
 224 ~~~~~~~~~~~~~~~~~~
 225
 226 ``pool``
 227
 228 :Description: The pool to be made available for data placement.
 229 :Type: String
 230 :Example: ``foo_pool``
 231 :Required: Yes
 232
 233 ``create``
 234
 235 :Description: Creates the data pool if it does not exist.
 236 :Type: Boolean
 237 :Example: False [False]
 238 :Required: No
 239
 240 Response Entities
 241 ~~~~~~~~~~~~~~~~~
 242
 243 TBD.
 244
 245 Special Error Responses
 246 ~~~~~~~~~~~~~~~~~~~~~~~
 247
 248 TBD.
 249
 250 Remove Placement Pool
 251 =====================
 252
 253 Make a pool unavailable for data placement.
 254
 255 Syntax
 256 ~~~~~~
 257
 258 ::
 259
 260         DELETE /{admin}/pool?format=json HTTP/1.1
 261         Host {fqdn}
 262
 263
 264 Request Parameters
 265 ~~~~~~~~~~~~~~~~~~
 266
 267 ``pool``
 268
 269 :Description: The existing pool to be made available for data placement.
 270 :Type: String
 271 :Example: ``foo_pool``
 272 :Required: Yes
 273
 274 ``destroy``
 275
 276 :Description: Destroys the pool after removing it from the active set.
 277 :Type: Boolean
 278 :Example: False [False]
 279 :Required: No
 280
 281 Response Entities
 282 ~~~~~~~~~~~~~~~~~
 283
 284 TBD.
 285
 286 Special Error Responses
 287 ~~~~~~~~~~~~~~~~~~~~~~~
 288
 289 TBD.
 290
 291 List Available Data Placement Pools
 292 ===================================
 293
 294 List current pools available for data placement.
 295
 296 Syntax
 297 ~~~~~~
 298
 299 ::
 300
 301         GET /{admin}/pool?format=json HTTP/1.1
 302         Host {fqdn}
 303
 304
 305 Response Entities
 306 ~~~~~~~~~~~~~~~~~
 307
 308 If successful, returns a list of pools available for data placement.
 309
 310 ``pools``
 311
 312 :Description: Contains currently available pools for data placement.
 313 :Type: Container
 314
 315
 316
 317 List Expired Garbage Collection Items
 318 =====================================
 319
 320 List objects scheduled for garbage collection.
 321
 322 Syntax
 323 ~~~~~~
 324
 325 ::
 326
 327         GET /{admin}/garbage?format=json HTTP/1.1
 328         Host {fqdn}
 329
 330 Request Parameters
 331 ~~~~~~~~~~~~~~~~~~
 332
 333 None.
 334
 335 Response Entities
 336 ~~~~~~~~~~~~~~~~~
 337
 338 If expired garbage collection items exist, a list of such objects
 339 will be returned.
 340
 341 ``garbage``
 342
 343 :Description: Expired garbage collection items.
 344 :Type: Container
 345
 346 ``object``
 347
 348 :Description: A container garbage collection object information.
 349 :Type: Container
 350 :Parent: ``garbage``
 351
 352 ``name``
 353
 354 :Description: The name of the object.
 355 :Type: String
 356 :Parent: ``object``
 357
 358 ``expired``
 359
 360 :Description: The date at which the object expired.
 361 :Type: String
 362 :Parent: ``object``
 363
 364 Special Error Responses
 365 ~~~~~~~~~~~~~~~~~~~~~~~
 366
 367 TBD.
 368
 369 Manually Processes Garbage Collection Items
 370 ===========================================
 371
 372 List objects scheduled for garbage collection.
 373
 374 Syntax
 375 ~~~~~~
 376
 377 ::
 378
 379         DELETE /{admin}/garbage?format=json HTTP/1.1
 380         Host {fqdn}
 381
 382 Request Parameters
 383 ~~~~~~~~~~~~~~~~~~
 384
 385 None.
 386
 387 Response Entities
 388 ~~~~~~~~~~~~~~~~~
 389
 390 If expired garbage collection items exist, a list of removed objects
 391 will be returned.
 392
 393 ``garbage``
 394
 395 :Description: Expired garbage collection items.
 396 :Type: Container
 397
 398 ``object``
 399
 400 :Description: A container garbage collection object information.
 401 :Type: Container
 402 :Parent: ``garbage``
 403
 404 ``name``
 405
 406 :Description: The name of the object.
 407 :Type: String
 408 :Parent: ``object``
 409
 410 ``expired``
 411
 412 :Description: The date at which the object expired.
 413 :Type: String
 414 :Parent: ``object``
 415
 416 Special Error Responses
 417 ~~~~~~~~~~~~~~~~~~~~~~~
 418
 419 TBD.
 420
 421 Show Log Objects
 422 ================
 423
 424 Show log objects
 425
 426 Syntax
 427 ~~~~~~
 428
 429 ::
 430
 431         GET /{admin}/log?format=json HTTP/1.1
 432         Host {fqdn}
 433
 434 Request Parameters
 435 ~~~~~~~~~~~~~~~~~~
 436
 437 ``object``
 438
 439 :Description: The log object to return.
 440 :Type: String:
 441 :Example: ``2012-10-11-09-4165.2-foo_bucket``
 442 :Required: No
 443
 444 Response Entities
 445 ~~~~~~~~~~~~~~~~~
 446
 447 If no object is specified, returns the full list of log objects.
 448
 449 ``log-objects``
 450
 451 :Description: A list of log objects.
 452 :Type: Container
 453
 454 ``object``
 455
 456 :Description: The name of the log object.
 457 :Type: String
 458
 459 ``log``
 460
 461 :Description: The contents of the log object.
 462 :Type: Container
 463
 464 Special Error Responses
 465 ~~~~~~~~~~~~~~~~~~~~~~~
 466
 467 None.
 468
 469 Standard Error Responses
 470 ========================
 471
 472 ``AccessDenied``
 473
 474 :Description: Access denied.
 475 :Code: 403 Forbidden
 476
 477 ``InternalError``
 478
 479 :Description: Internal server error.
 480 :Code: 500 Internal Server Error
 481
 482 ``NoSuchUser``
 483
 484 :Description: User does not exist.
 485 :Code: 404 Not Found
 486
 487 ``NoSuchBucket``
 488
 489 :Description: Bucket does not exist.
 490 :Code: 404 Not Found
 491
 492 ``NoSuchKey``
 493
 494 :Description: No such access key.
 495 :Code: 404 Not Found