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