src/ceph/doc/radosgw/config-ref.rst

   1 ======================================
   2  Ceph Object Gateway Config Reference
   3 ======================================
   4
   5 The following settings may added to the Ceph configuration file (i.e., usually
   6 ``ceph.conf``) under the ``[client.radosgw.{instance-name}]`` section. The
   7 settings may contain default values. If you do not specify each setting in the
   8 Ceph configuration file, the default value will be set automatically.
   9
  10 Configuration variables set under the ``[client.radosgw.{instance-name}]``
  11 section will not apply to rgw or radosgw-admin commands without an instance-name
  12 specified in the command. Thus variables meant to be applied to all RGW
  13 instances or all radosgw-admin commands can be put into the ``[global]`` or the
  14 ``[client]`` section to avoid specifying instance-name.
  15
  16 ``rgw data``
  17
  18 :Description: Sets the location of the data files for Ceph Object Gateway.
  19 :Type: String
  20 :Default: ``/var/lib/ceph/radosgw/$cluster-$id``
  21
  22
  23 ``rgw enable apis``
  24
  25 :Description: Enables the specified APIs.
  26 :Type: String
  27 :Default: ``s3, swift, swift_auth, admin`` All APIs.
  28
  29
  30 ``rgw cache enabled``
  31
  32 :Description: Whether the Ceph Object Gateway cache is enabled.
  33 :Type: Boolean
  34 :Default: ``true``
  35
  36
  37 ``rgw cache lru size``
  38
  39 :Description: The number of entries in the Ceph Object Gateway cache.
  40 :Type: Integer
  41 :Default: ``10000``
  42
  43
  44 ``rgw socket path``
  45
  46 :Description: The socket path for the domain socket. ``FastCgiExternalServer``
  47               uses this socket. If you do not specify a socket path, Ceph
  48               Object Gateway will not run as an external server. The path you
  49               specify here must be the same as the path specified in the
  50               ``rgw.conf`` file.
  51
  52 :Type: String
  53 :Default: N/A
  54
  55 ``rgw fcgi socket backlog``
  56
  57 :Description: The socket backlog for fcgi.
  58 :Type: Integer
  59 :Default: ``1024``
  60
  61 ``rgw host``
  62
  63 :Description: The host for the Ceph Object Gateway instance. Can be an IP
  64               address or a hostname.
  65
  66 :Type: String
  67 :Default: ``0.0.0.0``
  68
  69
  70 ``rgw port``
  71
  72 :Description: Port the instance listens for requests. If not specified,
  73               Ceph Object Gateway runs external FastCGI.
  74
  75 :Type: String
  76 :Default: None
  77
  78
  79 ``rgw dns name``
  80
  81 :Description: The DNS name of the served domain. See also the ``hostnames`` setting within regions.
  82 :Type: String
  83 :Default: None
  84
  85
  86 ``rgw script uri``
  87
  88 :Description: The alternative value for the ``SCRIPT_URI`` if not set
  89               in the request.
  90
  91 :Type: String
  92 :Default: None
  93
  94
  95 ``rgw request uri``
  96
  97 :Description: The alternative value for the ``REQUEST_URI`` if not set
  98               in the request.
  99
 100 :Type: String
 101 :Default: None
 102
 103
 104 ``rgw print continue``
 105
 106 :Description: Enable ``100-continue`` if it is operational.
 107 :Type: Boolean
 108 :Default: ``true``
 109
 110
 111 ``rgw remote addr param``
 112
 113 :Description: The remote address parameter. For example, the HTTP field
 114               containing the remote address, or the ``X-Forwarded-For``
 115               address if a reverse proxy is operational.
 116
 117 :Type: String
 118 :Default: ``REMOTE_ADDR``
 119
 120
 121 ``rgw op thread timeout``
 122
 123 :Description: The timeout in seconds for open threads.
 124 :Type: Integer
 125 :Default: 600
 126
 127
 128 ``rgw op thread suicide timeout``
 129
 130 :Description: The time ``timeout`` in seconds before a Ceph Object Gateway
 131               process dies. Disabled if set to ``0``.
 132
 133 :Type: Integer
 134 :Default: ``0``
 135
 136
 137 ``rgw thread pool size``
 138
 139 :Description: The size of the thread pool.
 140 :Type: Integer
 141 :Default: 100 threads.
 142
 143
 144 ``rgw num rados handles``
 145
 146 :Description: The number of `RADOS cluster handles`_ for Ceph Object Gateway.
 147               Having a configurable number of RADOS handles is resulting in
 148               significant performance boost for all types of workloads. Each RGW
 149               worker thread would now get to pick a RADOS handle for its lifetime,
 150               from the available bunch.
 151
 152 :Type: Integer
 153 :Default: ``1``
 154
 155
 156 ``rgw num control oids``
 157
 158 :Description: The number of notification objects used for cache synchronization
 159               between different ``rgw`` instances.
 160
 161 :Type: Integer
 162 :Default: ``8``
 163
 164
 165 ``rgw init timeout``
 166
 167 :Description: The number of seconds before Ceph Object Gateway gives up on
 168               initialization.
 169
 170 :Type: Integer
 171 :Default: ``30``
 172
 173
 174 ``rgw mime types file``
 175
 176 :Description: The path and location of the MIME types. Used for Swift
 177               auto-detection of object types.
 178
 179 :Type: String
 180 :Default: ``/etc/mime.types``
 181
 182
 183 ``rgw gc max objs``
 184
 185 :Description: The maximum number of objects that may be handled by
 186               garbage collection in one garbage collection processing cycle.
 187
 188 :Type: Integer
 189 :Default: ``32``
 190
 191
 192 ``rgw gc obj min wait``
 193
 194 :Description: The minimum wait time before the object may be removed
 195               and handled by garbage collection processing.
 196
 197 :Type: Integer
 198 :Default: ``2 * 3600``
 199
 200
 201 ``rgw gc processor max time``
 202
 203 :Description: The maximum time between the beginning of two consecutive garbage
 204               collection processing cycles.
 205
 206 :Type: Integer
 207 :Default: ``3600``
 208
 209
 210 ``rgw gc processor period``
 211
 212 :Description: The cycle time for garbage collection processing.
 213 :Type: Integer
 214 :Default: ``3600``
 215
 216
 217 ``rgw s3 success create obj status``
 218
 219 :Description: The alternate success status response for ``create-obj``.
 220 :Type: Integer
 221 :Default: ``0``
 222
 223
 224 ``rgw resolve cname``
 225
 226 :Description: Whether ``rgw`` should use DNS CNAME record of the request
 227               hostname field (if hostname is not equal to ``rgw dns name``).
 228
 229 :Type: Boolean
 230 :Default: ``false``
 231
 232
 233 ``rgw obj stripe size``
 234
 235 :Description: The size of an object stripe for Ceph Object Gateway objects.
 236               See `Architecture`_ for details on striping.
 237
 238 :Type: Integer
 239 :Default: ``4 << 20``
 240
 241
 242 ``rgw extended http attrs``
 243
 244 :Description: Add new set of attributes that could be set on an entity
 245               (user, bucket or object). These extra attributes can be set
 246               through HTTP header fields when putting the entity or modifying
 247               it using POST method. If set, these attributes will return as
 248               HTTP  fields when doing GET/HEAD on the entity.
 249
 250 :Type: String
 251 :Default: None
 252 :Example: "content_foo, content_bar, x-foo-bar"
 253
 254
 255 ``rgw exit timeout secs``
 256
 257 :Description: Number of seconds to wait for a process before exiting
 258               unconditionally.
 259
 260 :Type: Integer
 261 :Default: ``120``
 262
 263
 264 ``rgw get obj window size``
 265
 266 :Description: The window size in bytes for a single object request.
 267 :Type: Integer
 268 :Default: ``16 << 20``
 269
 270
 271 ``rgw get obj max req size``
 272
 273 :Description: The maximum request size of a single get operation sent to the
 274               Ceph Storage Cluster.
 275
 276 :Type: Integer
 277 :Default: ``4 << 20``
 278
 279
 280 ``rgw relaxed s3 bucket names``
 281
 282 :Description: Enables relaxed S3 bucket names rules for US region buckets.
 283 :Type: Boolean
 284 :Default: ``false``
 285
 286
 287 ``rgw list buckets max chunk``
 288
 289 :Description: The maximum number of buckets to retrieve in a single operation
 290               when listing user buckets.
 291
 292 :Type: Integer
 293 :Default: ``1000``
 294
 295
 296 ``rgw override bucket index max shards``
 297
 298 :Description: Represents the number of shards for the bucket index object,
 299               a value of zero indicates there is no sharding. It is not
 300               recommended to set a value too large (e.g. thousand) as it
 301               increases the cost for bucket listing.
 302               This variable should be set in the client or global sections
 303               so that it is automatically applied to radosgw-admin commands.
 304
 305 :Type: Integer
 306 :Default: ``0``
 307
 308
 309 ``rgw curl wait timeout ms``
 310
 311 :Description: The timeout in milliseconds for certain ``curl`` calls.
 312 :Type: Integer
 313 :Default: ``1000``
 314
 315
 316 ``rgw copy obj progress``
 317
 318 :Description: Enables output of object progress during long copy operations.
 319 :Type: Boolean
 320 :Default: ``true``
 321
 322
 323 ``rgw copy obj progress every bytes``
 324
 325 :Description: The minimum bytes between copy progress output.
 326 :Type: Integer
 327 :Default: ``1024 * 1024``
 328
 329
 330 ``rgw admin entry``
 331
 332 :Description: The entry point for an admin request URL.
 333 :Type: String
 334 :Default: ``admin``
 335
 336
 337 ``rgw content length compat``
 338
 339 :Description: Enable compatability handling of FCGI requests with both CONTENT_LENGTH AND HTTP_CONTENT_LENGTH set.
 340 :Type: Boolean
 341 :Default: ``false``
 342
 343
 344 ``rgw bucket quota ttl``
 345
 346 :Description: The amount of time in seconds cached quota information is
 347               trusted.  After this timeout, the quota information will be
 348               re-fetched from the cluster.
 349 :Type: Integer
 350 :Default: ``600``
 351
 352
 353 ``rgw user quota bucket sync interval``
 354
 355 :Description: The amount of time in seconds bucket quota information is
 356               accumulated before syncing to the cluster.  During this time,
 357               other RGW instances will not see the changes in bucket quota
 358               stats from operations on this instance.
 359 :Type: Integer
 360 :Default: ``180``
 361
 362
 363 ``rgw user quota sync interval``
 364
 365 :Description: The amount of time in seconds user quota information is
 366               accumulated before syncing to the cluster.  During this time,
 367               other RGW instances will not see the changes in user quota stats
 368               from operations on this instance.
 369 :Type: Integer
 370 :Default: ``180``
 371
 372
 373 ``rgw bucket default quota max objects``
 374
 375 :Description: Default max number of objects per bucket. Set on new users,
 376               if no other quota is specified. Has no effect on existing users.
 377               This variable should be set in the client or global sections
 378               so that it is automatically applied to radosgw-admin commands.
 379 :Type: Integer
 380 :Default: ``-1``
 381
 382
 383 ``rgw bucket default quota max size``
 384
 385 :Description: Default max capacity per bucket, in bytes. Set on new users,
 386               if no other quota is specified. Has no effect on existing users.
 387 :Type: Integer
 388 :Default: ``-1``
 389
 390
 391 ``rgw user default quota max objects``
 392
 393 :Description: Default max number of objects for a user. This includes all
 394               objects in all buckets owned by the user. Set on new users,
 395               if no other quota is specified. Has no effect on existing users.
 396 :Type: Integer
 397 :Default: ``-1``
 398
 399
 400 ``rgw user default quota max size``
 401
 402 :Description: The value for user max size quota in bytes set on new users,
 403               if no other quota is specified.  Has no effect on existing users.
 404 :Type: Integer
 405 :Default: ``-1``
 406
 407
 408 ``rgw verify ssl``
 409
 410 :Description: Verify SSL certificates while making requests.
 411 :Type: Boolean
 412 :Default: ``true``
 413
 414
 415 Multisite Settings
 416 ==================
 417
 418 .. versionadded:: Jewel
 419
 420 You may include the following settings in your Ceph configuration
 421 file under each ``[client.radosgw.{instance-name}]`` instance.
 422
 423
 424 ``rgw zone``
 425
 426 :Description: The name of the zone for the gateway instance. If no zone is
 427               set, a cluster-wide default can be configured with the command
 428               ``radosgw-admin zone default``.
 429 :Type: String
 430 :Default: None
 431
 432
 433 ``rgw zonegroup``
 434
 435 :Description: The name of the zonegroup for the gateway instance. If no
 436               zonegroup is set, a cluster-wide default can be configured with
 437               the command ``radosgw-admin zonegroup default``.
 438 :Type: String
 439 :Default: None
 440
 441
 442 ``rgw realm``
 443
 444 :Description: The name of the realm for the gateway instance. If no realm is
 445               set, a cluster-wide default can be configured with the command
 446               ``radosgw-admin realm default``.
 447 :Type: String
 448 :Default: None
 449
 450
 451 ``rgw run sync thread``
 452
 453 :Description: If there are other zones in the realm to sync from, spawn threads
 454               to handle the sync of data and metadata.
 455 :Type: Boolean
 456 :Default: ``true``
 457
 458
 459 ``rgw data log window``
 460
 461 :Description: The data log entries window in seconds.
 462 :Type: Integer
 463 :Default: ``30``
 464
 465
 466 ``rgw data log changes size``
 467
 468 :Description: The number of in-memory entries to hold for the data changes log.
 469 :Type: Integer
 470 :Default: ``1000``
 471
 472
 473 ``rgw data log obj prefix``
 474
 475 :Description: The object name prefix for the data log.
 476 :Type: String
 477 :Default: ``data_log``
 478
 479
 480 ``rgw data log num shards``
 481
 482 :Description: The number of shards (objects) on which to keep the
 483               data changes log.
 484
 485 :Type: Integer
 486 :Default: ``128``
 487
 488
 489 ``rgw md log max shards``
 490
 491 :Description: The maximum number of shards for the metadata log.
 492 :Type: Integer
 493 :Default: ``64``
 494
 495 .. important:: The values of ``rgw data log num shards`` and
 496    ``rgw md log max shards`` should not be changed after sync has
 497    started.
 498
 499
 500 Swift Settings
 501 ==============
 502
 503 ``rgw enforce swift acls``
 504
 505 :Description: Enforces the Swift Access Control List (ACL) settings.
 506 :Type: Boolean
 507 :Default: ``true``
 508
 509
 510 ``rgw swift token expiration``
 511
 512 :Description: The time in seconds for expiring a Swift token.
 513 :Type: Integer
 514 :Default: ``24 * 3600``
 515
 516
 517 ``rgw swift url``
 518
 519 :Description: The URL for the Ceph Object Gateway Swift API.
 520 :Type: String
 521 :Default: None
 522
 523
 524 ``rgw swift url prefix``
 525
 526 :Description: The URL prefix for the Swift StorageURL that goes in front of
 527               the "/v1" part. This allows to run several Gateway instances
 528               on the same host. For compatibility, setting this configuration
 529               variable to empty causes the default "/swift" to be used.
 530               Use explicit prefix "/" to start StorageURL at the root.
 531               WARNING: setting this option to "/" will NOT work if S3 API is
 532               enabled. From the other side disabling S3 will make impossible
 533               to deploy RadosGW in the multi-site configuration!
 534 :Default: ``swift``
 535 :Example: "/swift-testing"
 536
 537
 538 ``rgw swift auth url``
 539
 540 :Description: Default URL for verifying v1 auth tokens (if not using internal
 541               Swift auth).
 542
 543 :Type: String
 544 :Default: None
 545
 546
 547 ``rgw swift auth entry``
 548
 549 :Description: The entry point for a Swift auth URL.
 550 :Type: String
 551 :Default: ``auth``
 552
 553
 554 ``rgw swift versioning enabled``
 555
 556 :Description: Enables the Object Versioning of OpenStack Object Storage API.
 557               This allows clients to put the ``X-Versions-Location`` attribute
 558               on containers that should be versioned. The attribute specifies
 559               the name of container storing archived versions. It must be owned
 560               by the same user that the versioned container due to access
 561               control verification - ACLs are NOT taken into consideration.
 562               Those containers cannot be versioned by the S3 object versioning
 563               mechanism.
 564 :Type: Boolean
 565 :Default: ``false``
 566
 567
 568
 569 Logging Settings
 570 ================
 571
 572
 573 ``rgw log nonexistent bucket``
 574
 575 :Description: Enables Ceph Object Gateway to log a request for a non-existent
 576               bucket.
 577
 578 :Type: Boolean
 579 :Default: ``false``
 580
 581
 582 ``rgw log object name``
 583
 584 :Description: The logging format for an object name. See manpage
 585               :manpage:`date` for details about format specifiers.
 586
 587 :Type: Date
 588 :Default: ``%Y-%m-%d-%H-%i-%n``
 589
 590
 591 ``rgw log object name utc``
 592
 593 :Description: Whether a logged object name includes a UTC time.
 594               If ``false``, it uses the local time.
 595
 596 :Type: Boolean
 597 :Default: ``false``
 598
 599
 600 ``rgw usage max shards``
 601
 602 :Description: The maximum number of shards for usage logging.
 603 :Type: Integer
 604 :Default: ``32``
 605
 606
 607 ``rgw usage max user shards``
 608
 609 :Description: The maximum number of shards used for a single user's
 610               usage logging.
 611
 612 :Type: Integer
 613 :Default: ``1``
 614
 615
 616 ``rgw enable ops log``
 617
 618 :Description: Enable logging for each successful Ceph Object Gateway operation.
 619 :Type: Boolean
 620 :Default: ``false``
 621
 622
 623 ``rgw enable usage log``
 624
 625 :Description: Enable the usage log.
 626 :Type: Boolean
 627 :Default: ``false``
 628
 629
 630 ``rgw ops log rados``
 631
 632 :Description: Whether the operations log should be written to the
 633               Ceph Storage Cluster backend.
 634
 635 :Type: Boolean
 636 :Default: ``true``
 637
 638
 639 ``rgw ops log socket path``
 640
 641 :Description: The Unix domain socket for writing operations logs.
 642 :Type: String
 643 :Default: None
 644
 645
 646 ``rgw ops log data backlog``
 647
 648 :Description: The maximum data backlog data size for operations logs written
 649               to a Unix domain socket.
 650
 651 :Type: Integer
 652 :Default: ``5 << 20``
 653
 654
 655 ``rgw usage log flush threshold``
 656
 657 :Description: The number of dirty merged entries in the usage log before
 658               flushing synchronously.
 659
 660 :Type: Integer
 661 :Default: 1024
 662
 663
 664 ``rgw usage log tick interval``
 665
 666 :Description: Flush pending usage log data every ``n`` seconds.
 667 :Type: Integer
 668 :Default: ``30``
 669
 670
 671 ``rgw log http headers``
 672
 673 :Description: Comma-delimited list of HTTP headers to include with ops
 674               log entries.  Header names are case insensitive, and use
 675               the full header name with words separated by underscores.
 676
 677 :Type: String
 678 :Default: None
 679 :Example: "http_x_forwarded_for, http_x_special_k"
 680
 681
 682 ``rgw intent log object name``
 683
 684 :Description: The logging format for the intent log object name. See manpage
 685               :manpage:`date` for details about format specifiers.
 686
 687 :Type: Date
 688 :Default: ``%Y-%m-%d-%i-%n``
 689
 690
 691 ``rgw intent log object name utc``
 692
 693 :Description: Whether the intent log object name includes a UTC time.
 694               If ``false``, it uses the local time.
 695
 696 :Type: Boolean
 697 :Default: ``false``
 698
 699
 700
 701 Keystone Settings
 702 =================
 703
 704
 705 ``rgw keystone url``
 706
 707 :Description: The URL for the Keystone server.
 708 :Type: String
 709 :Default: None
 710
 711
 712 ``rgw keystone api version``
 713
 714 :Description: The version (2 or 3) of OpenStack Identity API that should be
 715               used for communication with the Keystone server.
 716 :Type: Integer
 717 :Default: ``2``
 718
 719
 720 ``rgw keystone admin domain``
 721
 722 :Description: The name of OpenStack domain with admin privilege when using
 723               OpenStack Identity API v3.
 724 :Type: String
 725 :Default: None
 726
 727
 728 ``rgw keystone admin project``
 729
 730 :Description: The name of OpenStack project with admin privilege when using
 731               OpenStack Identity API v3. If left unspecified, value of
 732               ``rgw keystone admin tenant`` will be used instead.
 733 :Type: String
 734 :Default: None
 735
 736
 737 ``rgw keystone admin token``
 738
 739 :Description: The Keystone admin token (shared secret). In Ceph RadosGW
 740               authentication with the admin token has priority over
 741               authentication with the admin credentials
 742               (``rgw keystone admin user``, ``rgw keystone admin password``,
 743               ``rgw keystone admin tenant``, ``rgw keystone admin project``,
 744               ``rgw keystone admin domain``). Admin token feature is considered
 745               as deprecated.
 746 :Type: String
 747 :Default: None
 748
 749
 750 ``rgw keystone admin tenant``
 751
 752 :Description: The name of OpenStack tenant with admin privilege (Service Tenant) when
 753               using OpenStack Identity API v2
 754 :Type: String
 755 :Default: None
 756
 757
 758 ``rgw keystone admin user``
 759
 760 :Description: The name of OpenStack user with admin privilege for Keystone
 761               authentication (Service User) when OpenStack Identity API v2
 762 :Type: String
 763 :Default: None
 764
 765
 766 ``rgw keystone admin password``
 767
 768 :Description: The password for OpenStack admin user when using OpenStack
 769               Identity API v2
 770 :Type: String
 771 :Default: None
 772
 773
 774 ``rgw keystone accepted roles``
 775
 776 :Description: The roles requires to serve requests.
 777 :Type: String
 778 :Default: ``Member, admin``
 779
 780
 781 ``rgw keystone token cache size``
 782
 783 :Description: The maximum number of entries in each Keystone token cache.
 784 :Type: Integer
 785 :Default: ``10000``
 786
 787
 788 ``rgw keystone revocation interval``
 789
 790 :Description: The number of seconds between token revocation checks.
 791 :Type: Integer
 792 :Default: ``15 * 60``
 793
 794
 795 ``rgw keystone verify ssl``
 796
 797 :Description: Verify SSL certificates while making token requests to keystone.
 798 :Type: Boolean
 799 :Default: ``true``
 800
 801 Barbican Settings
 802 =================
 803
 804 ``rgw barbican url``
 805
 806 :Description: The URL for the Barbican server.
 807 :Type: String
 808 :Default: None
 809
 810 ``rgw keystone barbican user``
 811
 812 :Description: The name of the OpenStack user with access to the `Barbican`_
 813               secrets used for `Encryption`_.
 814 :Type: String
 815 :Default: None
 816
 817 ``rgw keystone barbican password``
 818
 819 :Description: The password associated with the `Barbican`_ user.
 820 :Type: String
 821 :Default: None
 822
 823 ``rgw keystone barbican tenant``
 824
 825 :Description: The name of the OpenStack tenant associated with the `Barbican`_
 826               user when using OpenStack Identity API v2.
 827 :Type: String
 828 :Default: None
 829
 830 ``rgw keystone barbican project``
 831
 832 :Description: The name of the OpenStack project associated with the `Barbican`_
 833               user when using OpenStack Identity API v3.
 834 :Type: String
 835 :Default: None
 836
 837 ``rgw keystone barbican domain``
 838
 839 :Description: The name of the OpenStack domain associated with the `Barbican`_
 840               user when using OpenStack Identity API v3.
 841 :Type: String
 842 :Default: None
 843
 844
 845 .. _Architecture: ../../architecture#data-striping
 846 .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/
 847 .. _Cluster Pools: ../../rados/operations/pools
 848 .. _Rados cluster handles: ../../rados/api/librados-intro/#step-2-configuring-a-cluster-handle
 849 .. _Barbican: ../barbican
 850 .. _Encryption: ../encryption