Red Hat Training

A Red Hat training course is available for Red Hat Ceph Storage

Chapter 4. Object Gateway Configuration Reference

The following settings may be added to the Ceph configuration file (i.e., usually ceph.conf) under the [client.rgw.{instance-name}] section. The settings may contain default values. If you do not specify each setting in the Ceph configuration file, the default value will be set automatically.

Name	Description	Type	Default
`rgw_data`	Sets the location of the data files for Ceph Object Gateway.	String	`/var/lib/ceph/radosgw/$cluster-$id`
`rgw_enable_apis`	Enables the specified APIs.	String	`s3, swift, swift_auth, admin` All APIs.
`rgw_cache_enabled`	Whether the Ceph Object Gateway cache is enabled.	Boolean	`true`
`rgw_cache_lru_size`	The number of entries in the Ceph Object Gateway cache.	Integer	`10000`
`rgw_socket_path`	The socket path for the domain socket. `FastCgiExternalServer` uses this socket. If you do not specify a socket path, Ceph Object Gateway will not run as an external server. The path you specify here must be the same as the path specified in the `rgw.conf` file.	String	N/A
`rgw_host`	The host for the Ceph Object Gateway instance. Can be an IP address or a hostname.	String	`0.0.0.0`
`rgw_port`	Port the instance listens for requests. If not specified, Ceph Object Gateway runs external FastCGI.	String	None
`rgw_dns_name`	The DNS name of the served domain. See also the `hostnames` setting within regions.	String	None
`rgw_script_uri`	The alternative value for the `SCRIPT_URI` if not set in the request.	String	None
`rgw_request_uri`	The alternative value for the `REQUEST_URI` if not set in the request.	String	None
`rgw_print_continue`	Enable `100-continue` if it is operational.	Boolean	`true`
`rgw_remote_addr_param`	The remote address parameter. For example, the HTTP field containing the remote address, or the `X-Forwarded-For` address if a reverse proxy is operational.	String	`REMOTE_ADDR`
`rgw_op_thread_timeout`	The timeout in seconds for open threads.	Integer	600
`rgw_op_thread_suicide_timeout`	The time `timeout` in seconds before a Ceph Object Gateway process dies. Disabled if set to `0`.	Integer	`0`
`rgw_thread_pool_size`	The size of the thread pool.	Integer	100 threads.
`rgw_num_control_oids`	The number of notification objects used for cache synchronization between different `rgw` instances.	Integer	`8`
`rgw_init_timeout`	The number of seconds before Ceph Object Gateway gives up on initialization.	Integer	`30`
`rgw_mime_types_file`	The path and location of the MIME types. Used for Swift auto-detection of object types.	String	`/etc/mime.types`
`rgw_gc_max_objs`	The maximum number of objects that may be handled by garbage collection in one garbage collection processing cycle.	Integer	`32`
`rgw_gc_obj_min_wait`	The minimum wait time before the object may be removed and handled by garbage collection processing.	Integer	`2 * 3600`
`rgw_gc_processor_max_time`	The maximum time between the beginning of two consecutive garbage collection processing cycles.	Integer	`3600`
`rgw_gc_processor_period`	The cycle time for garbage collection processing.	Integer	`3600`
`rgw_s3 success_create_obj_status`	The alternate success status response for `create-obj`.	Integer	`0`
`rgw_resolve_cname`	Whether `rgw` should use DNS CNAME record of the request hostname field (if hostname is not equal to `rgw_dns name`).	Boolean	`false`
`rgw_object_stripe_size`	The size of an object stripe for Ceph Object Gateway objects.	Integer	`4 << 20`
`rgw_extended_http_attrs`	Add new set of attributes that could be set on an object. These extra attributes can be set through HTTP header fields when putting the objects. If set, these attributes will return as HTTP fields when doing GET/HEAD on the object.	String	None. For example: "content_foo, content_bar"
`rgw_exit_timeout_secs`	Number of seconds to wait for a process before exiting unconditionally.	Integer	`120`
`rgw_get_obj_window_size`	The window size in bytes for a single object request.	Integer	`16 << 20`
`rgw_get_obj_max_req_size`	The maximum request size of a single get operation sent to the Ceph Storage Cluster.	Integer	`4 << 20`
`rgw_relaxed s3_bucket_names`	Enables relaxed S3 bucket names rules for US region buckets.	Boolean	`false`
`rgw_list buckets_max_chunk`	The maximum number of buckets to retrieve in a single operation when listing user buckets.	Integer	`1000`
`rgw_num_zone_opstate_shards`	The maximum number of shards for keeping inter-region copy progress information.	Integer	`128`
`rgw_opstate_ratelimit_sec`	The minimum time between opstate updates on a single upload. `0` disables the ratelimit.	Integer	`30`
`rgw_curl_wait_timeout_ms`	The timeout in milliseconds for certain `curl` calls.	Integer	`1000`
`rgw_copy_obj_progress`	Enables output of object progress during long copy operations.	Boolean	`true`
`rgw_copy_obj_progress_every_bytes`	The minimum bytes between copy progress output.	Integer	`1024 * 1024`
`rgw_admin_entry`	The entry point for an admin request URL.	String	`admin`
`rgw_content_length_compat`	Enable compatability handling of FCGI requests with both CONTENT_LENGTH AND HTTP_CONTENT_LENGTH set.	Boolean	`false`

4.1. Regions

The Ceph Object Gateway supports federated deployments and a global namespace via the notion of regions. A region defines the geographic location of one or more Ceph Object Gateway instances within one or more zones.

Configuring regions differs from typical configuration procedures, because not all of the settings end up in a Ceph configuration file. You can list regions, get a region configuration and set a region configuration.

4.1.1. List Regions

A Ceph cluster contains a list of regions. To list the regions, execute:

sudo radosgw-admin regions list

The radosgw-admin returns a JSON formatted list of regions.

{ "default_info": { "default_region": "default"},
  "regions": [
        "default"]}

4.1.2. Get a Region Map

To list the details of each region, execute:

sudo radosgw-admin region-map get

Note

If you receive a failed to read region map error, run sudo radosgw-admin region-map update first.

4.1.3. Get a Region

To view the configuration of a region, execute:

radosgw-admin region get [--rgw-region=<region>]

The default region looks like this:

{"name": "default",
 "api_name": "",
 "is_master": "true",
 "endpoints": [],
 "hostnames": [],
 "master_zone": "",
 "zones": [
   {"name": "default",
    "endpoints": [],
    "log_meta": "false",
    "log_data": "false"}
  ],
 "placement_targets": [
   {"name": "default-placement",
    "tags": [] }],
 "default_placement": "default-placement"}

4.1.4. Set a Region

Defining a region consists of creating a JSON object, specifying at least the required settings:

name: The name of the region. Required.
api_name: The API name for the region. Optional.
is_master: Determines if the region is the master region. Required. note: You can only have one master region.
endpoints: A list of all the endpoints in the region. For example, you may use multiple domain names to refer to the same region. Remember to escape the forward slashes (\/). You may also specify a port (fqdn:port) for each endpoint. Optional.
hostnames: A list of all the hostnames in the region. For example, you may use multiple domain names to refer to the same region. Optional. The rgw dns name setting will automatically be included in this list. You should restart the radosgw daemon(s) after changing this setting.
master_zone: The master zone for the region. Optional. Uses the default zone if not specified. note: You can only have one master zone per region.
zones: A list of all zones within the region. Each zone has a name (required), a list of endpoints (optional), and whether or not the gateway will log metadata and data operations (false by default).
placement_targets: A list of placement targets (optional). Each placement target contains a name (required) for the placement target and a list of tags (optional) so that only users with the tag can use the placement target (i.e., the user’s placement_tags field in the user info).
default_placement: The default placement target for the object index and object data. Set to default-placement by default. You may also set a per-user default placement in the user info for each user.

To set a region, create a JSON object consisting of the required fields, save the object to a file (e.g., region.json); then, execute the following command:

sudo radosgw-admin region set --infile region.json

Where region.json is the JSON file you created.

Important

The default region is_master setting is true by default. If you create a new region and want to make it the master region, you must either set the default region is_master setting to false, or delete the default region.

Finally, update the map. :

sudo radosgw-admin region-map update

4.1.5. Set a Region Map

Setting a region map consists of creating a JSON object consisting of one or more regions, and setting the master_region for the cluster. Each region in the region map consists of a key/value pair, where the key setting is equivalent to the name setting for an individual region configuration, and the val is a JSON object consisting of an individual region configuration.

You may only have one region with is_master equal to true, and it must be specified as the master_region at the end of the region map. The following JSON object is an example of a default region map.

{
    "regions": [
        {
            "key": "default",
            "val": {
                "name": "default",
                "api_name": "",
                "is_master": "true",
                "endpoints": [],
                "hostnames": [],
                "master_zone": "",
                "zones": [
                    {
                        "name": "default",
                        "endpoints": [],
                        "log_meta": "false",
                        "log_data": "false",
                        "bucket_index_max_shards": 0
                    }
                ],
                "placement_targets": [
                    {
                        "name": "default-placement",
                        "tags": []
                    }
                ],
                "default_placement": "default-placement"
            }
        }
    ],
    "master_region": "default",
    "bucket_quota": {
        "enabled": false,
        "max_size_kb": -1,
        "max_objects": -1
    },
    "user_quota": {
        "enabled": false,
        "max_size_kb": -1,
        "max_objects": -1
    }
}

To set a region map, execute the following:

sudo radosgw-admin region-map set --infile regionmap.json

Where regionmap.json is the JSON file you created. Ensure that you have zones created for the ones specified in the region map. Finally, update the map.

sudo radosgw-admin regionmap update

4.2. Zones

Ceph Object Gateway supports the notion of zones. A zone defines a logical group consisting of one or more Ceph Object Gateway instances.

Configuring zones differs from typical configuration procedures, because not all of the settings end up in a Ceph configuration file. You can list zones, get a zone configuration and set a zone configuration.

4.2.1. List Zones

To list the zones in a cluster, execute:

sudo radosgw-admin zone list

4.2.2. Get a Zone

To get the configuration of a zone, execute:

sudo radosgw-admin zone get [--rgw-zone=<zone>]

The default zone looks like this:

{ "domain_root": ".rgw",
  "control_pool": ".rgw.control",
  "gc_pool": ".rgw.gc",
  "log_pool": ".log",
  "intent_log_pool": ".intent-log",
  "usage_log_pool": ".usage",
  "user_keys_pool": ".users",
  "user_email_pool": ".users.email",
  "user_swift_pool": ".users.swift",
  "user_uid_pool": ".users.uid",
  "system_key": { "access_key": "", "secret_key": ""},
  "placement_pools": [
      {  "key": "default-placement",
         "val": { "index_pool": ".rgw.buckets.index",
                  "data_pool": ".rgw.buckets"}
      }
    ]
  }

4.2.3. Set a Zone

Configuring a zone involves specifying a series of Ceph Object Gateway pools. For consistency, we recommend using a pool prefix that is the same as the zone name. See Pools_ for details of configuring pools.

To set a zone, create a JSON object consisting of the pools, save the object to a file (e.g., zone.json); then, execute the following command, replacing {zone-name} with the name of the zone:

sudo radosgw-admin zone set --rgw-zone={zone-name} --infile zone.json

Where zone.json is the JSON file you created.

4.3. Region and Zone Settings

When configuring a default region and zone, the pool name typically leaves off the region and zone names, but you may use any naming convention you prefer. The only requirement is to include a leading period to the region or zone name. For example:

.rgw.root
.users.swift

To change the defaults, include the following settings in your Ceph configuration file under each [client.radosgw.{instance-name}] instance.

Name	Description	Type	Default
`rgw_zone`	The name of the zone for the gateway instance.	String	None
`rgw_region`	The name of the region for the gateway instance.	String	None
`rgw_default_region_info_oid`	The OID for storing the default region. We do not recommend changing this setting.	String	`default.region`

4.4. Pools

Ceph zones map to a series of Ceph Storage Cluster pools.

Manually Created Pools vs. Generated Pools

If you provide write capabilities to the user key for the Ceph Object Gateway, the gateway has the ability to create pools automatically. This is convenient, but the Ceph Object Storage Cluster uses the default values for the number of placement groups, which doesn’t have to be ideal, or the values you specified in the Ceph configuration file. If you allow the Ceph Object Gateway to create pools automatically, ensure that you have reasonable defaults for the number of placement groups.

The default pools for the Ceph Object Gateway’s default zone include:

.rgw
.rgw.control
.rgw.gc
.log
.intent-log
.usage
.users
.users.email
.users.swift
.users.uid

You have significant discretion in determining how you want a zone to access pools. You can create pools on a per zone basis, or use the same pools for multiple zones. As a best practice, Red Hat recommends having a separate set of pools for the master zone and the secondary zones in each region. When creating pools for a specific zone, consider prepending the region name and zone name to the default pool names. For example:

.region1-zone1.domain.rgw
.region1-zone1.rgw.control
.region1-zone1.rgw.gc
.region1-zone1.log
.region1-zone1.intent-log
.region1-zone1.usage
.region1-zone1.users
.region1-zone1.users.email
.region1-zone1.users.swift
.region1-zone1.users.uid

Ceph Object Gateways store data for the bucket index (index_pool) and bucket data (data_pool) in placement pools. These might overlap; you can use the same pool for the index and the data. The index pool for default placement is .rgw.buckets.index and for the data pool for default placement is .rgw.buckets.

Name	Description	Type	Default
`rgw_region_root_pool`	The pool for storing all region-specific information.	String	`.rgw.root`
`rgw_zone_root_pool`	The pool for storing zone-specific information.	String	`.rgw.root`

4.5. Swift Settings

Name	Description	Type	Default
`rgw_enforce_swift_acls`	Enforces the Swift Access Control List (ACL) settings.	Boolean	`true`
`rgw_swift_token_expiration`	The time in seconds for expiring a Swift token.	Integer	`24 * 3600`
`rgw_swift_url`	The URL for the Ceph Object Gateway Swift API.	String	None
`rgw_swift_url_prefix`	The URL prefix for the Swift API (e.g., `http://fqdn.com/swift`).	`swift`	N/A
`rgw_swift_auth_url`	Default URL for verifying v1 auth tokens (if not using internal Swift auth).	String	None
`rgw_swift_auth_entry`	The entry point for a Swift auth URL.	String	`auth`

4.6. Logging Settings

Name	Description	Type	Default
`rgw_log_nonexistent_bucket`	Enables Ceph Object Gateway to log a request for a non-existent bucket.	Boolean	`false`
`rgw_log_object_name`	The logging format for an object name. See manpage date for details about format specifiers.	Date	`%Y-%m-%d-%H-%i-%n`
`rgw_log_object_name_utc`	Whether a logged object name includes a UTC time. If `false`, it uses the local time.	Boolean	`false`
`rgw_usage_max_shards`	The maximum number of shards for usage logging.	Integer	`32`
`rgw_usage_max_user_shards`	The maximum number of shards used for a single user’s usage logging.	Integer	`1`
`rgw_enable_ops_log`	Enable logging for each successful Ceph Object Gateway operation.	Boolean	`false`
`rgw_enable_usage_log`	Enable the usage log.	Boolean	`false`
`rgw_ops_log_rados`	Whether the operations log should be written to the Ceph Storage Cluster backend.	Boolean	`true`
`rgw_ops_log_socket_path`	The Unix domain socket for writing operations logs.	String	None
`rgw_ops_log_data-backlog`	The maximum data backlog data size for operations logs written to a Unix domain socket.	Integer	`5 << 20`
`rgw_usage_log_flush_threshold`	The number of dirty merged entries in the usage log before flushing synchronously.	Integer	1024
`rgw_usage_log_tick_interval`	Flush pending usage log data every `n` seconds.	Integer	`30`
`rgw_intent_log_object_name`	The logging format for the intent log object name. See manpage date for details about format specifiers.	Date	`%Y-%m-%d-%i-%n`
`rgw_intent_log_object_name_utc`	Whether the intent log object name includes a UTC time. If `false`, it uses the local time.	Boolean	`false`
`rgw_data_log_window`	The data log entries window in seconds.	Integer	`30`
`rgw_data_log_changes_size`	The number of in-memory entries to hold for the data changes log.	Integer	`1000`
`rgw_data_log_num_shards`	The number of shards (objects) on which to keep the data changes log.	Integer	`128`
`rgw_data_log_obj_prefix`	The object name prefix for the data log.	String	`data_log`
`rgw_replica_log_obj_prefix`	The object name prefix for the replica log.	String	`replica log`
`rgw_md_log_max_shards`	The maximum number of shards for the metadata log.	Integer	`64`

4.7. Keystone Settings

Name	Description	Type	Default
`rgw_keystone_url`	The URL for the Keystone server.	String	None
`rgw_keystone_admin_token`	The Keystone admin token (shared secret).	String	None
`rgw_keystone_accepted_roles`	The roles requires to serve requests.	String	`Member, admin`
`rgw_keystone_token_cache_size`	The maximum number of entries in each Keystone token cache.	Integer	`10000`
`rgw_keystone_revocation_interval`	The number of seconds between token revocation checks.	Integer	`15 * 60`

Select Your Language

Language:

Language:

Red Hat Training

Chapter 4. Object Gateway Configuration Reference

4.1. Regions

4.1.1. List Regions

4.1.2. Get a Region Map

4.1.3. Get a Region

4.1.4. Set a Region

4.1.5. Set a Region Map

4.2. Zones

4.2.1. List Zones

4.2.2. Get a Zone

4.2.3. Set a Zone

4.3. Region and Zone Settings

4.4. Pools

4.5. Swift Settings

4.6. Logging Settings

4.7. Keystone Settings

Quick Links

Help

Site Info

Related Sites

About

Red Hat legal and privacy links

Red Hat legal and privacy links

Language:

Language and Page Formatting Options

Language:

Red Hat Training

Chapter 4. Object Gateway Configuration Reference

4.1. Regions

4.1.1. List Regions

4.1.2. Get a Region Map

4.1.3. Get a Region

4.1.4. Set a Region

4.1.5. Set a Region Map

4.2. Zones

4.2.1. List Zones

4.2.2. Get a Zone

4.2.3. Set a Zone

4.3. Region and Zone Settings

4.4. Pools

4.5. Swift Settings

4.6. Logging Settings

4.7. Keystone Settings

Quick Links

Help

Site Info

Related Sites

Systems Status

About

Red Hat legal and privacy links

Red Hat legal and privacy links