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 |
---|---|---|---|
| Sets the location of the data files for Ceph Object Gateway. | String |
|
| Enables the specified APIs. | String |
|
| Whether the Ceph Object Gateway cache is enabled. | Boolean |
|
| The number of entries in the Ceph Object Gateway cache. | Integer |
|
|
The socket path for the domain socket. | String | N/A |
| The host for the Ceph Object Gateway instance. Can be an IP address or a hostname. | String |
|
| Port the instance listens for requests. If not specified, Ceph Object Gateway runs external FastCGI. | String | None |
|
The DNS name of the served domain. See also the | String | None |
|
The alternative value for the | String | None |
|
The alternative value for the | String | None |
|
Enable | Boolean |
|
|
The remote address parameter. For example, the HTTP field containing the remote address, or the | String |
|
| The timeout in seconds for open threads. | Integer | 600 |
|
The time | Integer |
|
| The size of the thread pool. | Integer | 100 threads. |
|
The number of notification objects used for cache synchronization between different | Integer |
|
| The number of seconds before Ceph Object Gateway gives up on initialization. | Integer |
|
| The path and location of the MIME types. Used for Swift auto-detection of object types. | String |
|
| The maximum number of objects that may be handled by garbage collection in one garbage collection processing cycle. | Integer |
|
| The minimum wait time before the object may be removed and handled by garbage collection processing. | Integer |
|
| The maximum time between the beginning of two consecutive garbage collection processing cycles. | Integer |
|
| The cycle time for garbage collection processing. | Integer |
|
|
The alternate success status response for | Integer |
|
|
Whether | Boolean |
|
| The size of an object stripe for Ceph Object Gateway objects. | Integer |
|
| 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" |
| Number of seconds to wait for a process before exiting unconditionally. | Integer |
|
| The window size in bytes for a single object request. | Integer |
|
| The maximum request size of a single get operation sent to the Ceph Storage Cluster. | Integer |
|
| Enables relaxed S3 bucket names rules for US region buckets. | Boolean |
|
| The maximum number of buckets to retrieve in a single operation when listing user buckets. | Integer |
|
| The maximum number of shards for keeping inter-region copy progress information. | Integer |
|
|
The minimum time between opstate updates on a single upload. | Integer |
|
|
The timeout in milliseconds for certain | Integer |
|
| Enables output of object progress during long copy operations. | Boolean |
|
| The minimum bytes between copy progress output. | Integer |
|
| The entry point for an admin request URL. | String |
|
| Enable compatability handling of FCGI requests with both CONTENT_LENGTH AND HTTP_CONTENT_LENGTH set. | Boolean |
|
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
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. Thergw dns name
setting will automatically be included in this list. You should restart theradosgw
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’splacement_tags
field in the user info). -
default_placement
: The default placement target for the object index and object data. Set todefault-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.
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 |
---|---|---|---|
| The name of the zone for the gateway instance. | String | None |
| The name of the region for the gateway instance. | String | None |
| The OID for storing the default region. We do not recommend changing this setting. | String |
|
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 |
---|---|---|---|
| The pool for storing all region-specific information. | String |
|
| The pool for storing zone-specific information. | String |
|
4.5. Swift Settings
Name | Description | Type | Default |
---|---|---|---|
| Enforces the Swift Access Control List (ACL) settings. | Boolean |
|
| The time in seconds for expiring a Swift token. | Integer |
|
| The URL for the Ceph Object Gateway Swift API. | String | None |
|
The URL prefix for the Swift API (e.g., |
| N/A |
| Default URL for verifying v1 auth tokens (if not using internal Swift auth). | String | None |
| The entry point for a Swift auth URL. | String |
|
4.6. Logging Settings
Name | Description | Type | Default |
---|---|---|---|
| Enables Ceph Object Gateway to log a request for a non-existent bucket. | Boolean |
|
| The logging format for an object name. See manpage date for details about format specifiers. | Date |
|
|
Whether a logged object name includes a UTC time. If | Boolean |
|
| The maximum number of shards for usage logging. | Integer |
|
| The maximum number of shards used for a single user’s usage logging. | Integer |
|
| Enable logging for each successful Ceph Object Gateway operation. | Boolean |
|
| Enable the usage log. | Boolean |
|
| Whether the operations log should be written to the Ceph Storage Cluster backend. | Boolean |
|
| The Unix domain socket for writing operations logs. | String | None |
| The maximum data backlog data size for operations logs written to a Unix domain socket. | Integer |
|
| The number of dirty merged entries in the usage log before flushing synchronously. | Integer | 1024 |
|
Flush pending usage log data every | Integer |
|
| The logging format for the intent log object name. See manpage date for details about format specifiers. | Date |
|
|
Whether the intent log object name includes a UTC time. If | Boolean |
|
| The data log entries window in seconds. | Integer |
|
| The number of in-memory entries to hold for the data changes log. | Integer |
|
| The number of shards (objects) on which to keep the data changes log. | Integer |
|
| The object name prefix for the data log. | String |
|
| The object name prefix for the replica log. | String |
|
| The maximum number of shards for the metadata log. | Integer |
|
4.7. Keystone Settings
Name | Description | Type | Default |
---|---|---|---|
| The URL for the Keystone server. | String | None |
| The Keystone admin token (shared secret). | String | None |
| The roles requires to serve requests. | String |
|
| The maximum number of entries in each Keystone token cache. | Integer |
|
| The number of seconds between token revocation checks. | Integer |
|