[ceph.git] / ceph / doc / rbd / rbd-config-ref.rst

=======================
 librbd Settings
=======================

See `Block Device`_ for additional details.

Cache Settings
=======================

.. sidebar:: Kernel Caching

	The kernel driver for Ceph block devices can use the Linux page cache to 
	improve performance.

The user space implementation of the Ceph block device (i.e., ``librbd``) cannot
take advantage of the Linux page cache, so it includes its own in-memory
caching, called "RBD caching." RBD caching behaves just like well-behaved hard
disk caching.  When the OS sends a barrier or a flush request, all dirty data is
written to the OSDs. This means that using write-back caching is just as safe as
using a well-behaved physical hard disk with a VM that properly sends flushes
(i.e. Linux kernel >= 2.6.32). The cache uses a Least Recently Used (LRU)
algorithm, and in write-back mode it  can coalesce contiguous requests for
better throughput.

.. versionadded:: 0.46

Ceph supports write-back caching for RBD. To enable it, add  ``rbd cache =
true`` to the ``[client]`` section of your ``ceph.conf`` file. By default
``librbd`` does not perform any caching. Writes and reads go directly to the
storage cluster, and writes return only when the data is on disk on all
replicas. With caching enabled, writes return immediately, unless there are more
than ``rbd cache max dirty`` unflushed bytes. In this case, the write triggers
writeback and blocks until enough bytes are flushed.

.. versionadded:: 0.47

Ceph supports write-through caching for RBD. You can set the size of
the cache, and you can set targets and limits to switch from
write-back caching to write through caching. To enable write-through
mode, set ``rbd cache max dirty`` to 0. This means writes return only
when the data is on disk on all replicas, but reads may come from the
cache. The cache is in memory on the client, and each RBD image has
its own.  Since the cache is local to the client, there's no coherency
if there are others accessing the image. Running GFS or OCFS on top of
RBD will not work with caching enabled.

The ``ceph.conf`` file settings for RBD should be set in the ``[client]``
section of your configuration file. The settings include: 


``rbd cache``

:Description: Enable caching for RADOS Block Device (RBD).
:Type: Boolean
:Required: No
:Default: ``true``


``rbd cache size``

:Description: The RBD cache size in bytes.
:Type: 64-bit Integer
:Required: No
:Default: ``32 MiB``


``rbd cache max dirty``

:Description: The ``dirty`` limit in bytes at which the cache triggers write-back.  If ``0``, uses write-through caching.
:Type: 64-bit Integer
:Required: No
:Constraint: Must be less than ``rbd cache size``.
:Default: ``24 MiB``


``rbd cache target dirty``

:Description: The ``dirty target`` before the cache begins writing data to the data storage. Does not block writes to the cache.
:Type: 64-bit Integer
:Required: No
:Constraint: Must be less than ``rbd cache max dirty``.
:Default: ``16 MiB``


``rbd cache max dirty age``

:Description: The number of seconds dirty data is in the cache before writeback starts. 
:Type: Float
:Required: No
:Default: ``1.0``

.. versionadded:: 0.60

``rbd cache writethrough until flush``

:Description: Start out in write-through mode, and switch to write-back after the first flush request is received. Enabling this is a conservative but safe setting in case VMs running on rbd are too old to send flushes, like the virtio driver in Linux before 2.6.32.
:Type: Boolean
:Required: No
:Default: ``true``

.. _Block Device: ../../rbd


Read-ahead Settings
=======================

.. versionadded:: 0.86

RBD supports read-ahead/prefetching to optimize small, sequential reads.
This should normally be handled by the guest OS in the case of a VM,
but boot loaders may not issue efficient reads.
Read-ahead is automatically disabled if caching is disabled.


``rbd readahead trigger requests``

:Description: Number of sequential read requests necessary to trigger read-ahead.
:Type: Integer
:Required: No
:Default: ``10``


``rbd readahead max bytes``

:Description: Maximum size of a read-ahead request.  If zero, read-ahead is disabled.
:Type: 64-bit Integer
:Required: No
:Default: ``512 KiB``


``rbd readahead disable after bytes``

:Description: After this many bytes have been read from an RBD image, read-ahead is disabled for that image until it is closed.  This allows the guest OS to take over read-ahead once it is booted.  If zero, read-ahead stays enabled.
:Type: 64-bit Integer
:Required: No
:Default: ``50 MiB``
Commit	Line	Data
7c673cae FG	1	=======================
	2	librbd Settings
	3	=======================
	4
	5	See `Block Device`_ for additional details.
	6
	7	Cache Settings
	8	=======================
	9
	10	.. sidebar:: Kernel Caching
	11
	12	The kernel driver for Ceph block devices can use the Linux page cache to
	13	improve performance.
	14
	15	The user space implementation of the Ceph block device (i.e., ``librbd``) cannot
	16	take advantage of the Linux page cache, so it includes its own in-memory
	17	caching, called "RBD caching." RBD caching behaves just like well-behaved hard
	18	disk caching. When the OS sends a barrier or a flush request, all dirty data is
	19	written to the OSDs. This means that using write-back caching is just as safe as
	20	using a well-behaved physical hard disk with a VM that properly sends flushes
	21	(i.e. Linux kernel >= 2.6.32). The cache uses a Least Recently Used (LRU)
	22	algorithm, and in write-back mode it can coalesce contiguous requests for
	23	better throughput.
	24
	25	.. versionadded:: 0.46
	26
	27	Ceph supports write-back caching for RBD. To enable it, add ``rbd cache =
	28	true`` to the ``[client]`` section of your ``ceph.conf`` file. By default
	29	``librbd`` does not perform any caching. Writes and reads go directly to the
	30	storage cluster, and writes return only when the data is on disk on all
	31	replicas. With caching enabled, writes return immediately, unless there are more
	32	than ``rbd cache max dirty`` unflushed bytes. In this case, the write triggers
	33	writeback and blocks until enough bytes are flushed.
	34
	35	.. versionadded:: 0.47
	36
	37	Ceph supports write-through caching for RBD. You can set the size of
	38	the cache, and you can set targets and limits to switch from
	39	write-back caching to write through caching. To enable write-through
	40	mode, set ``rbd cache max dirty`` to 0. This means writes return only
	41	when the data is on disk on all replicas, but reads may come from the
	42	cache. The cache is in memory on the client, and each RBD image has
	43	its own. Since the cache is local to the client, there's no coherency
	44	if there are others accessing the image. Running GFS or OCFS on top of
	45	RBD will not work with caching enabled.
	46
	47	The ``ceph.conf`` file settings for RBD should be set in the ``[client]``
	48	section of your configuration file. The settings include:
	49
	50
	51	``rbd cache``
	52
	53	:Description: Enable caching for RADOS Block Device (RBD).
	54	:Type: Boolean
	55	:Required: No
	56	:Default: ``true``
	57
	58
	59	``rbd cache size``
	60
	61	:Description: The RBD cache size in bytes.
	62	:Type: 64-bit Integer
	63	:Required: No
	64	:Default: ``32 MiB``
65
66
67	``rbd cache max dirty``
68
69	:Description: The ``dirty`` limit in bytes at which the cache triggers write-back. If ``0``, uses write-through caching.
70	:Type: 64-bit Integer
71	:Required: No
72	:Constraint: Must be less than ``rbd cache size``.
73	:Default: ``24 MiB``
74
75
76	``rbd cache target dirty``
77
78	:Description: The ``dirty target`` before the cache begins writing data to the data storage. Does not block writes to the cache.
79	:Type: 64-bit Integer
80	:Required: No
81	:Constraint: Must be less than ``rbd cache max dirty``.
82	:Default: ``16 MiB``
83
84
85	``rbd cache max dirty age``
86
87	:Description: The number of seconds dirty data is in the cache before writeback starts.
88	:Type: Float
89	:Required: No
90	:Default: ``1.0``
91
92	.. versionadded:: 0.60
93
94	``rbd cache writethrough until flush``
95
96	:Description: Start out in write-through mode, and switch to write-back after the first flush request is received. Enabling this is a conservative but safe setting in case VMs running on rbd are too old to send flushes, like the virtio driver in Linux before 2.6.32.
97	:Type: Boolean
98	:Required: No
99	:Default: ``true``
100
d2e6a577	101	.. _Block Device: ../../rbd
7c673cae FG	102
	103
	104	Read-ahead Settings
	105	=======================
	106
	107	.. versionadded:: 0.86
	108
	109	RBD supports read-ahead/prefetching to optimize small, sequential reads.
	110	This should normally be handled by the guest OS in the case of a VM,
	111	but boot loaders may not issue efficient reads.
	112	Read-ahead is automatically disabled if caching is disabled.
	113
	114
	115	``rbd readahead trigger requests``
	116
	117	:Description: Number of sequential read requests necessary to trigger read-ahead.
	118	:Type: Integer
	119	:Required: No
	120	:Default: ``10``
	121
	122
	123	``rbd readahead max bytes``
	124
	125	:Description: Maximum size of a read-ahead request. If zero, read-ahead is disabled.
	126	:Type: 64-bit Integer
	127	:Required: No
	128	:Default: ``512 KiB``
	129
	130
	131	``rbd readahead disable after bytes``
	132
	133	:Description: After this many bytes have been read from an RBD image, read-ahead is disabled for that image until it is closed. This allows the guest OS to take over read-ahead once it is booted. If zero, read-ahead stays enabled.
	134	:Type: 64-bit Integer
	135	:Required: No
	136	:Default: ``50 MiB``