]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
11 | ``rgw data`` | |
12 | ||
13 | :Description: Sets the location of the data files for Ceph Object Gateway. | |
14 | :Type: String | |
15 | :Default: ``/var/lib/ceph/radosgw/$cluster-$id`` | |
16 | ||
17 | ||
18 | ``rgw enable apis`` | |
19 | ||
20 | :Description: Enables the specified APIs. | |
21 | :Type: String | |
22 | :Default: ``s3, swift, swift_auth, admin`` All APIs. | |
23 | ||
24 | ||
25 | ``rgw cache enabled`` | |
26 | ||
27 | :Description: Whether the Ceph Object Gateway cache is enabled. | |
28 | :Type: Boolean | |
29 | :Default: ``true`` | |
30 | ||
31 | ||
32 | ``rgw cache lru size`` | |
33 | ||
34 | :Description: The number of entries in the Ceph Object Gateway cache. | |
35 | :Type: Integer | |
36 | :Default: ``10000`` | |
37 | ||
38 | ||
39 | ``rgw socket path`` | |
40 | ||
41 | :Description: The socket path for the domain socket. ``FastCgiExternalServer`` | |
42 | uses this socket. If you do not specify a socket path, Ceph | |
43 | Object Gateway will not run as an external server. The path you | |
44 | specify here must be the same as the path specified in the | |
45 | ``rgw.conf`` file. | |
46 | ||
47 | :Type: String | |
48 | :Default: N/A | |
49 | ||
50 | ``rgw fcgi socket backlog`` | |
51 | ||
52 | :Description: The socket backlog for fcgi. | |
53 | :Type: Integer | |
54 | :Default: ``1024`` | |
55 | ||
56 | ``rgw host`` | |
57 | ||
58 | :Description: The host for the Ceph Object Gateway instance. Can be an IP | |
59 | address or a hostname. | |
60 | ||
61 | :Type: String | |
62 | :Default: ``0.0.0.0`` | |
63 | ||
64 | ||
65 | ``rgw port`` | |
66 | ||
67 | :Description: Port the instance listens for requests. If not specified, | |
68 | Ceph Object Gateway runs external FastCGI. | |
69 | ||
70 | :Type: String | |
71 | :Default: None | |
72 | ||
73 | ||
74 | ``rgw dns name`` | |
75 | ||
76 | :Description: The DNS name of the served domain. See also the ``hostnames`` setting within regions. | |
77 | :Type: String | |
78 | :Default: None | |
79 | ||
80 | ||
81 | ``rgw script uri`` | |
82 | ||
83 | :Description: The alternative value for the ``SCRIPT_URI`` if not set | |
84 | in the request. | |
85 | ||
86 | :Type: String | |
87 | :Default: None | |
88 | ||
89 | ||
90 | ``rgw request uri`` | |
91 | ||
92 | :Description: The alternative value for the ``REQUEST_URI`` if not set | |
93 | in the request. | |
94 | ||
95 | :Type: String | |
96 | :Default: None | |
97 | ||
98 | ||
99 | ``rgw print continue`` | |
100 | ||
101 | :Description: Enable ``100-continue`` if it is operational. | |
102 | :Type: Boolean | |
103 | :Default: ``true`` | |
104 | ||
105 | ||
106 | ``rgw remote addr param`` | |
107 | ||
108 | :Description: The remote address parameter. For example, the HTTP field | |
109 | containing the remote address, or the ``X-Forwarded-For`` | |
110 | address if a reverse proxy is operational. | |
111 | ||
112 | :Type: String | |
113 | :Default: ``REMOTE_ADDR`` | |
114 | ||
115 | ||
116 | ``rgw op thread timeout`` | |
117 | ||
118 | :Description: The timeout in seconds for open threads. | |
119 | :Type: Integer | |
120 | :Default: 600 | |
121 | ||
122 | ||
123 | ``rgw op thread suicide timeout`` | |
124 | ||
125 | :Description: The time ``timeout`` in seconds before a Ceph Object Gateway | |
126 | process dies. Disabled if set to ``0``. | |
127 | ||
128 | :Type: Integer | |
129 | :Default: ``0`` | |
130 | ||
131 | ||
132 | ``rgw thread pool size`` | |
133 | ||
134 | :Description: The size of the thread pool. | |
135 | :Type: Integer | |
136 | :Default: 100 threads. | |
137 | ||
138 | ||
139 | ``rgw num rados handles`` | |
140 | ||
141 | :Description: The number of `RADOS cluster handles`_ for Ceph Object Gateway. | |
142 | Having a configurable number of RADOS handles is resulting in | |
143 | significant performance boost for all types of workloads. Each RGW | |
144 | worker thread would now get to pick a RADOS handle for its lifetime, | |
145 | from the available bunch. | |
146 | ||
147 | :Type: Integer | |
148 | :Default: ``1`` | |
149 | ||
150 | ||
151 | ``rgw num control oids`` | |
152 | ||
153 | :Description: The number of notification objects used for cache synchronization | |
154 | between different ``rgw`` instances. | |
155 | ||
156 | :Type: Integer | |
157 | :Default: ``8`` | |
158 | ||
159 | ||
160 | ``rgw init timeout`` | |
161 | ||
162 | :Description: The number of seconds before Ceph Object Gateway gives up on | |
163 | initialization. | |
164 | ||
165 | :Type: Integer | |
166 | :Default: ``30`` | |
167 | ||
168 | ||
169 | ``rgw mime types file`` | |
170 | ||
171 | :Description: The path and location of the MIME types. Used for Swift | |
172 | auto-detection of object types. | |
173 | ||
174 | :Type: String | |
175 | :Default: ``/etc/mime.types`` | |
176 | ||
177 | ||
178 | ``rgw gc max objs`` | |
179 | ||
180 | :Description: The maximum number of objects that may be handled by | |
181 | garbage collection in one garbage collection processing cycle. | |
182 | ||
183 | :Type: Integer | |
184 | :Default: ``32`` | |
185 | ||
186 | ||
187 | ``rgw gc obj min wait`` | |
188 | ||
189 | :Description: The minimum wait time before the object may be removed | |
190 | and handled by garbage collection processing. | |
191 | ||
192 | :Type: Integer | |
193 | :Default: ``2 * 3600`` | |
194 | ||
195 | ||
196 | ``rgw gc processor max time`` | |
197 | ||
198 | :Description: The maximum time between the beginning of two consecutive garbage | |
199 | collection processing cycles. | |
200 | ||
201 | :Type: Integer | |
202 | :Default: ``3600`` | |
203 | ||
204 | ||
205 | ``rgw gc processor period`` | |
206 | ||
207 | :Description: The cycle time for garbage collection processing. | |
208 | :Type: Integer | |
209 | :Default: ``3600`` | |
210 | ||
211 | ||
212 | ``rgw s3 success create obj status`` | |
213 | ||
214 | :Description: The alternate success status response for ``create-obj``. | |
215 | :Type: Integer | |
216 | :Default: ``0`` | |
217 | ||
218 | ||
219 | ``rgw resolve cname`` | |
220 | ||
221 | :Description: Whether ``rgw`` should use DNS CNAME record of the request | |
222 | hostname field (if hostname is not equal to ``rgw dns name``). | |
223 | ||
224 | :Type: Boolean | |
225 | :Default: ``false`` | |
226 | ||
227 | ||
228 | ``rgw obj stripe size`` | |
229 | ||
230 | :Description: The size of an object stripe for Ceph Object Gateway objects. | |
231 | See `Architecture`_ for details on striping. | |
232 | ||
233 | :Type: Integer | |
234 | :Default: ``4 << 20`` | |
235 | ||
236 | ||
237 | ``rgw extended http attrs`` | |
238 | ||
239 | :Description: Add new set of attributes that could be set on an entity | |
240 | (user, bucket or object). These extra attributes can be set | |
241 | through HTTP header fields when putting the entity or modifying | |
242 | it using POST method. If set, these attributes will return as | |
243 | HTTP fields when doing GET/HEAD on the entity. | |
244 | ||
245 | :Type: String | |
246 | :Default: None | |
247 | :Example: "content_foo, content_bar, x-foo-bar" | |
248 | ||
249 | ||
250 | ``rgw exit timeout secs`` | |
251 | ||
252 | :Description: Number of seconds to wait for a process before exiting | |
253 | unconditionally. | |
254 | ||
255 | :Type: Integer | |
256 | :Default: ``120`` | |
257 | ||
258 | ||
259 | ``rgw get obj window size`` | |
260 | ||
261 | :Description: The window size in bytes for a single object request. | |
262 | :Type: Integer | |
263 | :Default: ``16 << 20`` | |
264 | ||
265 | ||
266 | ``rgw get obj max req size`` | |
267 | ||
268 | :Description: The maximum request size of a single get operation sent to the | |
269 | Ceph Storage Cluster. | |
270 | ||
271 | :Type: Integer | |
272 | :Default: ``4 << 20`` | |
273 | ||
274 | ||
275 | ``rgw relaxed s3 bucket names`` | |
276 | ||
277 | :Description: Enables relaxed S3 bucket names rules for US region buckets. | |
278 | :Type: Boolean | |
279 | :Default: ``false`` | |
280 | ||
281 | ||
282 | ``rgw list buckets max chunk`` | |
283 | ||
284 | :Description: The maximum number of buckets to retrieve in a single operation | |
285 | when listing user buckets. | |
286 | ||
287 | :Type: Integer | |
288 | :Default: ``1000`` | |
289 | ||
290 | ||
291 | ``rgw override bucket index max shards`` | |
292 | ||
293 | :Description: Represents the number of shards for the bucket index object, | |
294 | a value of zero indicates there is no sharding. It is not | |
295 | recommended to set a value too large (e.g. thousand) as it | |
296 | increases the cost for bucket listing. | |
297 | ||
298 | :Type: Integer | |
299 | :Default: ``0`` | |
300 | ||
301 | ||
302 | ``rgw num zone opstate shards`` | |
303 | ||
304 | :Description: The maximum number of shards for keeping inter-region copy | |
305 | progress information. | |
306 | ||
307 | :Type: Integer | |
308 | :Default: ``128`` | |
309 | ||
310 | ||
311 | ``rgw opstate ratelimit sec`` | |
312 | ||
313 | :Description: The minimum time between opstate updates on a single upload. | |
314 | ``0`` disables the ratelimit. | |
315 | ||
316 | :Type: Integer | |
317 | :Default: ``30`` | |
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 default quota max objects`` | |
356 | ||
357 | :Description: Default max number of objects per bucket. Set on new users, | |
358 | if no other quota is specified. Has no effect on existing users. | |
359 | :Type: Integer | |
360 | :Default: ``-1`` | |
361 | ||
362 | ||
363 | ``rgw bucket default quota max size`` | |
364 | ||
365 | :Description: Default max capacity per bucket, in bytes. Set on new users, | |
366 | if no other quota is specified. Has no effect on existing users. | |
367 | :Type: Integer | |
368 | :Default: ``-1`` | |
369 | ||
370 | ||
371 | ``rgw user default quota max objects`` | |
372 | ||
373 | :Description: Default max number of objects for a user. This includes all | |
374 | objects in all buckets owned by the user. Set on new users, | |
375 | if no other quota is specified. Has no effect on existing users. | |
376 | :Type: Integer | |
377 | :Default: ``-1`` | |
378 | ||
379 | ||
380 | ``rgw user default quota max size`` | |
381 | ||
382 | :Description: The value for user max size quota in bytes set on new users, | |
383 | if no other quota is specified. Has no effect on existing users. | |
384 | :Type: Integer | |
385 | :Default: ``-1`` | |
386 | ||
387 | ||
388 | Regions | |
389 | ======= | |
390 | ||
391 | In Ceph v0.67 and beyond, Ceph Object Gateway supports federated deployments and | |
392 | a global namespace via the notion of regions. A region defines the geographic | |
393 | location of one or more Ceph Object Gateway instances within one or more zones. | |
394 | ||
395 | ||
396 | Configuring regions differs from typical configuration procedures, because not | |
397 | all of the settings end up in a Ceph configuration file. In Ceph v0.67 and | |
398 | beyond, you can list regions, get a region configuration and set a region | |
399 | configuration. | |
400 | ||
401 | ||
402 | List Regions | |
403 | ------------ | |
404 | ||
405 | A Ceph cluster contains a list of regions. To list the regions, execute:: | |
406 | ||
407 | sudo radosgw-admin region list | |
408 | ||
409 | The ``radosgw-admin`` returns a JSON formatted list of regions. | |
410 | ||
411 | .. code-block:: javascript | |
412 | ||
413 | { "default_info": { "default_region": "default"}, | |
414 | "regions": [ | |
415 | "default"]} | |
416 | ||
417 | ||
418 | Get a Region Map | |
419 | ---------------- | |
420 | ||
421 | To list the details of each region, execute:: | |
422 | ||
423 | sudo radosgw-admin region-map get | |
424 | ||
425 | ||
426 | .. note:: If you receive a ``failed to read region map`` error, run | |
427 | ``sudo radosgw-admin region-map update`` first. | |
428 | ||
429 | ||
430 | Get a Region | |
431 | ------------ | |
432 | ||
433 | To view the configuration of a region, execute:: | |
434 | ||
435 | radosgw-admin region get [--rgw-region=<region>] | |
436 | ||
437 | The ``default`` region looks like this: | |
438 | ||
439 | .. code-block:: javascript | |
440 | ||
441 | {"name": "default", | |
442 | "api_name": "", | |
443 | "is_master": "true", | |
444 | "endpoints": [], | |
445 | "hostnames": [], | |
446 | "master_zone": "", | |
447 | "zones": [ | |
448 | {"name": "default", | |
449 | "endpoints": [], | |
450 | "log_meta": "false", | |
451 | "log_data": "false"} | |
452 | ], | |
453 | "placement_targets": [ | |
454 | {"name": "default-placement", | |
455 | "tags": [] }], | |
456 | "default_placement": "default-placement"} | |
457 | ||
458 | Set a Region | |
459 | ------------ | |
460 | ||
461 | Defining a region consists of creating a JSON object, specifying at least the | |
462 | required settings: | |
463 | ||
464 | #. ``name``: The name of the region. Required. | |
465 | ||
466 | #. ``api_name``: The API name for the region. Optional. | |
467 | ||
468 | #. ``is_master``: Determines if the region is the master region. Required. | |
469 | **note:** You can only have one master region. | |
470 | ||
471 | #. ``endpoints``: A list of all the endpoints in the region. For example, | |
472 | you may use multiple domain names to refer to the same region. Remember to | |
473 | escape the forward slashes (``\/``). You may also specify a | |
474 | port (``fqdn:port``) for each endpoint. Optional. | |
475 | ||
476 | #. ``hostnames``: A list of all the hostnames in the region. For example, | |
477 | you may use multiple domain names to refer to the same region. Optional. | |
478 | The ``rgw dns name`` setting will automatically be included in this list. | |
479 | You should restart the ``radosgw`` daemon(s) after changing this setting. | |
480 | ||
481 | #. ``master_zone``: The master zone for the region. Optional. Uses the default | |
482 | zone if not specified. **note:** You can only have one master zone per | |
483 | region. | |
484 | ||
485 | #. ``zones``: A list of all zones within the region. Each zone has a | |
486 | name (required), a list of endpoints (optional), and whether or not the | |
487 | gateway will log metadata and data operations (false by default). | |
488 | ||
489 | #. ``placement_targets``: A list of placement targets (optional). Each | |
490 | placement target contains a name (required) for the placement target | |
491 | and a list of tags (optional) so that only users with the tag can use | |
492 | the placement target (i.e., the user's ``placement_tags`` field in the | |
493 | user info). | |
494 | ||
495 | #. ``default_placement``: The default placement target for the object | |
496 | index and object data. Set to ``default-placement`` by default. You | |
497 | may also set a per-user default placement in the user info for each | |
498 | user. | |
499 | ||
500 | To set a region, create a JSON object consisting of the required fields, save | |
501 | the object to a file (e.g., ``region.json``); then, execute the following | |
502 | command:: | |
503 | ||
504 | sudo radosgw-admin region set --infile region.json | |
505 | ||
506 | Where ``region.json`` is the JSON file you created. | |
507 | ||
508 | ||
509 | .. important:: The ``default`` region ``is_master`` setting is ``true`` by | |
510 | default. If you create a new region and want to make it the master region, | |
511 | you must either set the ``default`` region ``is_master`` setting to | |
512 | ``false``, or delete the ``default`` region. | |
513 | ||
514 | ||
515 | Finally, update the map. :: | |
516 | ||
517 | sudo radosgw-admin region-map update | |
518 | ||
519 | ||
520 | Set a Region Map | |
521 | ---------------- | |
522 | ||
523 | Setting a region map consists of creating a JSON object consisting of one or more | |
524 | regions, and setting the ``master_region`` for the cluster. Each region in the | |
525 | region map consists of a key/value pair, where the ``key`` setting is equivalent to | |
526 | the ``name`` setting for an individual region configuration, and the ``val`` is | |
527 | a JSON object consisting of an individual region configuration. | |
528 | ||
529 | You may only have one region with ``is_master`` equal to ``true``, and it must be | |
530 | specified as the ``master_region`` at the end of the region map. The following | |
531 | JSON object is an example of a default region map. | |
532 | ||
533 | ||
534 | .. code-block:: javascript | |
535 | ||
536 | { "regions": [ | |
537 | { "key": "default", | |
538 | "val": { "name": "default", | |
539 | "api_name": "", | |
540 | "is_master": "true", | |
541 | "endpoints": [], | |
542 | "hostnames": [], | |
543 | "master_zone": "", | |
544 | "zones": [ | |
545 | { "name": "default", | |
546 | "endpoints": [], | |
547 | "log_meta": "false", | |
548 | "log_data": "false"}], | |
549 | "placement_targets": [ | |
550 | { "name": "default-placement", | |
551 | "tags": []}], | |
552 | "default_placement": "default-placement" | |
553 | } | |
554 | } | |
555 | ], | |
556 | "master_region": "default" | |
557 | } | |
558 | ||
559 | To set a region map, execute the following:: | |
560 | ||
561 | sudo radosgw-admin region-map set --infile regionmap.json | |
562 | ||
563 | Where ``regionmap.json`` is the JSON file you created. Ensure that you have | |
564 | zones created for the ones specified in the region map. Finally, update the map. | |
565 | :: | |
566 | ||
567 | sudo radosgw-admin regionmap update | |
568 | ||
569 | ||
570 | Zones | |
571 | ===== | |
572 | ||
573 | In Ceph v0.67 and beyond, Ceph Object Gateway supports the notion of zones. A | |
574 | zone defines a logical group consisting of one or more Ceph Object Gateway | |
575 | instances. | |
576 | ||
577 | Configuring zones differs from typical configuration procedures, because not | |
578 | all of the settings end up in a Ceph configuration file. In Ceph v0.67 and | |
579 | beyond, you can list zones, get a zone configuration and set a zone | |
580 | configuration. | |
581 | ||
582 | ||
583 | List Zones | |
584 | ---------- | |
585 | ||
586 | To list the zones in a cluster, execute:: | |
587 | ||
588 | sudo radosgw-admin zone list | |
589 | ||
590 | ||
591 | Get a Zone | |
592 | ---------- | |
593 | ||
594 | To get the configuration of a zone, execute:: | |
595 | ||
596 | sudo radosgw-admin zone get [--rgw-zone=<zone>] | |
597 | ||
598 | The ``default`` zone looks like this: | |
599 | ||
600 | .. code-block:: javascript | |
601 | ||
602 | { "domain_root": ".rgw", | |
603 | "control_pool": ".rgw.control", | |
604 | "gc_pool": ".rgw.gc", | |
605 | "log_pool": ".log", | |
606 | "intent_log_pool": ".intent-log", | |
607 | "usage_log_pool": ".usage", | |
608 | "user_keys_pool": ".users", | |
609 | "user_email_pool": ".users.email", | |
610 | "user_swift_pool": ".users.swift", | |
611 | "user_uid_pool": ".users.uid", | |
612 | "system_key": { "access_key": "", "secret_key": ""}, | |
613 | "placement_pools": [ | |
614 | { "key": "default-placement", | |
615 | "val": { "index_pool": ".rgw.buckets.index", | |
616 | "data_pool": ".rgw.buckets"} | |
617 | } | |
618 | ] | |
619 | } | |
620 | ||
621 | ||
622 | Set a Zone | |
623 | ---------- | |
624 | ||
625 | Configuring a zone involves specifying a series of Ceph Object Gateway pools. | |
626 | For consistency, we recommend using a pool prefix that is | |
627 | the same as the zone name. See `Pools`_ for details of configuring pools. | |
628 | ||
629 | To set a zone, create a JSON object consisting of the pools, save | |
630 | the object to a file (e.g., ``zone.json``); then, execute the following | |
631 | command, replacing ``{zone-name}`` with the name of the zone:: | |
632 | ||
633 | sudo radosgw-admin zone set --rgw-zone={zone-name} --infile zone.json | |
634 | ||
635 | Where ``zone.json`` is the JSON file you created. | |
636 | ||
637 | ||
638 | Region/Zone Settings | |
639 | ==================== | |
640 | ||
641 | You may include the following settings in your Ceph configuration | |
642 | file under each ``[client.radosgw.{instance-name}]`` instance. | |
643 | ||
644 | ||
645 | .. versionadded:: v.67 | |
646 | ||
647 | ``rgw zone`` | |
648 | ||
649 | :Description: The name of the zone for the gateway instance. | |
650 | :Type: String | |
651 | :Default: None | |
652 | ||
653 | ||
654 | .. versionadded:: v.67 | |
655 | ||
656 | ``rgw region`` | |
657 | ||
658 | :Description: The name of the region for the gateway instance. | |
659 | :Type: String | |
660 | :Default: None | |
661 | ||
662 | ||
663 | .. versionadded:: v.67 | |
664 | ||
665 | ``rgw default region info oid`` | |
666 | ||
667 | :Description: The OID for storing the default region. We do not recommend | |
668 | changing this setting. | |
669 | ||
670 | :Type: String | |
671 | :Default: ``default.region`` | |
672 | ||
673 | ||
674 | ||
675 | Pools | |
676 | ===== | |
677 | ||
678 | Ceph zones map to a series of Ceph Storage Cluster pools. | |
679 | ||
680 | .. topic:: Manually Created Pools vs. Generated Pools | |
681 | ||
682 | If you provide write capabilities to the user key for your Ceph Object | |
683 | Gateway, the gateway has the ability to create pools automatically. This | |
684 | is convenient, but the Ceph Object Storage Cluster uses the default | |
685 | values for the number of placement groups (which may not be ideal) or the | |
686 | values you specified in your Ceph configuration file. If you allow the | |
687 | Ceph Object Gateway to create pools automatically, ensure that you have | |
688 | reasonable defaults for the number of placement groups. See | |
689 | `Pool Configuration`_ for details. See `Cluster Pools`_ for details on | |
690 | creating pools. | |
691 | ||
692 | The default pools for the Ceph Object Gateway's default zone include: | |
693 | ||
694 | - ``.rgw`` | |
695 | - ``.rgw.control`` | |
696 | - ``.rgw.gc`` | |
697 | - ``.log`` | |
698 | - ``.intent-log`` | |
699 | - ``.usage`` | |
700 | - ``.users`` | |
701 | - ``.users.email`` | |
702 | - ``.users.swift`` | |
703 | - ``.users.uid`` | |
704 | ||
705 | You have significant discretion in determining how you want a zone to access | |
706 | pools. You can create pools on a per zone basis, or use the same pools for | |
707 | multiple zones. As a best practice, we recommend having a separate set of pools | |
708 | for your master zone and your secondary zones in each region. When creating | |
709 | pools for a specific zone, consider prepending the region name and zone name to | |
710 | the default pool names. For example: | |
711 | ||
712 | - ``.region1-zone1.domain.rgw`` | |
713 | - ``.region1-zone1.rgw.control`` | |
714 | - ``.region1-zone1.rgw.gc`` | |
715 | - ``.region1-zone1.log`` | |
716 | - ``.region1-zone1.intent-log`` | |
717 | - ``.region1-zone1.usage`` | |
718 | - ``.region1-zone1.users`` | |
719 | - ``.region1-zone1.users.email`` | |
720 | - ``.region1-zone1.users.swift`` | |
721 | - ``.region1-zone1.users.uid`` | |
722 | ||
723 | ||
724 | Ceph Object Gateways store data for the bucket index (``index_pool``) and bucket | |
725 | data (``data_pool``) in placement pools. These may overlap--i.e., you may use | |
726 | the same pool for the index and the data. The index pool for default | |
727 | placement is ``.rgw.buckets.index`` and for the data pool for default placement | |
728 | is ``.rgw.buckets``. See `Zones`_ for details on specifying pools in a zone | |
729 | configuration. | |
730 | ||
731 | ||
732 | .. deprecated:: v.67 | |
733 | ||
734 | ``rgw cluster root pool`` | |
735 | ||
736 | :Description: The Ceph Storage Cluster pool to store ``radosgw`` metadata for | |
737 | this instance. Not used in Ceph version v.67 and later. Use | |
738 | ``rgw zone root pool`` instead. | |
739 | ||
740 | :Type: String | |
741 | :Required: No | |
742 | :Default: ``.rgw.root`` | |
743 | :Replaced By: ``rgw zone root pool`` | |
744 | ||
745 | ||
746 | .. versionadded:: v.67 | |
747 | ||
748 | ``rgw region root pool`` | |
749 | ||
750 | :Description: The pool for storing all region-specific information. | |
751 | Not used in Ceph version ``Jewel``. | |
752 | :Type: String | |
753 | :Default: ``.rgw.root`` | |
754 | ||
755 | .. versionadded:: Jewel | |
756 | ||
757 | ``rgw zonegroup root pool`` | |
758 | ||
759 | :Description: The pool for storing all zonegroup-specific information. | |
760 | :Type: String | |
761 | :Default: ``.rgw.root`` | |
762 | ||
763 | ||
764 | .. versionadded:: v.67 | |
765 | ||
766 | ``rgw zone root pool`` | |
767 | ||
768 | :Description: The pool for storing zone-specific information. | |
769 | :Type: String | |
770 | :Default: ``.rgw.root`` | |
771 | ||
772 | ||
773 | Swift Settings | |
774 | ============== | |
775 | ||
776 | ``rgw enforce swift acls`` | |
777 | ||
778 | :Description: Enforces the Swift Access Control List (ACL) settings. | |
779 | :Type: Boolean | |
780 | :Default: ``true`` | |
781 | ||
782 | ||
783 | ``rgw swift token expiration`` | |
784 | ||
785 | :Description: The time in seconds for expiring a Swift token. | |
786 | :Type: Integer | |
787 | :Default: ``24 * 3600`` | |
788 | ||
789 | ||
790 | ``rgw swift url`` | |
791 | ||
792 | :Description: The URL for the Ceph Object Gateway Swift API. | |
793 | :Type: String | |
794 | :Default: None | |
795 | ||
796 | ||
797 | ``rgw swift url prefix`` | |
798 | ||
799 | :Description: The URL prefix for the Swift StorageURL that goes in front of | |
800 | the "/v1" part. This allows to run several Gateway instances | |
801 | on the same host. For compatibility, setting this configuration | |
802 | variable to empty causes the default "/swift" to be used. | |
803 | Use explicit prefix "/" to start StorageURL at the root. | |
804 | WARNING: setting this option to "/" will NOT work if S3 API is | |
805 | enabled. From the other side disabling S3 will make impossible | |
806 | to deploy RadosGW in the multi-site configuration! | |
807 | :Default: ``swift`` | |
808 | :Example: "/swift-testing" | |
809 | ||
810 | ||
811 | ``rgw swift auth url`` | |
812 | ||
813 | :Description: Default URL for verifying v1 auth tokens (if not using internal | |
814 | Swift auth). | |
815 | ||
816 | :Type: String | |
817 | :Default: None | |
818 | ||
819 | ||
820 | ``rgw swift auth entry`` | |
821 | ||
822 | :Description: The entry point for a Swift auth URL. | |
823 | :Type: String | |
824 | :Default: ``auth`` | |
825 | ||
826 | ||
827 | ``rgw swift versioning enabled`` | |
828 | ||
829 | :Description: Enables the Object Versioning of OpenStack Object Storage API. | |
830 | This allows clients to put the ``X-Versions-Location`` attribute | |
831 | on containers that should be versioned. The attribute specifies | |
832 | the name of container storing archived versions. It must be owned | |
833 | by the same user that the versioned container due to access | |
834 | control verification - ACLs are NOT taken into consideration. | |
835 | Those containers cannot be versioned by the S3 object versioning | |
836 | mechanism. | |
837 | :Type: Boolean | |
838 | :Default: ``false`` | |
839 | ||
840 | ||
841 | ||
842 | Logging Settings | |
843 | ================ | |
844 | ||
845 | ||
846 | ``rgw log nonexistent bucket`` | |
847 | ||
848 | :Description: Enables Ceph Object Gateway to log a request for a non-existent | |
849 | bucket. | |
850 | ||
851 | :Type: Boolean | |
852 | :Default: ``false`` | |
853 | ||
854 | ||
855 | ``rgw log object name`` | |
856 | ||
857 | :Description: The logging format for an object name. See manpage | |
858 | :manpage:`date` for details about format specifiers. | |
859 | ||
860 | :Type: Date | |
861 | :Default: ``%Y-%m-%d-%H-%i-%n`` | |
862 | ||
863 | ||
864 | ``rgw log object name utc`` | |
865 | ||
866 | :Description: Whether a logged object name includes a UTC time. | |
867 | If ``false``, it uses the local time. | |
868 | ||
869 | :Type: Boolean | |
870 | :Default: ``false`` | |
871 | ||
872 | ||
873 | ``rgw usage max shards`` | |
874 | ||
875 | :Description: The maximum number of shards for usage logging. | |
876 | :Type: Integer | |
877 | :Default: ``32`` | |
878 | ||
879 | ||
880 | ``rgw usage max user shards`` | |
881 | ||
882 | :Description: The maximum number of shards used for a single user's | |
883 | usage logging. | |
884 | ||
885 | :Type: Integer | |
886 | :Default: ``1`` | |
887 | ||
888 | ||
889 | ``rgw enable ops log`` | |
890 | ||
891 | :Description: Enable logging for each successful Ceph Object Gateway operation. | |
892 | :Type: Boolean | |
893 | :Default: ``false`` | |
894 | ||
895 | ||
896 | ``rgw enable usage log`` | |
897 | ||
898 | :Description: Enable the usage log. | |
899 | :Type: Boolean | |
900 | :Default: ``false`` | |
901 | ||
902 | ||
903 | ``rgw ops log rados`` | |
904 | ||
905 | :Description: Whether the operations log should be written to the | |
906 | Ceph Storage Cluster backend. | |
907 | ||
908 | :Type: Boolean | |
909 | :Default: ``true`` | |
910 | ||
911 | ||
912 | ``rgw ops log socket path`` | |
913 | ||
914 | :Description: The Unix domain socket for writing operations logs. | |
915 | :Type: String | |
916 | :Default: None | |
917 | ||
918 | ||
919 | ``rgw ops log data backlog`` | |
920 | ||
921 | :Description: The maximum data backlog data size for operations logs written | |
922 | to a Unix domain socket. | |
923 | ||
924 | :Type: Integer | |
925 | :Default: ``5 << 20`` | |
926 | ||
927 | ||
928 | ``rgw usage log flush threshold`` | |
929 | ||
930 | :Description: The number of dirty merged entries in the usage log before | |
931 | flushing synchronously. | |
932 | ||
933 | :Type: Integer | |
934 | :Default: 1024 | |
935 | ||
936 | ||
937 | ``rgw usage log tick interval`` | |
938 | ||
939 | :Description: Flush pending usage log data every ``n`` seconds. | |
940 | :Type: Integer | |
941 | :Default: ``30`` | |
942 | ||
943 | ||
944 | ``rgw log http headers`` | |
945 | ||
946 | :Description: Comma-delimited list of HTTP headers to include with ops | |
947 | log entries. Header names are case insensitive, and use | |
948 | the full header name with words separated by underscores. | |
949 | ||
950 | :Type: String | |
951 | :Default: None | |
952 | :Example: "http_x_forwarded_for, http_x_special_k" | |
953 | ||
954 | ||
955 | ``rgw intent log object name`` | |
956 | ||
957 | :Description: The logging format for the intent log object name. See manpage | |
958 | :manpage:`date` for details about format specifiers. | |
959 | ||
960 | :Type: Date | |
961 | :Default: ``%Y-%m-%d-%i-%n`` | |
962 | ||
963 | ||
964 | ``rgw intent log object name utc`` | |
965 | ||
966 | :Description: Whether the intent log object name includes a UTC time. | |
967 | If ``false``, it uses the local time. | |
968 | ||
969 | :Type: Boolean | |
970 | :Default: ``false`` | |
971 | ||
972 | ||
973 | ``rgw data log window`` | |
974 | ||
975 | :Description: The data log entries window in seconds. | |
976 | :Type: Integer | |
977 | :Default: ``30`` | |
978 | ||
979 | ||
980 | ``rgw data log changes size`` | |
981 | ||
982 | :Description: The number of in-memory entries to hold for the data changes log. | |
983 | :Type: Integer | |
984 | :Default: ``1000`` | |
985 | ||
986 | ||
987 | ``rgw data log num shards`` | |
988 | ||
989 | :Description: The number of shards (objects) on which to keep the | |
990 | data changes log. | |
991 | ||
992 | :Type: Integer | |
993 | :Default: ``128`` | |
994 | ||
995 | ||
996 | ``rgw data log obj prefix`` | |
997 | ||
998 | :Description: The object name prefix for the data log. | |
999 | :Type: String | |
1000 | :Default: ``data_log`` | |
1001 | ||
1002 | ||
1003 | ``rgw replica log obj prefix`` | |
1004 | ||
1005 | :Description: The object name prefix for the replica log. | |
1006 | :Type: String | |
1007 | :Default: ``replica log`` | |
1008 | ||
1009 | ||
1010 | ``rgw md log max shards`` | |
1011 | ||
1012 | :Description: The maximum number of shards for the metadata log. | |
1013 | :Type: Integer | |
1014 | :Default: ``64`` | |
1015 | ||
1016 | ||
1017 | ||
1018 | Keystone Settings | |
1019 | ================= | |
1020 | ||
1021 | ||
1022 | ``rgw keystone url`` | |
1023 | ||
1024 | :Description: The URL for the Keystone server. | |
1025 | :Type: String | |
1026 | :Default: None | |
1027 | ||
1028 | ||
1029 | ``rgw keystone api version`` | |
1030 | ||
1031 | :Description: The version (2 or 3) of OpenStack Identity API that should be | |
1032 | used for communication with the Keystone server. | |
1033 | :Type: Integer | |
1034 | :Default: ``2`` | |
1035 | ||
1036 | ||
1037 | ``rgw keystone admin domain`` | |
1038 | ||
1039 | :Description: The name of OpenStack domain with admin privilege when using | |
1040 | OpenStack Identity API v3. | |
1041 | :Type: String | |
1042 | :Default: None | |
1043 | ||
1044 | ||
1045 | ``rgw keystone admin project`` | |
1046 | ||
1047 | :Description: The name of OpenStack project with admin privilege when using | |
1048 | OpenStack Identity API v3. If left unspecified, value of | |
1049 | ``rgw keystone admin tenant`` will be used instead. | |
1050 | :Type: String | |
1051 | :Default: None | |
1052 | ||
1053 | ||
1054 | ``rgw keystone admin token`` | |
1055 | ||
1056 | :Description: The Keystone admin token (shared secret). In Ceph RadosGW | |
1057 | authentication with the admin token has priority over | |
1058 | authentication with the admin credentials | |
1059 | (``rgw keystone admin user``, ``rgw keystone admin password``, | |
1060 | ``rgw keystone admin tenant``, ``rgw keystone admin project``, | |
1061 | ``rgw keystone admin domain``). Admin token feature is considered | |
1062 | as deprecated. | |
1063 | :Type: String | |
1064 | :Default: None | |
1065 | ||
1066 | ||
1067 | ``rgw keystone admin tenant`` | |
1068 | ||
1069 | :Description: The name of OpenStack tenant with admin privilege (Service Tenant) when | |
1070 | using OpenStack Identity API v2 | |
1071 | :Type: String | |
1072 | :Default: None | |
1073 | ||
1074 | ||
1075 | ``rgw keystone admin user`` | |
1076 | ||
1077 | :Description: The name of OpenStack user with admin privilege for Keystone | |
1078 | authentication (Service User) when OpenStack Identity API v2 | |
1079 | :Type: String | |
1080 | :Default: None | |
1081 | ||
1082 | ||
1083 | ``rgw keystone admin password`` | |
1084 | ||
1085 | :Description: The password for OpenStack admin user when using OpenStack | |
1086 | Identity API v2 | |
1087 | :Type: String | |
1088 | :Default: None | |
1089 | ||
1090 | ||
1091 | ``rgw keystone accepted roles`` | |
1092 | ||
1093 | :Description: The roles requires to serve requests. | |
1094 | :Type: String | |
1095 | :Default: ``Member, admin`` | |
1096 | ||
1097 | ||
1098 | ``rgw keystone token cache size`` | |
1099 | ||
1100 | :Description: The maximum number of entries in each Keystone token cache. | |
1101 | :Type: Integer | |
1102 | :Default: ``10000`` | |
1103 | ||
1104 | ||
1105 | ``rgw keystone revocation interval`` | |
1106 | ||
1107 | :Description: The number of seconds between token revocation checks. | |
1108 | :Type: Integer | |
1109 | :Default: ``15 * 60`` | |
1110 | ||
1111 | ||
1112 | ``rgw keystone verify ssl`` | |
1113 | ||
1114 | :Description: Verify SSL certificates while making token requests to keystone. | |
1115 | :Type: Boolean | |
1116 | :Default: ``true`` | |
1117 | ||
1118 | Barbican Settings | |
1119 | ================= | |
1120 | ||
1121 | ``rgw barbican url`` | |
1122 | ||
1123 | :Description: The URL for the Barbican server. | |
1124 | :Type: String | |
1125 | :Default: None | |
1126 | ||
1127 | ``rgw keystone barbican user`` | |
1128 | ||
1129 | :Description: The name of the OpenStack user with access to the `Barbican`_ | |
1130 | secrets used for `Encryption`_. | |
1131 | :Type: String | |
1132 | :Default: None | |
1133 | ||
1134 | ``rgw keystone barbican password`` | |
1135 | ||
1136 | :Description: The password associated with the `Barbican`_ user. | |
1137 | :Type: String | |
1138 | :Default: None | |
1139 | ||
1140 | ``rgw keystone barbican tenant`` | |
1141 | ||
1142 | :Description: The name of the OpenStack tenant associated with the `Barbican`_ | |
1143 | user when using OpenStack Identity API v2. | |
1144 | :Type: String | |
1145 | :Default: None | |
1146 | ||
1147 | ``rgw keystone barbican project`` | |
1148 | ||
1149 | :Description: The name of the OpenStack project associated with the `Barbican`_ | |
1150 | user when using OpenStack Identity API v3. | |
1151 | :Type: String | |
1152 | :Default: None | |
1153 | ||
1154 | ``rgw keystone barbican domain`` | |
1155 | ||
1156 | :Description: The name of the OpenStack domain associated with the `Barbican`_ | |
1157 | user when using OpenStack Identity API v3. | |
1158 | :Type: String | |
1159 | :Default: None | |
1160 | ||
1161 | ||
1162 | .. _Architecture: ../../architecture#data-striping | |
1163 | .. _Pool Configuration: ../../rados/configuration/pool-pg-config-ref/ | |
1164 | .. _Cluster Pools: ../../rados/operations/pools | |
1165 | .. _Rados cluster handles: ../../rados/api/librados-intro/#step-2-configuring-a-cluster-handle | |
1166 | .. _Barbican: ../barbican | |
1167 | .. _Encryption: ../encryption |